Configuring an Angular CLI project with GraphQL

AngularInDepth is moving away from Medium. More recent articles are hosted on the new platform inDepth.dev. Thanks for being part of indepth movement!

The content in this article was made possible by the research from Zack Ream, Chaz Gatian, and Elizabeth Coble —September 9th 2019

GraphQL drastically alters the development cycle and time to delivery. In this post we will cover how to configure an empty Angular CLI project to get it up to speed with a top notch developer experience, which includes:

• Apollo Client Configuration
• GraphQL Code Generation
• Additional Tooling
• VSCode extension

In this tutorial I will be using Graphql Zero (a public GraphQL server built for rapid prototyping).

Add Apollo Client

Apollo Client has become the defacto Angular based GraphQL client. For newcomers this is GraphQL’s equivalent to HttpClient.

Run the Apollo Angular schematic:

ng add apollo-angular

This will add dependencies and create a new file graphql.module.ts in the application root. Open this file and configure the uri variable to your GraphQL server.

Tip: Use a InjectionToken to configure the endpoint

Add graphql-cli

graphql-cli contains a collection of useful tools. The one we are interested in is the ability to copy a schema locally to the project. First, install graphql-cli:

npm install graphql-cli -D

Next run the init command to create a .graphqlconfig

npx graphql init

Select the following options:

Enter project name: Default
Local schema File Path: Default (schema.graphql)
Endpoint URL: https://graphqlzero.almansi.me/api
Name of this endpoint? Default
Subscription URL: Skip
Do you want to add other endpoints? No
What format do you want to save your config in? JSON

This should generate a .graphqlconfig in the root of the application.

{
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "default": "https://graphqlzero.almansi.me/api"
    }
  }
}

Next create a package.json script to copy the schema locally to the project.

"gql:update-schema": "graphql get-schema -e default"

Run the script and verify a schema.graphql was created in the root of the project.

The schema is copied locally for two reasons. First, by copying the schema locally CI pipelines are not dependant on an external server resource to auto generate code. Secondly, during code reviews we only want to see modifications to the auto generated files when we’ve consciously made the decision to consume new features from the graph.

Add GraphQL Codegen

GraphQL Code Generator is an amazing tool that has a plugin system to generate types for multiple languages. One plugin TypeScript Apollo Angular, allows the generation of Apollo Services. These services can be injected into components.

Install GraphQL Codegen CLI:

npm install @graphql-codegen/cli -D

Then run the initialization wizard:

npx graphql-codegen init

Select the following options:

What type of application are you building: Application Built with Angular
Where is your schema: schema.graphql
Where are your operations and fragments: Default option (/src/**/*.graphql)
Pick Plugins: Typescript, TypeScript Operations, TypeScript Apollo Angular
Where to write the output: src/generated/types.graphql-gen.ts
Do you want to generate an introspection file? No
How to name the config file? Default(codegen.yml)
What script in package.json should run the codegen? gql:codegen

After the wizard completes run npm install

Next add an entry in.gitignore to exclude all files ending with graphql-gen.ts.

# Other .gitignore options...
*.graphql-gen.ts

Add File Watching

To enhance the development experience, it would be great if the application would recompile anytime we make changes to .graphql files.

Install npm-run-all (a concurrently alternative):

npm install npm-run-all -D

Now modify your package.json. First create a new script to monitor the graphql files for changes.

"gql:codegen:watch": "graphql-codegen --watch"

Next create a script to just run the Angular build.

"start:ng": "ng serve",

Finally, update the start script to run both the Angular build and the codegen script in parallel.

"start": "run-p start:ng gql:codegen:watch",

Your final package.json should look like this:

"start": "run-p start:ng gql:codegen:watch",
"start:ng": "ng serve",
"gql:update-schema": "graphql get-schema -e default",
"gql:codegen": "graphql-codegen --config codegen.yml",
"gql:codegen:watch": "graphql-codegen --watch"

Now that the project is properly configured, create a new file app.component.graphql alongside your app.component.ts .

Create a GraphQL query to return a list of users.

Now initiate the build by running npm run start

Update the app.component.ts by injecting the newly created service UsersGQL

Lastly, render the list of users provided by the Observable stream.

Congratulations, your project is configured! 🎊

Additional Options

Near File Operations

Instead of generating all GraphQL types and services in one file, we prefer to generate the services next to the .graphql files. In order to do this first install the near-operation-file-preset.

npm install @graphql-codegen/near-operation-file-preset -D

Update codegen.yml to with the following configuration

codegen.yml

VS Code Plugin

Install Prisma’s GraphQL extension for VSCode. The enhances .graphql with autocomplete and go to definition functionality. Additionally, it’s configured through the same .graphqlconfig generated by graphql-cli. 🎊

Conclusion

This tutorial showed you how to leverage Apollo Client, GraphQL Code Generator, and graphql-cli to create a rich development experience. If you have any suggestions to the workflow, or know improvements that can be made to the experience please let us know!