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
  • Generate the project
  • Setup Contentful access
  • Setting up Docker
  • Starting the local server
• 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 GraphQL?
  • Why use Contentful?
  • Why use Amazon Simple Queue Service (SQS)?
  • Why use Apollo Server?
  • Why use the Serverless Framework?
  • Why use Redis?
• 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.

1. Log into your Contentful account
2. Click on the Content Model tab
3. Click on the Design your Content Modal button if this is your first modal
4. Create a new model called Technology
5. Add three new text fields called displayName, description and url
6. 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:

1. Sign up for an AWS account
2. Create an IAM User and Access Key
3. Export your AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY credentials.
   Copy 📋

      export AWS_ACCESS_KEY_ID=<your-key-here>
      export AWS_SECRET_ACCESS_KEY=<your-secret-key-here>
   

4. Deploy your application on AWS Lambda:
   Copy 📋

      npm run deploy
   

5. To deploy a single function, run:
   Copy 📋

      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!