DEV Community

Begin profile image SHAWNHOSEA
SHAWNHOSEA for Begin

Posted on

Apollo GraphQL & Begin starter example

#aws #cloud #serverless

⏱ This tutorial is an introductory walkthrough of creating an Apollo GraphQL app on Begin. It should take less than 15 minutes.

Introduction

Hello there, Beginner!

This tutorial uses the Apollo GraphQL Begin starter example, extended by an example API endpoint.

What is GraphQL?

Created by Facebook in parallel with React, GraphQL is a query language that defines a set of constraints for APIs. It has a built-in server-side runtime for fulfilling those queries with your existing data. Basically, it is used to load data from a server to a client -- it’s a way to get data from an API into your application. The principles of GraphQL are extremely useful building blocks for web applications.

To learn more about GraphQL click here to check out their docs!

What is Apollo?

Apollo is the industry-standard GraphQL implementation, providing the data graph layer that connects modern apps to the cloud.

The Apollo platform is an implementation of GraphQL that can transfer data between the cloud (server) to the UI of your app. In fact, Apollo builds its environment in such a way that we can use it to handle GraphQL on the client as well as the server-side of the application.

To learn more about Apollo click here to checkout their docs!

Prerequisites

You will need to have git and Node.js installed to your local computer to follow along with this tutorial. (Learn more about installing git and installing Node.js.)

You'll also need a GitHub account. (Learn more about signing up with GitHub.)

This tutorial also assumes some familiarity with such things as:

  • Text editors
  • Terminal / CLI
  • Git and version control
  • General software development using JavaScript

You do not need to be an expert in any of these things in order to follow along and make your first Apollo app in Begin!

Getting started

Create your Apollo app

First, click the Deploy to Begin button below. This starts the process of authorizing Begin with your GitHub account. (You may be prompted to log into GitHub, and/or be asked to create a Begin username.)

Deploy to Begin

Name your app & repo

You'll then be prompted to name your new app and repository – this is optional, feel free to use the default app and repo name if you like!

Note: your Begin app name and repository name cannot be changed later.

begin-repo-name

Once you've clicked the Create... button, Begin will spin up your new project on GitHub (under github.com/{your GH username}/{your repo name}).

By default your Begin app repo is created as a public GitHub repo; it can be set to private by granting Begin additional permissions from this screen (or later from the Settings screen found in the left nav of your Begin app).

Your first deploy

After creating your app, you'll be taken to its Activity stream. Welcome to the main backend interface of your Begin app!

begin-activity

From the Activity view, you'll be able to watch your app build & deploy in real-time. Any time you push to master, you'll see a new build get kicked off in Begin.

Each build undergoes a number of predefined build steps (learn more about build steps here); these build steps may install your app's dependencies (install), check your code's syntax for issues (lint), generate any files or assets needed to run your app (build), and/or run an automated test suite (test).

If no build steps fail, then the build containing your latest commit to master is automatically deployed to your staging environment.

Go ahead and click the Staging link in the upper left corner of your left nav to open your new app's staging URL. You should now see your basic Apollo GraphQL app:

apollo-screen

💡 Learn more! Head here to dig deeper into covers build pipelines, git tagging, and more.

Make your first commit

If you'd like to jump right into making your first commit and running your first build, click the Edit on GitHub button. This will open your app's code in GitHub and allow you to make a quick change.

begin-activity-2

Look for this code, and try changing the text of the h1 to say My Begin + Apollo GraphQL API:

// Customize your site by changing the text of the h1
 <body>
    <h1 class="center-text">Begin + Apollo GraphQL API</h1> // Edit this line of code
    <section
      class="padding-0 background-color-dark border-radius-4"
    >
      <pre><code id="code" class="color-light">
        Loading...
      </code></pre>
    </section>
Enter fullscreen mode Exit fullscreen mode

Click the commit changes button on GitHub, and head back to your Activity view to watch it build.

When it's done, don't forget to see your changes live in your staging environment!

Get set up locally

Next, let's get your new site running in your local environment (i.e. the computer you work on).

First, head to your GitHub repo (from the first card in your Activity, or from the left nav). Find the clone or download the button and copy the git URL.

Then head to your terminal and clone your repo to your local filesystem.

git clone https://github.com/your-github-username/your-new-begin-app.git
Enter fullscreen mode Exit fullscreen mode

Once you've got your project cloned on your local machine, cd into the project directory, install your dependencies, and start the local dev server:

cd your-new-begin-app
npm install
npm start
Enter fullscreen mode Exit fullscreen mode

You should see a localhost link in your terminal – go ahead and visit that in your browser.

That's all you need to do preview your changes locally before pushing them to staging!

Project structure

Now that your app is live on staging and running locally, let's take a quick look into how the project itself is structured so you'll know your way around. Here are the key folders in the source tree of your Apollo app:

.
├── public/
├── src/
│   └── http/
│       └── post-graphql/
└── test/
Enter fullscreen mode Exit fullscreen mode

Let's go over each of these directories and how you may use them:

public/

The public directory is where we host our home page: index.html. Inside we have an example GraphQL query that pulls in data from our HTTP function using an async function that fetches our GraphQL data graph from src/http/post-graphql/index.js. We then append our query results to a DOM element using getElementById.

// public/index.html

 <!-- Example GraphQL query -->
 // Fetch data graph layer
  <script type=module>
    (async function() {
      let query = `{hello}`
      let result = await fetch('/graphql', {
        method: 'post',
        body: JSON.stringify({query}),
        headers: {
          'X-Requested-With': 'XMLHttpRequest',
          'Content-Type': 'application/json',
        }
      })
      let json = await result.json()
      console.log(json)

      // Append results to div element
      let code = document.getElementById('code')
      code.innerHTML = JSON.stringify(json, null, 2)
    })()
  </script>
Enter fullscreen mode Exit fullscreen mode

src/http/post-graphql/

The POST /graphql function constructs a schema, using GraphQL schema language and then sets up a GraphQL server that will enforce our schema's structure. Afterwards, we provide resolver functions for your schema fields that will output our Hello World string! To learn more about GraphQL schemas, check out this section of the Apollo docs: Build a schema.

// src/http/post-graphql/index.js

let arc = require('@architect/functions')
let {ApolloServer, gql} = require('apollo-server-lambda')

// Construct a schema, using GraphQL schema language
let typeDefs = gql`
  type Query {
    hello: String
  }
`
// Provide resolver functions for your schema fields
let resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
}

let server = new ApolloServer({typeDefs, resolvers})
let handler = server.createHandler()

exports.handler = function(event, context, callback) {
  let body = arc.http.helpers.bodyParser(event)
  // Body is now parsed, re-encode to JSON for Apollo
  event.body = JSON.stringify(body)
  handler(event, context, callback)
}
Enter fullscreen mode Exit fullscreen mode

In the next section, we will go more in-depth about how to provision HTTP functions in your Apollo GraphQL app by setting up a function that displays the GraphQL playground.

💡 Learn more! Head here to dig deeper into HTTP functions in Begin apps.

src/test/

Your Apollo GraphQL project comes built-in with a few boilerplate tests to ensure that things are running smoothly in your app. We've even loaded some example tests for web integration & Begin data in the src/test/example/ directory.

A solid platform is the foundation of a durable application, but tests are essential!

You can find the test script specified in package.json:

// package.json
{
  "scripts": {
    "test": "NODE_ENV=testing tape test/*-test.js | tap-spec"
  }
}
Enter fullscreen mode Exit fullscreen mode

Tests run via npm test or npm t.

While you can use any test runner and reporter combo you want, we recommend the TAP family for testing. Test suites that require their runners to inject globals can create some very difficult to debug situations.

With that said, Jest, Enzyme, Mocha, etc. are all options available to you!

💡 Learn more! Head here to dig deeper into the project structure of Begin apps.

GraphQL Playground

The GraphQL Playground is an IDE (Integrated development environment) for better development workflows (GraphQL Subscriptions, interactive docs & collaboration). This playground is where you can test out your GraphQL queries for your app. You can learn more about the GraphQL Playground here.

graphql-playground

Provision new route for GraphQL Playground

Let's make a new route that displays our GraphQL playground on its own page.

Ready to give it a go?

  1. Head to your app’s repo folder
  2. Open the app.arc file in your root
  3. Find the @http pragma, and on a new line, add the route get /playground.
  4. Start the local dev environment (npm start) to generate any new HTTP Function handlers
  5. Push your changes!

Your new route(s) will instantly activate in staging. Then deploy to production to see them there, too.

If your app’s existing app.arc file has a commented warning about not editing it, go ahead and remove that – it's time to start editing that file!

Inside of your project folder, navigate to the src/http/get-playground/index.js file. This repo here provides the code that will display our playground. The code is also written below. Copy and paste this code inside of the index.js file.

<!DOCTYPE html>
<html>

<head>
  <meta charset=utf-8/>
  <meta name="viewport" content="user-scalable=no, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, minimal-ui">
  <title>GraphQL Playground</title>
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/graphql-playground-react/build/static/css/index.css" />
  <link rel="shortcut icon" href="//cdn.jsdelivr.net/npm/graphql-playground-react/build/favicon.png" />
  <script src="//cdn.jsdelivr.net/npm/graphql-playground-react/build/static/js/middleware.js"></script>
</head>

<body>
  <div id="root">
    <style>
      body {
        background-color: rgb(23, 42, 58);
        font-family: Open Sans, sans-serif;
        height: 90vh;
      }

      #root {
        height: 100%;
        width: 100%;
        display: flex;
        align-items: center;
        justify-content: center;
      }

      .loading {
        font-size: 32px;
        font-weight: 200;
        color: rgba(255, 255, 255, .6);
        margin-left: 20px;
      }

      img {
        width: 78px;
        height: 78px;
      }

      .title {
        font-weight: 400;
      }
    </style>
    <img src='//cdn.jsdelivr.net/npm/graphql-playground-react/build/logo.png' alt=''>
    <div class="loading"> Loading
      <span class="title">GraphQL Playground</span>
    </div>
  </div>
  <script>window.addEventListener('load', function (event) {
      GraphQLPlayground.init(document.getElementById('root'), {
        endpoint: '/graphql'
      })
    })</script>
</body>

</html>
Enter fullscreen mode Exit fullscreen mode

Now let's add a button that will take us to our new playground route. Head to the public directory and open the index.html file. Add this block of code in between the <style> tag.

Add this block of code after the <section> tag inside of the <body>.

// public/index.html

  <a href="/playground">GraphQL Playground</a>
Enter fullscreen mode Exit fullscreen mode

This link navigates to our new GraphQL playground.

Your new GraphQL playground is set up and connected to your data graph. Test out some new queries grow your database!

Deploy your site

While not required, it's always a good idea to lint and run tests before pushing just to make sure you catch any errors:

npm run lint
npm t
Enter fullscreen mode Exit fullscreen mode

Everything set? Now let's push this commit (and deploy the build to staging):

git add -A
git commit -am 'Just customizing my Begin site!'
git push origin master
Enter fullscreen mode Exit fullscreen mode

Head on back to Begin and open your staging URL once your build is complete. Looking good? Excellent!

Now let's deploy to production: click the Deploy to production button in the upper left, pick a version, leave an optional message summarizing your changes, and Ship it!

When your next build is done, click the production link in the upper left corner to see the latest release of your app!

✨Tip: You can also deploy to production from your terminal by bumping your npm version (npm version [patch|minor|major] && git push origin) or by cutting a git tag (git tag -a 1.0.0 -m "1.0, here we come" && git push origin --tags)

Congratulations!

You've now got a shiny new Apollo GraphQL app hosted on Begin – nice work.

Now go show it off – people need to see this thing!

Additional resources

Top comments (0)

Read next

segoja7 profile image

KCL + Crossplane: A Declarative Language for Deploying Complex Infrastructure on AWS with Kubernetes.

Javier Sepúlveda -

574n13y profile image

File Management Systems

Vivesh -

piyush_desai_bddc94d674ad profile image

Amazon S3 Increases Bucket Limit to 10,000 — Scalability Just Got Easier!

piyush desai -

adityabhuyan profile image

Connecting SQL Databases to the Cloud: PostgreSQL, MySQL, SQLite, and Cloud Integration Explained

Aditya Pratap Bhuyan -