Run npm run setup or yarn setup (yarn is preferred) in the root repo. The script will:
- Ensure you have the correct global dependencies installed
- Bootstrap the repo for you with yarn workspaces
The toolbox is a repo for sharing code between repositories. We can put anything in here and import it into other projects. Anything exported from exports.ts will be available in any client project with import { ComponentName } from 'toolbox';.
This will be invaluable for building up a library of reusable components, unifying approaches to data fetching, and building a handy library of hooks.
Run yarn toolbox start, and you'll see the components inside laid out in a storybook.
Run yarn generate component, to bootstrap a new component in the toolbox.
Starting new projects can be daunting. Webpack configs, frameworks, all sorts of decisions to make. The SPA boilerplate is a clean boilerplate for bootstrapping an SPA, complete with Urql, Hasura, Tailwind CSS and Typescript.
- Run
cp spa-boilerplate/.example.env spa-boilerplate/.env.localto get your environment variables. - Kick off a Hasura backend on
localhost:6060withyarn spa hasura:up. - Run
cp spa-boilerplate/hasura/config.example.yaml spa-boilerplate/hasura/config.yamlto set up using hasura from the CLI - Run
yarn spa startto start the hasura console, the react app, and kick off some helpful dev tasks.
We use graphql-codegen to automatically generate code to talk to our API. Here's how you use it:
- Run
yarn spa start. - Write some queries under
src/graphql/queries/<QueryName>.graphql - The queries will get auto-built into Urql hooks, in the same folder as the query.
An invaluable tool for unit testing, component creation, and catching regressions.
Design your UI with JSX, and save as a shareable URL. It even bundles up your component library. I envision us using it as a design process - design new pages in Playroom, share and discuss on Slack, and then just lift that code into a new view.
Generate component boilerplate easily. Run yarn generate to scaffold a new component in the Toolbox, or a new route within a client.
yarn setup
Sets up the repo, ensures you have docker installed, and installs necessary dependencies.
yarn spa
Allows you to run a script inside the spa-boilerplate package. For instance, yarn spa start is the same as yarn start inside the spa-boilerplate folder.
yarn toolbox
The same as above, but for the toolbox package.
yarn tb
An alias for yarn toolbox
yarn lint
Runs the lint command in all the workspaces. Useful for CI, or for checking if you're safe to push.
yarn codegen
Runs the codegen command in all the workspaces. Useful for autogenerating all types within a workspace.
yarn test:ci
Runs yarn test in each repo. This should usually only be run in a CI.
yarn generate
Opens a dialog to bootstrap a component or route in the repo. Too much description here is unnecessary - try it out and feel the power!
yarn pretty-staged
Runs prettier on the files you've staged for commit. This is currently set up to run every commit, with husky git hooks.
yarn version-minor / yarn version-patch
Creates a new git tag and pushes it to the remote repo. This is used when you need to create a new tag to deploy to.
The AWS Amplify toolchain (SDK and CLI) brings together various other AWS services for building mobile & web apps in a single API. Out of the box, it will give you Authentication, Serverless Functions, REST/GraphQL APIs, Offline Sync, NoSQL DB, File Storage, Logging, Analytics, Notifications, Bots, AR/VR, and more.
- Profile - this is a set of credentials, used by Amplify CLI to programmatically access an AWS account. Credentials are usually stored locally on dev machines inside ~/.aws, they should never be checked in to a git repo.
- Environment - this is a bunch of related infrastructure in AWS, usually named like git branches (e.g. prod, beta, staging, feature-test1)
- CloudFormation Template - these template files are how the Amplify CLI actually manipulates the services within AWS
- Cognito - the authentication service we use
- S3 - the storage service we use for blobs of data (files), but also used to store our frontend bundle after it is built
- CloudFront - a global CDN that serves up our bundle from S3
- Amplify Console - continuous deployment tool that builds/tests both the frontend and backend for us by watching a git repo. It deploys to S3 and invalidates any CloudFront caches where required.
- AWS Command Line Interface Profiles
- Setting up your dev workstation with the Amplify CLI
- Key Amplify Concepts
- Environments and Teams
- amplify the entire definition of our backend AWS environment, committed to git, right alongside our frontend code 🎉
- amplify/#current-cloud-backend a reflection of what is already deployed
- amplify/backend work in progress, not applied/deployed until we run
amplify push - team-provider-info.json a list describing the different backend environments (but no credentials!)
- amplify/.config mostly config that is local to your dev machine, with the exception of 'project-config.json'
- Install the generic AWS CLI tools
- Install the Amplify CLI tools -
yarn global add @aws-amplify/cliornpm i -g @aws-amplify/cli - Set up an AWS account, add an IAM user with programmatic access, and make a note of the access key & secret.
- Set up a credential profile
aws configure --profile projectname-amplify-profile, you can give the profile whatever alias you like as its local to your dev machine. It will ask for the access key & secret above. - Run
amplify initafter you checkout to choose an existing environment, or add a new one. It will ask if you want to use an existing profile (yes!). - Add or reconfigure features using the amplify CLI, or edit existing functions from within the amplify/backend folder in the repo. Test functions locally. When you are ready to apply changes to the AWS backend, run
amplify status(optional), and thenamplify push --yes.
If you change from dev to feature-new-login-page it is likely that you will be testing against the same AWS backend environment ('dev').
However, if you switch branches from dev to master your amplify CLI will still be pointing to the last backend (dev), so you need to do this:
amplify env checkout prod (where prod is the environment name).
You can see a list of environments in amplify/team-provider-info.json, or by running amplify env list. New ones can be added with amplify env add.
Even if you haven't switched branches, you should routinely run amplify env pull to overwrite the local reflection of the deployed AWS environment (stored in amplify/#current-cloud-backend). We do this just in case someone else has made changes (and given that this folder should be in .gitignore). If things ever get screwed up amplify init is usually the best recourse.