Introducing the new Serverless, GraphQL, Apollo Server, and Contentful Starter kit
The team at This Dot Labs has released a brand new starter kit which includes the Serverless Framework, GraphQL, Apollo Server and Contentful configured and ready to go. This article will walk through how to set up the new kit, the key technologies used, and reasons why you would consider using this kit.
Table of Contents
- How to get started setting up the kit
- How to Create the Technology Model in Contentful
- How to seed the database with demo data
- How to work with the migration scripts
- Technologies included in this starter kit
- Why use the Jest testing framework?
- Project structure
- How to deploy your application
- What can this starter kit be used for?
- Conclusion
How to get started setting up the kit
Generate the project
In the command line, you will need to start the starter.dev CLI by running the npx @this-dot/create-starter
command. You can then select the Serverless Framework, Apollo Server, and Contentful CMS
kit and name your new project. Then you will need to cd
into your new project directory and install the dependencies using the tool of your choice (npm, yarn, or pnpm). Next, you will need to Run cp .env.example .env
to copy the contents of the .env.example
file into the .env
file.
Setup Contentful access
You will first need to create an account on Contentful, if you don't have one already. Once you are logged in, you will need to create a new space. From there, go to Settings -> API keys
and click on the Content Management Tokens
tab. Next, click on the Generate personal token
button and give your token a name. Copy your new Personal Access Token, and add it to the CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN
variable. Then, go to Settings -> General settings
to get the CONTENTFUL_SPACE_ID
. The last step is to add those CONTENTFUL_CONTENT_MANAGEMENT_API_TOKEN
and CONTENTFUL_SPACE_ID
values to your .env
file.
Setting up Docker
You will first need to install Docker Desktop if you don't have it installed already. Once installed, you can start up the Docker container with the npm run infrastructure:up
command.
Starting the local server
While the Docker container is running, open up a new tab in the terminal and run npm run dev
to start the development server. Open your browser to http://localhost:3000/dev/graphql
to open up Apollo server.
How to Create the Technology Model in Contentful
To get started with the example model, you will first need to create the model in Contentful.
- Log into your Contentful account
- Click on the
Content Model
tab - Click on the
Design your Content Modal
button if this is your first modal - Create a new model called
Technology
- Add three new text fields called
displayName
,description
andurl
- Save your new model
How to seed the database with demo data
This starter kit comes with a seeding script that pre-populates data for the Technology
Content type.
In the command line, run npm run db:seed
which will add three new data entries into Contentful.
If you want to see the results from seeding the database, you can execute a small GraphQL query using Apollo server.
First, make sure Docker, and the local server(npm run dev
) are running, and then navigate to http://localhost:3000/dev/graphql
.
Add the following query:
query TechnologyQuery {
technologies {
description
displayName
url
}
}
When you run the query, you should see the following output.
{
"data": {
"technologies": [
{
"description": "GraphQL provides a strong-typing system to better understand and utilize our API to retrieve and interact with our data.",
"displayName": "GraphQL",
"url": "https://graphql.framework.dev/"
},
{
"description": "Node.jsยฎ is an open-source, cross-platform JavaScript runtime environment.",
"displayName": "Node.js",
"url": "https://nodejs.framework.dev/"
},
{
"description": "Express is a minimal and flexible Node.js web application framework.",
"displayName": "Express",
"url": "https://www.npmjs.com/package/express"
}
]
}
}
How to work with the migration scripts
Migrations are a way to make changes to your content models and entries. This starter kit comes with a couple of migration scripts that you can study and run to make changes to the demo Technology
model. These migration scripts are located in the scripts/migration
directory.
To get started, you will need to first install the contentful-cli
.
npm i -g contentful-cli
You can then login to Contentful using the contentful-cli
.
contentful login
You will then need to choose the Contentful space where the Technology
model is located.
contentful space use
If you want to modify the existing demo content type, you can run the second migration script from the starter kit.
contentful space migration scripts/migrations/02-edit-technology-contentType.js -y
If you want to build out more content models using the CLI, you can study the example code in the /scripts/migrations/01-create-technology-contentType.js
file. From there, you can create a new migration file, and run the above contentful space migration
command.
If you want to learn more about migration in Contentful, then please check out the documentation.
Technologies included in this starter kit
Why use GraphQL?
GraphQL is a query language for your API and it makes it easy to query all of the data you need in a single request. This starter kit uses GraphQL to query the data from our Contentful
space.
Why use Contentful?
Contentful is a headless CMS that makes it easy to create and manage structured data. We have integrated Contentful into this starter kit to make it easy for you to create new entries in the database.
Why use Amazon Simple Queue Service (SQS)?
Amazon Simple Queue Service (SQS) is a queuing service that allows you to decouple your components and process and store messages in a scalable way.
In this starter kit, an SQS message is sent by the APIGatewayProxyHandler
using the sendMessage
function, which is then stored in a queue called DemoJobQueue
. The SQS handler sqs-handler
polls this queue, and processes any message received.
import { APIGatewayProxyHandler } from "aws-lambda";
import { sendMessage } from "../utils/sqs";
export const handler: APIGatewayProxyHandler = async (event) => {
const body = JSON.parse(event.body || "{}");
const resp = await sendMessage({
id: Math.ceil(Math.random() * 100),
message: body.message,
});
return {
statusCode: resp.success ? 200 : 400,
body: JSON.stringify(resp.data),
};
};
Why use Apollo Server?
Apollo Server is a production-ready GraphQL server that works with any GraphQL client, and data source. When you run npm run dev
and open the browser to http://localhost:3000/dev/graphql
, you will be able to start querying your Contentful data in no time.
Why use the Serverless Framework?
The Serverless Framework is used to help auto-scale your application by using AWS Lambda functions. In the starter kit, you will find a serverless.yml
file, which acts as a configuration for the CLI and allows you to deploy your code to your chosen provider.
This starter kit also includes the following plugins:
serverless-offline
- allows us to deploy our application locally to speed up development cycles.serverless-plugin-typescript
- allows the use of TypeScript with zero-config.serverless-dotenv-plugin
- preloads function environment variables into the Serverless Framework.
Why use Redis?
Redis is an open-source in-memory data store that stores data in the server memory. This starter kit uses Redis to cache the data to reduce the API response times and rate limiting. When you make a new request, those new requests will be retrieved from the Redis cache.
Why use the Jest testing framework?
Jest is a popular testing framework that works well for creating unit tests.
You can see some example test files under the src/schema/technology
directory. You can use the npm run test
command to run all of the tests.
Project structure
Inside the src
directory, you will find the following structure:
.
โโโ generated
โ โโโ graphql.ts
โโโ handlers
โ โโโ graphql.ts
โ โโโ healthcheck.spec.ts
โ โโโ healthcheck.ts
โ โโโ sqs-generate-job.spec.ts
โ โโโ sqs-generate-job.ts
โ โโโ sqs-handler.spec.ts
โ โโโ sqs-handler.ts
โโโ models
โ โโโ Technology
โ โโโ create.spec.ts
โ โโโ create.ts
โ โโโ getAll.spec.ts
โ โโโ getAll.ts
โ โโโ getById.spec.ts
โ โโโ getById.ts
โ โโโ index.ts
โ โโโ TechnologyModel.spec.ts
โ โโโ TechnologyModel.ts
โโโ schema
โ โโโ technology
โ โ โโโ index.ts
โ โ โโโ technology.resolver.spec.ts
โ โ โโโ technology.resolvers.ts
โ โ โโโ technology.typedefs.ts
โ โโโ index.ts
โโโ utils
โโโ contentful
โ โโโ contentful-healthcheck.spec.ts
โ โโโ contentful-healthcheck.ts
โ โโโ contentful.spec.ts
โ โโโ contentful.ts
โ โโโ index.ts
โโโ redis
โ โโโ index.ts
โ โโโ redis-healthcheck.spec.ts
โ โโโ redis-healthcheck.ts
โ โโโ redis.spec.ts
โ โโโ redis.ts
โโโ sqs
โ โโโ client.spec.ts
โ โโโ client.ts
โ โโโ getQueueUrl.spec.ts
โ โโโ getQueueUrl.ts
โ โโโ index.ts
โ โโโ is-offline.spec.ts
โ โโโ is-offline.ts
โ โโโ sendMessage.spec.ts
โ โโโ sendMessage.ts
โโโ test
โโโ mocks
โโโ contentful
โ โโโ entry.ts
โ โโโ index.ts
โโโ aws-lambda-handler-context.ts
โโโ graphql.ts
โโโ index.ts
โโโ sqs-record.ts
This given structure makes it easy to find all of the code and tests related to that specific component. This structure also follows the single responsibility principle which means that each file has a single purpose.
How to deploy your application
The Serverless Framework needs access to your cloud provider account so that it can create and manage resources on your behalf. You can follow the guide to get started.
Steps to get started:
- Sign up for an AWS account
- Create an IAM User and Access Key
- Export your
AWS_ACCESS_KEY_ID
&AWS_SECRET_ACCESS_KEY
credentials.export AWS_ACCESS_KEY_ID=<your-key-here> export AWS_SECRET_ACCESS_KEY=<your-secret-key-here>
- Deploy your application on
AWS Lambda
:npm run deploy
- To deploy a single function, run:
npm run deploy function --function myFunction
To stop your Serverless application, run:
serverless remove
For more information on Serverless deployment, check out this article.
What can this starter kit be used for?
This starter kit is very versatile, and can be used with a front-end application for a variety of situations.
Here are some examples:
- personal developer blog
- small e-commerce application
Conclusion
In this article, we looked at how we can get started using the Serverless, GraphQL, Apollo Server, and Contentful Starter kit. We also looked at the different technologies used in the kit, and why they were chosen. Lastly, we looked at how to deploy our application using AWS.
I hope you enjoy working with our new starter kit!