TGRS stands for TypeScript, GraphQL, React and serverless. This is a sample project that demonstrates the key technologies in this stack.
Note that this stack does not support server-side rendering (SSR) out-of-the-box. For SSR to work, you'd need to introduce an additional server layer, which would also add extra complexity to your project. If your SEO or performance needs necessitate that you use SSR, I recommend you look at a framework like Remix or Next.js. Using these frameworks may also eliminate the need for you to use GraphQL at all.
For a general overview of the stack and the decisions behind it, see Introducing the TGRS stack for web interfaces, or check out this presentation video.
-
Run
nodenv install
-
Install yarn 1.x. If you used
npm install -g yarn
to install it, make sure you subsequently run:nodenv rehash
before continuing
-
Run
yarn install
-
Start the integration environment stub REST server:
yarn workspace integration startStubby
-
Set up a server environment file that configures the server to talk to the integration environment's stub REST server:
ln -sf ./env.integration.json packages/server/env.json
-
Build the code that is shared by both the client and server:
yarn workspace shared build
-
Start the GraphQl server inside an Express instance:
yarn workspace server start
-
Set up a client environment file that configures the client to talk to the GraphQL Express server:
ln -sf ../env/localhost-4000.json packages/client/public/env.json
-
Start the client:
yarn workspace client start
-
Go to http://localhost:3000
This section assumes you have installed the AWS SAM CLI
To start the GraphQL server in a lambda that is accessible to a local instance of API Gateway:
- Run
yarn workspace server build
- Go to
packages/server
- Run
sam local start-api --port 5000
- Go to the GraphQL Playground at http://localhost:5000, or point GraphiQL at that URL
- Go to the next section
This section assumes you have installed a GraphQL client like GraphiQL or Playground.
For endpoints that don't require that there be a logged-in user, just run the query in your GraphQL client. For example:
query {
greeting(language: ENGLISH)
}
For endpoints that do require there be a logged-in user, you'll need to first
configure your GraphQL client to include an Authorization
header that is an
encoded JWT with a field called name
. For example, in Playground, you can set
this header with the user name name John Doe
by adding the following to the
'HTTP HEADERS' tab:
{
"Authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
To create your own token, we recommend using https://jwt.io.
You can then run the query. For example:
query {
personalizedGreeting(language: ENGLISH)
}
Note that the integration tests use a client production build,
-
If you haven't already, build the shared project:
yarn workspace shared build
Note that if you change anything in the shared workspace, you will need to re-run this.
-
If you haven't started the server before, generate types for its GraphQL schema:
yarn workspace server codegen
Note that if you change anything in the GraphQL schema, you will need to re-run this.
-
If you haven't already, run a client production build:
yarn workspace client build
Note that if you change anything in the client workspace or GraphQL schema, you will need to re-run this.
-
Start the integration environment:
yarn workspace integration start
Note that if you've had to re-run steps 1, 2 or 3, you'll need to re-run this.
-
Run the tests:
yarn workspace tests start
Note that this project uses Prettier to format code, and
that if incorrectly formatted code is pushed to a branch, then that branch's
build will fail. Use yarn format
to format your code, or configure your editor
to automatically format your code using the version of Prettier in this project.