Angular & Apollo Client: Getting Started with GraphQL in Angular

To generate types, list every query and mutation you intend to use in files like {{name}}.graphql. This example demonstrates basic CRUD operations (create, read, update, delete) for movies. Create a file in graphql/graphql-custom-backend/movie.graphql and paste the following code

# src/app/graphql/graphql-custom-backend/movie.graphql

fragment MovieInfo on Movie {
	id
	createdAt
	updatedAt
	title
	description
}

query GetAllMovies {
	getAllMovies {
		...MovieInfo
	}
}

mutation CreateMovie($movieInputCreate: MovieInputCreate!) {
   createMovie(movieInputCreate: $movieInputCreate) {
		...MovieInfo
	}
}

mutation EditMovie($movieInputEdit: MovieInputEdit!) {
	editMovie(movieInputEdit: $movieInputEdit) {
		...MovieInfo
	}
}

mutation DeleteMovie($movieId: Int!) {
	deleteMovie(movieId: $movieId)
}

To generate TypeScript types, create a file named codegen.yml at the root of the application. codegen.yml is a configuration file for graphql-code-generator, which describes the endpoints for inspecting the server-side schema, the places where you want to generate TypeScript types, the plugins you intend to use, and much more. In our case, the codegen.yml looks like the following.

overwrite: true
generates:
  # where to generate file
  ./src/app/graphql/graphql-custom-backend.service.ts: 
schema:
  # where the server lives
  - http://localhost:3001/graphql 
documents:
  # where are our queries / mutations, etc.
  - src/app/graphql/graphql-custom-backend/*.graphql 
# necessary to properly generate types
plugins:
  - typescript
  - typescript-operations
  - typescript-apollo-angular
config:
  # used to disable lint rule: ts(4114) (override)
  addExplicitOverride: true 
  
  # Defined other endpoints with similar logic as above

To generate the schema, register an NPM command “generate-types”: “graphql-codegen --config codegen.yml” into scripts in package.json. After registering the command and executing npm run generate-types, you will have a newly created, or in the future, updated graphql-custom-backend.service.ts file.

Server Interaction

This is where the fun begins. You are going to use the generated GraphQL API calls you defined in movie.graphql. Create an Angular service in core/api/movie-api.service.ts and inject the generated types and API calls by Apollo-codegen.

// src/app/core/api/movie-api.service.ts

import { Injectable } from "@angular/core";
import { Apollo } from "apollo-angular";
import {
  CreateMovieGQL,
  DeleteMovieGQL,
  EditMovieGQL,
  GetAllMoviesGQL,
} from 'src/app/graphql/graphql-custom-backend.service';

@Injectable({
	providedIn: 'root',
})
export class MovieApiService {
	constructor(
		private getAllMoviesGQL: GetAllMoviesGQL,
		private createMovieGQL: CreateMovieGQL,
		private editMovieGQL: EditMovieGQL,
		private deleteMovieGQL: DeleteMovieGQL,
		private apollo: Apollo
	) {}	
	....
}

Read

Before any operation, you must first fetch movies with the following code.

getAllMovies(): Observable<MovieInfoFragment[]> {
	return this.getAllMoviesGQL.watch().valueChanges.pipe(
		map((res) => res.data.getAllMovies ?? [])
	);
}

When executing any query, you can attach watch() or fetch() method on these API calls (also pass an object as an argument if you need to send some input data to the server).

The most significant difference between watch() and fetch() is that watch() is reactive. If you replace the old list of movies, getAllMovies, in the Apollo cache with the new list, then by attaching watch(), the content replacement will notify all subscribers. However, with fetch(), subscribers will not get the updated value.

Also, be careful from where you import Observable interface. You may accidentally import it from @apollo/client, but you end up with an error in this case. Always import it from rxjs.

When working with multiple GraphQL endpoints, you can use any other endpoint defined for the APOLLO_NAMED_OPTIONS injection token by the following approach.

@Injectable({
	providedIn: 'root',
})
export class SpaceXApiService {
	constructor(private apollo: Apollo) {}
	
	getLaunchesPast(): Observable<ApolloQueryResult<unknown>> {
		return this.apollo.use('spaceX').query({
			query: LaunchesPastDocument,
		});
	}
}

Where LaunchesPastDocument is a strongly typed generated query by Apollo-codegen that you could have defined, for example, in spaceX.graphql to fetch some data from spaceX endpoint. For the spaceX example, visit the provided GitHub repository.

Create

Creating a new movie is a bit more complicated. You do not just have to send the correct data to your backend server, but you also have to save the newly created movie into Apollo’s cache, to group the newly created movie with the already loaded ones.

Send the new movie’s title and description to the server, wait for the server’s response and save the returned Movie object into the getAllMovies array. We can better describe everything in the following code

createMovie({ title, description }: MovieInputCreate): 
    Observable<FetchResult<CreateMovieMutation>> {
		return this.createMovieGQL.mutate(
			{
				movieInputCreate: {
					title,
					description,
				},
			},
			{
				optimisticResponse: {
					createMovie: {
						__typename: 'Movie',
						id: -1,
						createdAt: new Date().toISOString(),
						updatedAt: new Date().toISOString(),
						title: title,
						description: description,
					},
				},
				update: (store: DataProxy, { data }) => {
					const createdMovie = data?.createMovie as MovieInfoFragment;

					// query movies from cache
					const moviesQuery = store.readQuery<GetAllMoviesQuery>({
						query: GetAllMoviesDocument,
					});

					// movies haven't been loaded yet - no data in cache
					if (!moviesQuery?.getAllMovies) {
						return;
					}

					// update cache
					store.writeQuery<GetAllMoviesQuery>({
						query: GetAllMoviesDocument,
						data: {
							__typename: 'Query',
							getAllMovies: [
								...moviesQuery.getAllMovies, createdMovie
							],
						},
					});
				},
			}
		);
	}

I want to highlight the update method. The update method runs after the mutation has been successfully completed. When executing the createMovieGQL mutation, you receive back the object MovieInfoFragment, a fragment of the Movie object that has been created.

However, one thing to remember is even if you have successfully created a Movie, it is not yet grouped with the rest of the already loaded Movie objects. When you take a look back at the getAllMovies() method, you can see that it returns an attribute called getAllMovies, which contains a list of all MovieInfoFragment objects.

When you create a new Movie, you have to check Apollo’s cache to see if GetAllMoviesDocument has already been executed to ensure we have loaded all movies from the server. If not, don’t do anything.

However, if GetAllMoviesDocument was already executed, then replace the content of GetAllMoviesDocument with all the previously cached movies and the newly created one:
getAllMovies: [...moviesQuery.getAllMovies, createdMovie].

Finally, because we attached the getAllMoviesGQL.watch() method, all subscribers will be notified about the added element.

Apollo Optimistic Response

When executing any mutation, the operation on the server side may take some time to complete. Usually, server-side operations are counted in milliseconds; however, there can be longer operations that take seconds to complete.

When you want to avoid displaying a “loading spinner” on the UI, you can implement the optimisticResponse option, where we define the shape of data we expect to be returned by the server.

In the above code example, the update method for createMovieGQL.mutate runs twice, first with the mocked data defined in the optimisticResponse option and the second time when the server returns the real data: the actual Movie object that has been created.

No need to worry about having the same object in the getAllMovies array twice—Apollo is smart enough to replace the old mocked data with the real object once the server finishes its operation and returns the result.

Cannot find namespace ‘JSX’

When working with Apollo client in Angular, you might encounter the error Cannot find namespace‘JSX’. This happens when you make a wrong import. Because Apollo client can be also used with React, you have to exactly specify the path from which you want to import interfaces in Angular. This error is present by the following import: import { DataProxy, FetchResult } from ‘@apollo/client’;. In cases like this, change the import to @apollo/client/core.

Edit

Fortunately editing a Movie is much easier. Send the Id, title, and description attributes of the edited Movie object to the server as it is demonstrated in the following code snippet.

editMovie({id, title, description}: MovieInputEdit): 
  Observable<FetchResult<EditMovieMutation>> {
	return this.editMovieGQL.mutate({
		movieInputEdit: {
			id,
			title,
			description
		},
	});
}

The reason why you don’t need to update getAllMovies array in the editing process is because of Cache Normalization. Cache Normalization is when an object has some identification key, such as ID, so instead of creating multiple copies of the same object, Apollo maintains references to the normalized object by its unique identifiers. This reference maintenance results in keeping the size of the cache as small as possible and preventing duplicate data. You can inspect this behavior by using Apollo Client Devtools..

Keeping only the Movie references in getAllMovies array solves the issue of why you don’t need to update getAllMovies array when editing a Movie. You update the Movie entity in one place and every object that keeps the reference will get the updated value.

You also don’t need to implement the update option in editMovieGQL because of Apollo’s default behavior in how it handles normalized data. When defining the EditMovie mutation back in Generating schema from the backend, you included that you expect a MovieInfo fragment to be returned.

mutation EditMovie($movieInputEdit: MovieInputEdit!) {
	editMovie(movieInputEdit: $movieInputEdit) {
		...MovieInfo
	}
}

It means once the editMovieGQL mutation successfully executes, you indeed receive an updated version of a Movie object back on the frontend. However, because Apollo has already cached an old version of that edited Movie object with the same ID in its InMemoryCache, after the successful operation execution, Apollo just replaces the old Movie object with the newly received one in InMemoryCache.

Delete

Normalizing data greatly helps us to be consistent. An object can be edited in one place and for every other object, a list of objects or observers that keep a reference to the original one will get an updated value.

Data normalization is also beneficial when it comes to removing an object from the cache. Apollo provides methods for https://www.apollographql.com/docs/react/caching/garbage-collection/#cacheevict such as evict that completely removes an object from the cache. So deleting a movie can be done in the following case.

deleteMovie(movieId: number): Observable<FetchResult<DeleteMovieMutation>> {
	return this.deleteMovieGQL.mutate(
		{
			movieId,
		},
		{
			update: (store: DataProxy, { data }) => {
				this.apollo.client.cache.evict({id: `Movie:${data?.deleteMovie}` });
			},
		}
	);
}

Summary

This article served as the first part of working with Apollo Client in Angular. Executing each implemented method in MovieApiService, you can see the result in Apollo Client Devtools. You went through how to generate TypeScript types from the server-side schema, how to configure the Apollo module, how to work with mutations, and how to add an object to an already loaded list of objects. Apollo client is a massive library with lots of options, and for this reason, we will come back to it in the future to try out most of its available features.

For more information check out our training program, Bitovi Academy, or book a free Angular Consulting call to talk to an expert one-on-one!