Getting Started

Backend

Since this is a frontend track, you don’t want to spend too much time setting up the backend. This is why you use Graphcool, a service that provides a production-ready GraphQL API out-of-the-box.

The Data Model

You’ll use the Graphcool CLI to generate the server based on the data model that you need for the app. Speaking of the data model, here is what the final version of it looks like written in the GraphQL Schema Definition Language (SDL):

type User {
  name: String!
  links: [Link!]! @relation(name: "UsersLinks")
  votes: [Vote!]! @relation(name: "UsersVotes")
}

type Link { 
  url: String!
  postedBy: User! @relation(name: "UsersLinks")
  votes: [Vote!]! @relation(name: "VotesOnLink")
}

type Vote {
  user: User! @relation(name: "UsersVotes")
  link: Link! @relation(name: "VotesOnLink")
}

Creating the GraphQL Server

For starting out, you’re not going to use the full data model that you saw above. That’s because you want to evolve the schema when it becomes necessary for the features that you implement.

For now, you’ll just use the Link type to create the backend. The first thing you need to do to get your GraphQL server is install the Graphcool CLI with npm.

NOTE: This tutorial uses the legacy version of Graphcool and will be updated soon to use the new Graphcool Framework. The CLI commands mentioned in tutorial are outdated, you can read more about the new CLI here. If you still want to go through this tutorial, you can install the old version of the CLI using npm install -g graphcool@0.4.

Now you can go and create the server.

This will execute the graphcool init command with two arguments:

• --schema: This option accepts a .graphql-schema that’s either stored locally or at a remote URL. In your case, you’re using the starter schema stored at https://graphqlbin.com/hn-starter.graphql, you take a look at it in a bit.
• --name: This is the name of the Graphcool project you’re creating, here you’re simply calling it Hackernews.

Note that this command will open up a browser window first and ask you to authenticate on the Graphcool platform.

The schema that’s stored at https://graphqlbin.com/hn-starter.graphql only defines the Link type for now:

type Link @model {
  description: String!
  url: String!
}

Once the project is created, you’ll find the Graphcool Project File(project.graphcool) in the directory where you executed the command. It should look similar to this:

# project: cj4k7j28p7ujs014860czx89p
# version: 2

type Link @model {
  url: String!
  description: String!
  createdAt: DateTime!
  id: ID! @isUnique
  updatedAt: DateTime!
}

type File @model {
  contentType: String!
  createdAt: DateTime!
  id: ID! @isUnique
  name: String!
  secret: String! @isUnique
  size: Int!
  updatedAt: DateTime!
  url: String! @isUnique
}

type User @model {
  createdAt: DateTime!
  id: ID! @isUnique
  updatedAt: DateTime!
}

The top of the file contains some metadata about the project, namely the project ID and the version number of the schema.

The User and File types are generated by Graphcool and have some special characteristics. User can be used for authentication and File for file management.

Also notice that each type has three fields called id, createdAt and updatedAt. These are managed by the system and read-only for you.

Populate The Database & GraphQL Playgrounds

Before you move on to setup the frontend, go ahead and create some initial data in the project so you’ve got something to see once you start rendering data in the app!

You’ll do this by using a GraphQL Playground which is an interactive environment that allows you to send queries and mutations. It’s a great way to explore the capabilities of an API.

This command will read the project ID from the project file and open up a GraphQL Playground in a browser.

The left pane of the Playground is the editor that you can use to write your queries, mutations, and even subscriptions. Once you click the play button in the middle, the response to the request will be displayed in the results pane on the right.

Since you’re adding two mutations to the editor at once, the mutations need to have operation names. In your case, these are CreateGraphcoolLink and CreateApolloLink.

This creates two new Link records in the database. You can verify that the mutations actually worked by either viewing the currently stored data in the data browser (simply click DATA in the left side-menu) or by sending the following query in the already open Playground (you will need to comment out the two mutations to send this query in the Playground):

{
  allLinks {
    id
    description
    url
  }
}

If everything went well, the query will return the following data:

{
  "data": {
    "allLinks": [
      {
        "id": "cj4jo6xxat8o901420m0yy60i",
        "description": "The coolest GraphQL backend 😎",
        "url": "https://graph.cool"
      },
      {
        "id": "cj4jo6z4it8on0142p7q015hc",
        "description": "The best GraphQL client",
        "url": "http://dev.apollodata.com/"
      }
    ]
  }
}

Frontend

Creating the App

Next, you are going to create the Ember app! As mentioned in the beginning, you’ll use the ember-cli for that.

This will create a new directory called hackernews-ember-apollo that has all the basic configuration setup.

This will open a browser and navigate to http://localhost:4200 where the app is running. If everything went well, you’ll see the following:

Your project structure should now look as follows:

.
├── .editorconfig
├── .ember-cli
├── .eslintrc.js
├── .git
├── .gitignore
├── .travis.yml
├── .watchmanconfig
├── README.md
├── app
├── config
├── dist
├── ember-cli-build.js
├── node_modules
├── package.json
├── project.graphcool
├── public
├── testem.js
├── tests
├── tmp
├── vendor

Prepare Styling

This tutorial is about the concepts of GraphQL and how you can use it from within an Ember application, so you want to spend the least time on styling issues and in-depth Ember concepts. To ease up usage of CSS in this project, you’ll use the Tachyons library which provides a number of CSS classes.

Since you still want to have a bit more custom styling here and there, you also prepared some styles for you that you need to include in the project.

Installing Apollo

That’s it, you’re ready to write some code! 🚀

Configuring Apollo

Apollo abstracts away all lower-lever networking logic and provides a nice interface to the GraphQL API. In contrast to working with REST APIs, you don’t have to deal with constructing your own HTTP requests any more - instead you can simply write queries and mutations and send them using the ember-apollo-client.

The first thing you have to do when using Apollo is configure your ApolloClient instance. It needs to know the endpoint of your GraphQL API so it can deal with the network connections.

Next you need to replace the placeholder for the GraphQL endpoint with your actual endpoint. But where do you get your endpoint from?

There are two ways for you to get your endpoint. You can either open the Graphcool Console and click the Endoints-button in the bottom-left corner. The second option is to use the CLI.

Removing the welcome message

To remove the welcome message you need to do two small things.

That’s it! Now you are all set to start building your app! 😎