The element’s main job is to manage it’s children’s ApolloClient instance. Every Apollo Element that’s a child of an <apollo-client> element will share it’s client instance, even across deeply nested (open) shadow roots.

<apollo-client id="client-a">
  <query-a>
    #shadow-root
      <query-b>
        #shadow-root
          <mutation-a></mutation-a>
          <apollo-client id="client-b">
            <query-c><query-c>
          </apollo-client>
      </query-b>
  </query-a>
</apollo-client>

In the above example, queries A and B, and mutation A all share a client instance, but query C has its own client instance.

Configuring

There are two ways to use <apollo-client>, automatic and manual. Automatic mode creates a basic Apollo client instance, while manual mode lets you customize the client with links and other options. If you’re not sure which mode to use, start with automatic mode - you can always switch to manual mode later on.

Automatic Mode

When setting the uri attribute on the <apollo-client> element, it creates a basic Apollo client instance directed at the given GraphQL server URI. At that point, any existing Apollo Element children receive the client instance on their client DOM property.

In the following example, an <apollo-query> element queries for user via an Apollo client pointed at a graphql server running at /graphql (i.e. on the same origin as the page). Later, JavaScript imports a custom Apollo query element called <custom-query>, then appends it to the existing Apollo client element. Both query elements have the same client reference, and both will automatically query for data.

<apollo-client uri="/graphql">
  <apollo-query>
    <script type="application/graphql">
      query User($userId: ID!) {
        user(userId: $userId) {
          name
        }
      }
    </script>
    <template>
      <style>
        .loading { opacity: 0; }
      </style>
      <p class="{{ loading ? 'loading' : '' }}">Hi, {{ data.user.name }}</p>
    </template>
  </apollo-query>
</apollo-client>

import '../components/custom-query';
document
  .querySelector('apollo-client')
  .appendChild(document
    .createElement('custom-query'))

Customizing Automatic Mode Clients

<apollo-client> uses the createApolloClient helper from @apollo-elements/core/lib/create-apollo-client under the hood, and it comes with some options for customizing the automatic-mode client. You can set the validate-variables attribute to try to prevent fetching operations that don’t have all their required top-level variables.

You can also set a typePolicies DOM property on <apollo-client> using JavaScript in order to apply some default type policies.

Manual Mode

If you need more control over the client, for example to configure the links, use manual mode leaving out the uri attribute or DOM property on <apollo-client>. Instead, create your own ApolloClient instance, and assign it to the element’s client DOM property.

To construct an instance, import from @apollo/client/core (note: @apollo/client exports a bunch of react code, so if you leave off the /core, you might experience TypeScript compilation errors, or larger bundle sizes)

import {
  ApolloClient,
  ApolloLink,
  HttpLink,
  InMemoryCache,
} from '@apollo/client/core';

import { CustomLink } from './my-custom-link';

const cache =
  new InMemoryCache();

// Configure with a URL to your GraphQL endpoint
const link = ApolloLink.from([
  new CustomLink(),
  new HttpLink({ uri: '/graphql' }),
])

document.querySelector('apollo-client').client =
  new ApolloClient({ cache, link });

Once set, the element will ensure that all it’s children, even across open shadow roots, receive the instance on their client property.

Next Steps

• Learn how to write query components

ApolloController is the abstract base class at the heart of Apollo Elements. You should not import ApolloController directly, instead use the subclasses: ApolloQueryController, ApolloMutationController, and ApolloSubscriptionController.

Example

npm init @apollo-elements -- \
  component \
    --type mutation \
    --name x-user-profile \
    --operation-name UpdateProfile
    --variables '$input: UpdateProfileInput!' \
    --fields 'updateProfile(input: $input) { id }' \
    --subdir user \
    --schema-path '#schema' \
    --shared-css-path '#components/shared.css' \
    --no-codegen
    --overwrite

Options

Use the subscription factory to add a GraphQL subscription to you hybrids element.

Templates use stampino and jexpr for efficiently updating data expressions. See their respective READMEs for more information.

What that means is you can define the element’s dynamic template using good-old HTML:

<apollo-query>
  <script type="application/json">
    query Notifications {
      me { id name }
      notifications { href title }
    }
  </script>

  <template>
    <style>
      :host([loading]) {
        opacity: 0;
      }
    </style>

    <link rel="stylesheet" href="/components/notifications.css">

    <h2>Welcome, {{ data.me.name }}!</h2>
    <p>You have {{ data.notifications.length }} notifications.</p>
    <ol class="notifications-list">
      <template type="repeat" repeat="{{ data.notifications }}">
        <li>
          <a href="{{ item.href }}">{{ item.title }}</a>
        </li>
      </template>
    <ol>
  </template>
</apollo-query>

Template Expressions

jexpr expressions are like handlebars, nunjucks, polymer, etc. expressions. You can do most things you can do in JavaScript using jexpr. Read more at the jexpr README or try it out for yourself on the Stampino REPL

Template Bindings

Template bindings follow similar conventions to lit-html. You can bind to nodes or element children, attributes, DOM properties, or even event listeners.

Content Binding

Bind to element content by adding an expression as a child of the element.

<apollo-query>
  <template>
    <samp>{{ data.content }}<samp>
  </template>
</apollo-query>

Attribute Binding

You can bind to attributes by adding an expression in an attribute position. For boolean attributes (where their presence indicates true and their absence false), prefix a ? to the attribute name.

<apollo-query>
  <template>
    <label>
      Message
      <input value="{{ data.message.content }}"/>
    </label>
    <button ?hidden="{{ data.isEditing }}">Edit</button>
  </template>
</apollo-query>

Property Binding

Bind to DOM properties by prefixing . to the property name.

<apollo-query>
  <template>
    <figure>
      <img .src="{{ data.user.avatar }}" alt="avatar"/>
    </figure>
  </template>
</apollo-query>

Event Binding

If you pass a method to your model (e.g. by passing extra model content in the element’s extras DOM property), you can add event listeners to elements by prefixing @ to the event name in an attribute position.

<apollo-query>
  <template>
    <button @click="{{ onClick }}">Ping</button>
  </template>
</apollo-query>

<script>
  {
    const queryEl = document.currentScript.getRootNode()
      .querySelector('apollo-query')
    queryEl.extras = {
      onClick(event) {
        fetch(`/ping?user=${queryEl.data.userId}`)
      }
    };
  }
</script>

Custom Template Handlers

You can set the templateHanders property on an <apollo-query> element to customize rendering behaviour by adding your own custom template types.

<apollo-query no-auto-subscribe>
  <template>
    <template type="flashy">
      <samp>{{ data.content }}<samp>
    </template>
  </template>
</apollo-query>

<script>
(async function() {
  import('lit').then(({ html }) => {
    document.currentScript.getRootNode()
      .querySelector('apollo-query')
      .templateHandlers = {
        flashy(template, model, handlers, renderers) => {
          return html`
            <blink>
              ${evaluateTemplate(template, model, handlers, renderers)}
            </blink>
          `;
        },
      };

    document.currentScript.getRootNode()
      .querySelector('apollo-query')
      .subscribe();
  });
})();

</script>

Next Steps

• Read the <apollo-query> API docs
• Learn how to write mutation components

Templates use stampino and jexpr for efficiently updating data expressions. See their respective READMEs for more information.

What that means is you can define the element’s dynamic template using good-old HTML:

<apollo-subscription>
  <script type="application/json">
    subscription Notifications {
      newNotifications { href title }
    }
  </script>

  <template>
    <style>
      :host([loading]) {
        opacity: 0;
      }
    </style>

    <link rel="stylesheet" href="/components/notifications.css">

    <ol class="notifications-list">
      <template type="repeat" repeat="{{ data.notifications }}">
        <li>
          <a href="{{ item.href }}">{{ item.title }}</a>
        </li>
      </template>
    <ol>
  </template>
</apollo-subscription>

Data Templates

Learn more about template expressions and bindings in the <apollo-query> HTML element guide

Next Steps

• Learn how to manage client-side state using Apollo Elements

This sample config lets you also import css and graphql into your lit-apollo components written in TypeScript:

import { esbuildPlugin } from '@web/dev-server-esbuild';
import { fromRollup } from '@web/dev-server-rollup';

import rollupCommonjs from '@rollup/plugin-commonjs';
import rollupLitcss from 'rollup-plugin-lit-css';
import rollupGraphQL from '@rollup/plugin-graphql';

const litcss = fromRollup(rollupLitcss);
const graphql = fromRollup(rollupGraphQL);
const commonjs = fromRollup(rollupCommonjs);

/**
 * These are the CSS files you directly import into components
 * Transform these files into Lit `CSSResult` modules
 */
const componentCSS =
  'src/components/**/*.css';

/**
 * These are the CSS files you load globally in `index.html`.
 * Serve these as regular stylesheets
 */
const globalCSS =
  'examples/spacex/style.css';

export default {
  nodeResolve: true,
  watch: true,
  rootDir: '.',
  port: 8090,
  appIndex: 'src/index.html',
  mimeTypes: {
    'src/components/**/*.css': 'js',
    'src/**/*.graphql': 'js',
  },
  plugins: [
    litcss({ include: componentCSS, exclude: globalCSS }),
    graphql(),
    commonjs(),
    esbuildPlugin({ ts: true }),
  ],
};

If you’re using TypeScript and importing CSS and GraphQL files with the rollup plugins, make sure to add this declaration somewhere in a .d.ts file in your project:

declare module '*.graphql' {
  import { DocumentNode } from '@apollo/client/core';
  const defaultDocument: DocumentNode;
  export default defaultDocument;
}

declare module '*.css' {
  import { CSSResult } from 'lit';
  const css: CSSResult;
  export default css;
}

Recommended Optimizations

Apply these plugins to further reduce your bundle sizes.

• @rollup/plugin-terser
• rollup-plugin-minify-html-literals
• @open-wc/rollup-plugin-html

On connecting to the DOM, the element reads it’s mutation and variable properties either from JavaScript, or from it’s script children, and initializes a MutationObserver to watch for changes to those children.

mutate

Call this method to initiate the mutation. You can call it without arguments, or with a partial MutationOptions object. The rest of the mutation options will fall back to the corresponding instance properties.

In other words, the following two snippets are equivalent:

element.optimisticResponse = ({ name }) => ({ __typename: 'Mutation', addUser: { name } });
element.variables = { name: 'Hulda' };
element.mutate();

element.mutate({
  optimisticResponse: ({ name }) => ({ __typename: 'Mutation', addUser: { name } }),
  variables: { name: 'Hulda' },
});

If another call is made to mutate before the first resolves, only the final call will set element instance properties.

element.addEventListener('apollo-mutation-result', event =>
  console.log(event.detail.data.addUser.name));
element.mutate({ variables: { name: 'Miriam' } });
element.mutate({ variables: { name: 'Devorah' } });
element.mutate({ variables: { name: 'Yael' } });
// => logs: 'Yael'

updater

Function which defines how to integrate the mutation result into the cache. For some simple cases Apollo can do this automatically, but for others you will need or want to control the process, for example, an AddPostMutation which adds a post to an array of Posts.

element.updater: MutationUpdaterFn<AddPostsMutationData, AddPostsMutationVariables> =
  (cache, result) => {
    const query = LatestPostsQuery;
    const cached = cache.readQuery({ query: LatestPostsQuery });
    const data = { posts: [result.data.postBlogPost, ...cached.posts] }
    cache.writeQuery({ query, data });
  }

onCompleted

The onCompleted callback is a unary function that takes a FetchResult.

onCompleted is called after the element instance’ properties are set.

onError

The onError callback is a unary function that takes an Error or ApolloError.

onError is called after the element instance’ properties are set.

Events

Listen for the apollo-mutation-result and apollo-error events to react to changes. They fire before the element instance’ properties are set.

apollo-mutation-result

Detail is an FetchResult object.

On connecting to the DOM, the element reads it’s query and variable properties either from JavaScript, or from it’s script children, and initializes a MutationObserver to watch for changes to those children.

documentChanged

When the query property changes (via JavaScript assignment, or when the GraphQL script child changes) the element sets up its ObservableQuery and begins fetching data (unless configured otherwise).

If both a GraphQL script child and a JavaScript property are present, JavaScript takes precedence.

variablesChanged

When the variables property changes (via JavaScript assignment or when the JSON script child changes) the element either refetches the existing ObservableQuery or attempts to initialize a new one and fetch.

If both a JSON script child and a JavaScript property are present, JavaScript takes precedence.

shouldSubscribe

Called synchronously before all automatic attempts to subscribe. If it returns true, the element will subscribe and begin fetching. Returns true by default, Override to prevent automatic subscription.

subscribe

When called automatically (via documentChanged or variablesChanged) or explicitly, it stops any existing ObservableQuery, then initializes a new one and begins fetching.

executeQuery

If you want to explicitly run a query and receive a promise of the result, then await element.executeQuery(). The promise will resolve when the query does, and after the element instances’ properties are set.

options

Set this property at any point to reobserve the ObservableQuery.

onData

The onData callback is a unary function that takes an ApolloQueryResult containing data, loading, error, etc.

onData is called after the element instance’ properties are set.

onError

The onError callback is a unary function that takes an Error or ApolloError.

onError is called after the element instance’ properties are set.

Events

Listen for the apollo-query-result and apollo-error events to react to changes. They fire before the element instance’ properties are set.

apollo-query-result

Detail is an ApolloQueryResult object.

On connecting to the DOM, the element reads it’s subscription and variables properties either from JavaScript, or from it’s script children, and initializes a MutationObserver to watch for changes to those children.

documentChanged

When the subscription property changes (via JavaScript assignment, or when the GraphQL script child changes) the element sets up its Observable and begins fetching data (unless configured otherwise).

If both a GraphQL script child and a JavaScript property are present, JavaScript takes precedence.

variablesChanged

When the variables property changes (via JavaScript assignment or when the JSON script child changes) the element either refetches the existing Observable or attempts to initialize a new one and fetch.

If both a JSON script child and a JavaScript property are present, JavaScript takes precedence.

shouldSubscribe

Called synchronously before all automatic attempts to subscribe. If it returns true, the element will subscribe and begin fetching. Returns true by default, Override to prevent automatic subscription.

subscribe

When called automatically (via documentChanged or variablesChanged) or explicitly, attemptes to subscribe. If a observableSubscription already exists, it will use that one, unless shouldResubscribe is set.

cancel

When called, ends the subscription and unsets the Observable.

onSubscriptionData

Unary function which takes an object containing client and subscriptionData. The subscriptionData contains data, loading, and error properties. It is called after the element instance’s properties are set.

onSubscriptionComplete

The onSubscriptionComplete callback is a function of no parameters that is called when the subscription ends (e.g. via cancel or on disconnect).

onData is called after the element instance’ properties are set.

onError

The onError callback is a unary function that takes an Error or ApolloError.

onError is called after the element instance’ properties are set.

disconnectedCallback

Cancels the subscription.

Events

Listen for the apollo-subscription-result and apollo-error events to react to changes. They fire before the element instance’ properties are set.

apollo-subscription-result

Detail is an object containing client and subscriptionData. The subscriptionData contains data, loading, and error properties. It is called after the element instance’s properties are set.

Replace imports with @apollo/client/core

apollo-client, apollo-cache-inmemory, apollo-link-* and others are now supplied by @apollo/client/core, so replace your import statements to match. NB: you should always import from @apollo/client/core, not from @apollo/client, as the latter includes dependencies on react which you probably don’t need or want. A single import statement from @apollo/client in your app can cause the TypeScript compiler to fail if react is not installed as a dependency. To avoid this, always import from @apollo/client/core.

Remove calls to writeData

If your app used client.writeData (e.g. to set default values when loading the cache), you must replace it with calls to either writeQuery, writeFragment or cache.modify. You can also set default values in field policies

Check Non-Nullable Variables

Query and Subscription elements in @apollo-elements 2 tried to prevent operations with non-nullable variables from fetching if their required arguments were null or undefined. Version 3 removes that check by default, so as long as there’s a client and a query, they subscribe immediately. To avoid errors, always make sure to set your variables before you query.

To keep components from fetching until they have their required variables, see Validating Variables.

Replace Resolvers with Type Policies

Apollo client 3 deprecates local resolvers in favour of type policies. Your resolvers will still work for now, but it’s recommended to migrate them.

Say you had this query, and you wanted to define the client-side type policies for it.

query DetailsOpenQuery {
  eenieOpen @client
  meenieOpen @client
}

In which case you might define the type policies like this:

export const DetailsTypePolicies: TypePolicies = {
  Query: {
    fields: {
      eenieOpen: {
        read(prev) { return prev; },
        merge(_, next) { return next; },
      },
      meenieOpen: {
        read(prev) { return prev; },
        merge(_, next) { return next; },
      }
    }
  }
}

Use TypePoliciesMixin to declare a component’s type policies by setting the typePolicies property on the component.

Use the mutation factory to add a GraphQL mutation to you hybrids element.

<apollo-mutation> fires Polymer-style prop-changed events when its called, data, error, or loading properties change.

See ApolloMutationInterface for more information.

import { PolymerElement, html } from '@polymer/polymer';
import { AddUserMutation } from './Hello.query.graphql.js';
import './elements.js';

class AddUserMutationElement extends PolymerElement {
  static get template() {
    return html`
      <polymer-apollo-mutation id="userMutation" data="{{data}}" mutation="[[mutation]]"></polymer-apollo-mutation>

      <p-card>
        <h2 slot="heading">Add a User</h2>
        <paper-input hidden="[[data]]" label="Name" value="{{name}}"></paper-input>
        <paper-button slot="actions" hidden="[[data]]" on-click="mutate">Submit</paper-button>
        <p hidden="[[!data]]">[[data.insertUsers.returning.0.name]] added!</p>
      </p-card>
    `;
  }

  static get properties() {
    return {
      mutation: { type: Object, value: () => AddUserMutation },
    };
  }

  mutate() {
    const { name } = this;
    return this.$.userMutation.mutate({ variables: { name } });
  }
}

customElements.define('add-user', AddUserMutationElement);

ApolloMutation inherits from ApolloElement and implements the ApolloMutationInterface.

Read the mutation component guides for examples and tips.

ApolloMutation inherits from ApolloElement and implements the ApolloMutationInterface.

Read the mutation component guides for examples and tips.

ApolloMutationMixins applies ApolloElementMixin and the ApolloMutationInterface.

Read the mutation component guides for examples and tips.

Apollo Elements Breaking Changes

Subscription Error Handling

This is the main breaking change in Apollo Elements 4. Subscription controllers no longer maintain an errors (plural) array. Subscriptions now only use the error (singular) field, matching Apollo Client’s useSubscription behavior.

Before (Apollo Elements 3):

class MyElement extends LitElement {
  subscription = new ApolloSubscriptionController(this, MessageSubscription);

  render() {
    // ❌ No longer available
    if (this.subscription.errors?.length) {
      return html`<p>Errors: ${this.subscription.errors.map(e => e.message).join(', ')}</p>`;
    }
    return html`<p>${this.subscription.data?.message}</p>`;
  }
}

After (Apollo Elements 4):

class MyElement extends LitElement {
  subscription = new ApolloSubscriptionController(this, MessageSubscription);

  render() {
    // ✅ Use singular error instead
    if (this.subscription.error) {
      return html`<p>Error: ${this.subscription.error.message}</p>`;
    }
    return html`<p>${this.subscription.data?.message}</p>`;
  }
}

Migration: If you’re reading subscription.errors, replace it with subscription.error.

Environment Requirements

Node.js 24

Apollo Elements 4 requires Node.js 24 or higher (previously 18.x):

node --version  # Should be 24.x or higher

TypeScript 4.7

If you use TypeScript, you’ll need version 4.7 or higher:

npm install --save-dev typescript@^4.7.0

Apollo Client 4 Dependency

Apollo Elements 4 depends on Apollo Client 4. Update your dependency:

npm install @apollo/client@^4.0.6

Most Apollo Client 4 changes are internal and won’t affect Apollo Elements users. However, if you use the cache API directly, note these changes:

Removed InMemoryCache.writeData

The deprecated writeData method has been removed. Use writeQuery, writeFragment, or cache.modify instead:

Before:

cache.writeData({
  data: { user: { id: "1", name: "Alice" } },
});

After:

cache.writeQuery({
  query: gql`
    query GetUser {
      user {
        id
        name
      }
    }
  `,
  data: { user: { id: "1", name: "Alice" } },
});

Migration Checklist

1. ✅ Update Node.js to version 24.x or higher
2. ✅ Update TypeScript (if used) to version 4.7 or higher
3. ✅ Install Apollo Client 4: npm install @apollo/client@^4.0.6
4. ✅ Update Apollo Elements packages to version 4.x
5. ✅ Search for subscription.errors in your codebase and replace with subscription.error
6. ✅ If using cache.writeData, replace with writeQuery, writeFragment, or cache.modify
7. ✅ Run your tests to verify everything works

Need Help?

If you encounter issues migrating:

• Check the Apollo Client 4 migration guide
• Open an issue on GitHub

ApolloSubscription inherits from ApolloElement and implements the ApolloSubscriptionInterface.

Read the subscription component guides for examples and tips.

ApolloSubscription inherits from ApolloElement and implements the ApolloSubscriptionInterface.

Read the subscription component guides for examples and tips.

ApolloSubscriptionBehavior extends ApolloSubscriptionController and implements the Behavior interface.

Read the subscription component guides for examples and tips.

ApolloSubscriptionController lets you subscribe to real-time updated from your GraphQL server. Pass it a GraphQL subscription document, and any options you choose, and it will update its host when it’s state (e.g. data, error, or loading) changes.

The (optional) third argument to the constructor is an ApolloSubscriptionControllerOptions object.

import { ApolloSubscriptionController } from '@apollo-elements/core';
import { customElement, query } from 'lit/decorators.js';
import { html, LitElement } from 'lit';

import { UserJoinedSubscription } from './UserJoined.subscription.graphql.js';

import { Snackbar } from '@material/mwc-snackbar';

@customElement('user-joined')
class UserJoined extends LitElement {
  userJoined = new ApolloSubscriptionController(this, UserJoinedSubscription, {
    onData: ({ subscriptionData }) => {
      this.last = subscriptionData.userJoined,
      this.snackbar.show();
    }
  });

  @query('mwc-snackbar'): Snackbar;

  render() {
    return html`
      <mwc-snackbar labeltext="${this.userJoined?.data?.name}"></mwc-snackbar>
    `;
  }
}

ApolloSubscriptionMixin applies ApolloElementMixin and the ApolloSubscriptionInterface.

Read the subscription component guides for examples and tips.

Decorators for Apollo Elements. Used internally to reflect properties from controllers to their elements. Normally you shouldn’t need to import these directly.

import { controlled } from '@apollo-elements/core/decorators';

class ControlledData<D, V = VariablesOf<D>> extends LitElement {
  controller = new ApolloQueryController<D, V>(this);

  @controlled()
  @state()
  data: Data<D> | null = null;
}

GraphQLScriptChildMixin allows Apollo elements to read their GraphQL document (i.e. query, mutation, or subscription) and variables from HTML <script type="application/graphql"> or <script type="application/json"> elements

The Plan

The typical to-do app has a backend which contains the authoritative database of to-dos, and a frontend which displays the list and exposes UI for operations like adding, editing, or deleting to-dos. We’ll build our frontend out of a single GraphQL query and some GraphQL mutations, and our backend using Apollo server and Koa, with an in-memory “database” consisting of a javascript object.

We’ll use Shoelace for our UI components, and Lit as our web component base, so if you want to catch up or take a refresher, check out my blog post.

Non-Goals

For the purposes of this blog post, we’re focusing solely on the frontend side, so a proper backend server and database is out of scope. Instead, we’ll implement a backend server that plugs in to web dev server. We’re still going to write GraphQL resolver functions though, so we could copy parts of our mock backend into a NodeJS server and with some small modifications it would still work.

We also won’t be doing any fancy footwork like pagination or advanced cache management. We’re assuming a short todo list that fits on one screen.

App Boilerplate

Let’s use the Apollo Elements generator to scaffold an app template:

mkdir todo-apollo
cd todo-apollo
npm init @apollo-elements -- \
    app \
  --uri /graphql \
  --install \
  --overwrite \
  --package-defaults

Once that’s done, let’s install our dependencies.

npm i -S apollo-server-koa urlpattern-polyfill

And let’s add shoelace UI’s styles and scripts to /index.html:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.0.0-beta.48/dist/themes/base.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.0.0-beta.48/dist/shoelace.js"></script>

And some initial styles in /style.css:

html {
  font-family: var(--sl-font-sans);
}

main {
  display: flex;
  place-content: start center;
}

apollo-app {
  width: clamp(400px, 90vw, 90vw);
}

With our boilerplate ready, we’re ready to start on our mock backend.

The Backend

Let’s define our backend first, starting with the GraphQL schema.

The Schema

GraphQL apps resolve around their schema, so let’s define that now. We’ll need a type to represent each to-do, and a corresponding input type for mutations. We’ll also define our operations, or all the actions our app’s users can perform. Those actions are:

1. Reading the list of to-dos
2. Creating a new to-do
3. Editing an existing to-do
4. Deleting an existing to-do

type Todo {
  id: ID
  name: String
  complete: Boolean
}

input TodoInput {
  todoId: ID
  name: String
  complete: Boolean
}

type Query {
  todos: [Todo]
  todo(todoId: ID): Todo
}

type Mutation {
  createTodo(input: TodoInput!): Todo
  updateTodo(input: TodoInput!): Todo
  toggleTodo(todoId: ID!): Todo
  deleteTodo(input: TodoInput!): [Todo]
}

In a larger app we might have defined different input types to get stronger input validation for each operation. For the sake of this demo though, a single input with no required fields does the trick.

Copy the above snippets in to /schema.graphql.

The Database

Next, we need a database to store our todos and some initial content. For demo purposes, we’ll store the todo list in-memory. We’re going to cut a few corners for the sake of brevity, so don’t take this as an example of inspired database design.

We do try to hide our shame somewhat though by keeping our four CRUD operations in the server’s context. We’ll call those functions to perform our DB operations in our GraphQL resolvers. We also will simulate network lag, delaying reponses some random number of milliseconds.

Create a file /server.js and copy the following snippet in.

/* eslint-env node */
/* eslint-disable no-console */

import { ApolloServer } from 'apollo-server-koa';

import { readFileSync } from 'fs';

let TODOS;

const INITIAL_TODOS = [
  { id: '0', name: 'Get Milk', complete: false },
  { id: '1', name: 'Get Bread', complete: false },
  { id: '2', name: 'Try to Take Over the World', complete: false },
];

function initTodos() {
  TODOS = [...INITIAL_TODOS];
}

function byId(id) {
  return x => x.id === id;
}

function getNextId() {
  const last = TODOS.map(x => x.id).sort().pop();
  return (parseInt(last ?? '-1') + 1).toString();
}

async function randomSleep(max = 800) {
  await new Promise(r => setTimeout(r, Math.random() * max));
}

initTodos();

const server = new ApolloServer({
  typeDefs: readFileSync(new URL('schema.graphql', import.meta.url), 'utf-8'),
  context: {
    getTodo(id) {
      const todo = TODOS.find(byId(id));
      if (!todo)
        throw new Error(`TODO ${id} not found`);
      return todo;
    },

    async getTodos() {
      await randomSleep();
      return TODOS;
    },

    async addTodo({ name, complete }) {
      await randomSleep();
      const todo = { id: getNextId(), name, complete };
      TODOS.push(todo);
      return todo;
    },

    async updateTodo({ id, name, complete }) {
      await randomSleep();
      const todo = server.context.getTodo(id);
      todo.name = name ?? todo.name;
      todo.complete = complete ?? todo.complete;
      return todo;
    },

    async deleteTodo(id) {
      await randomSleep();
      server.context.getTodo(id);
      TODOS = TODOS.filter(x => x.id !== id);
      return TODOS;
    },
  },
  resolvers: {
  },
});

/** Attaches the Apollo server to web dev server */
export function graphqlTodoPlugin() {
  return {
    name: 'graphql-todo-plugin',
    async serverStart({ app, config }) {
      await server.start();
      server.applyMiddleware({ app });
      console.log(`🚀 GraphQL Dev Server ready at http://localhost:${config.port}${server.graphqlPath}`);
    },
  };
}

The Resolvers

With that accomplished, our next task is to define resolvers for each of the operations in our schema: todos, createTodo, updateTodo, and deleteTodo.

Ccopy the following snippet into the resolvers block of server.js:

Query: {
  async todo(_, { todoId }, context) {
    await randomSleep();
    return todoId ? context.getTodo(todoId) : null;
  },
  async todos(_, __, context) {
    return context.getTodos();
  },
},
Mutation: {
  async createTodo(_, { input: { name, complete = false } }, context) {
    return context.addTodo({ name, complete });
  },
  async updateTodo(_, { input: { todoId, name, complete } }, context) {
    return context.updateTodo({ id: todoId, name, complete });
  },
  async toggleTodo(_, { todoId }, context) {
    const todo = await context.getTodo(todoId)
    return context.updateTodo({ ...todo, complete: !todo.complete });
  },
  async deleteTodo(_, { input: { todoId } }, context) {
    await context.deleteTodo(todoId);
    return context.getTodos();
  },
},

Since we’re relying on the context functions we defined earlier, our resolvers can stay simple.

The Server

Our backend code is almost ready to go, all we have to do is hook it up to our frontend via the dev server. We need to add two custom dev server plugins:

1. graphqlTodoPlugin, which loads our graphql server code on the /graphql route, and
2. resolveCodegenPlugin to make sure the dev server loads graphql operations from the code-generated typescript files instead of their graphql sources. @apollo-elements/create/helpers.js exports this one for your convenience.

Replace the contents of web-dev-server.config.js with the following snippet:

import { esbuildPlugin } from '@web/dev-server-esbuild';
import { fromRollup } from '@web/dev-server-rollup';
import { graphqlTodoPlugin } from './server.js';
import { resolveCodegenPlugin } from '@apollo-elements/create/helpers.js';

import _litcss from 'rollup-plugin-lit-css';

const litcss = fromRollup(_litcss);

export default {
  nodeResolve: true,
  port: 8004,
  appIndex: 'index.html',
  rootDir: '.',
  mimeTypes: {
    'src/components/**/*.css': 'js',
  },
  plugins: [
    esbuildPlugin({ ts: true }),
    resolveCodegenPlugin({ ts: true }),
    graphqlTodoPlugin(),
    litcss({
      include: 'src/components/**/*.css',
      exclude: 'src/style.css',
    }),
  ],
};

The Apollo Client

Our Apollo Client uses HttpLink to connect to the backend server.

To make sure the todo-list renders the latest data, define a type policy which replaces the entire cached todo list every time the todos query updates. Replace the typePolicies config object with:

typePolicies: {
  Query: {
    fields: {
      location(): Location {
        return locationVar();
      },
      todos: {
        /** overwrite previous array when updating todos. */
        merge(_, next) {
          return next;
        },
      },
    },
  },
},

The App Shell

Next we’ll use the URLPattern proposal polyfill to set up some client-side routing. Open up src/router.ts and paste in the following.

import { makeVar } from '@apollo/client/core';
import { installRouter } from 'pwa-helpers/router';
import { URLPattern } from 'urlpattern-polyfill';

const pattern = new URLPattern({
  pathname: '/todos/:todoId',
});

function makeLocation(location = window.location) {
  const { assign, reload, replace, toString, valueOf, ...rest } = location;
  return {
    __typename: 'Location',
    ...rest,
    todoId: pattern.exec(new URL(rest.href))?.pathname?.groups?.todoId ?? null,
  };
}

function update(location = window.location) {
  locationVar(makeLocation(location));
}

export const locationVar = makeVar(makeLocation());

export async function go(path: string): Promise<void> {
  history.pushState(null, 'next', new URL(path, location.origin).toString());
  await new Promise(r => requestAnimationFrame(r));
  update();
}

installRouter(update);

Now we’re ready to start writing our UI components.

Reading Todos

Let’s define a query to display our list. Edit /src/components/app/App.query.graphql so that our app shell gets the list of todos:

query AppQuery {
  location @client { pathname }
  todos {
    id
    name
    complete
  }
}

Our next step is to add the query operation to our app shell component and render it’s data. Next let’s define the component’s template in src/components/list/list.ts,

render(): TemplateResult {
  const todos = this.query.data?.todos ?? [];
  return html`
  <sl-card>
    <h2 slot="header">To-Do List</h2>
    <ol>${todos.map(({ name, id, complete }) => html`
      <li>
        <sl-icon name="${complete ? 'check-square' : 'square'}"></sl-icon>
        <a href="/todos/${id}">${name}</a>
      </li>`)}
    </ol>
  </sl-card>
  `;
}

add some styles in src/components/app/app.css,

:host {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(0, auto));
  gap: 12px;
}

ol {
  width: 100%;
  list-style-type: none;
  padding: 0;
}

li {
  display: flex;
  align-items: center;
  gap: 4px;
}

sl-card {
  width: 100%;
}

sl-card, sl-card::part(base) {
  height: 100%;
}

sl-card::part(header) {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

And don’t forget to load the module in src/main.ts.

import './components/list';

We’ve fulfilled the first of our requirements: we can read the list of todos!

1. Display todo-list
2. Add new todos
3. Edit todos
4. Delete todos

Now we’ll move on to the next step by adding a mutation operation to our component.

Adding Todos

Let’s define our operation in src/components/app/CreateTodo.mutation.graphql. The createTodo operation takes a TodoInput object and returns a Todo.

mutation CreateTodo($input: TodoInput!) {
  createTodo(input: $input) {
    id
    name
    complete
  }
}

Add that mutation to our component by importing and instantiating an ApolloMutationController with an update function that appends the new todo to the cached list. For the UI, let’s add an icon-button to the header of our main card, and have it toggle a dialog with a form for the new item.

@query('sl-input') input: HTMLInputElement;
@query('#new-dialog') newDialog: SLDialog;

query = new ApolloQueryController(this, AppQuery);

mutation = new ApolloMutationController(this, CreateTodo, {
  update: (cache, result) => {
    const cached = cache.readQuery({ query: AppQuery, returnPartialData: true });
    cache.writeQuery({
      query: AppQuery,
      data: {
        ...cached,
        todos: [
          ...cached.todos,
          result.data.createTodo,
        ],
      },
    });
  },
});

render(): TemplateResult {
  const todos = this.query.data?.todos ?? [];
  return html`
  <sl-card>
    <h2 slot="header">To-Do List</h2>
    <sl-tooltip slot="header" content="Add Todo">
      <sl-icon-button name="plus-circle"
                      label="Add Todo"
                      @click="${() => this.newDialog.show()}"></sl-icon-button>
    </sl-tooltip>
    <ol>${todos.map(({ name, id, complete }) => html`
      <li>
        <sl-icon name="${complete ? 'check-square' : 'square'}"></sl-icon>
        <a href="/todos/${id}">${name}</a>
      </li>`)}
    </ol>
  </sl-card>

  <sl-dialog id="new-dialog" label="New To-Do Item">
    <sl-input ?disabled="${this.mutation.loading}"></sl-input>
    <sl-button slot="footer" @click="${this.addTodo}">Add Todo</sl-button>
  </sl-dialog>
  `;
}

private async addTodo() {
  try {
    await this.mutation.mutate({
      variables: { input: { name: this.input.value } },
    });
    this.input.value = '';
    this.input.blur();
    this.newDialog.hide();
  } catch (e) {
    console.error(e);
  }
}

Nice! Two requirements down, two to go:

1. Display todo-list
2. Add new todos
3. Edit todos
4. Delete todos

Toggling Todos

Our todo-list will have two different ways to update a todo, toggling it’s complete status, and editing it’s content. For the toggle operation, let’s create and import ToggleTodo.mutation.graphql:

mutation ToggleTodo($todoId: ID!) {
  toggleTodo(todoId: $todoId) {
    id
    name
    complete
  }
}

And for the UI, let’s import @apollo-elements/components/apollo-mutation for a quick one-off. This component will sit in place of the complete icon in our app’s template. We’ll add a data-todo-id attribute on <apollo-mutation> to define a single todoId variable for the element, and we’ll set refetch-queries and await-refetch-queries attributes to tell Apollo client to update the list of Todos after mutating, and to keep loading true until that request resolves. We could do without those, but this way the user gets a nicer experience. refetch-queries is a declarative alternative to a mutation update function. See the finished code for an example using updater. The trigger attribute on the slotted button tells <apollo-mutation> to execute when the user clicks, the element will also manage the disabled state of the button for you. Check out the <apollo-mutation> docs for more info.

<li>
  <apollo-mutation data-todo-id="${id}"
                  .mutation="${ToggleTodo}"
                  .optimisticResponse={{ toggleTodo: { __typename: 'Todo', complete: !complete, id, name } }}>
    <sl-icon-button trigger name="${complete ? 'check-square' : 'square'}"></sl-icon-button>
  </apollo-mutation>
  <a href="/todos/${id}">${name}</a>
</li>

Editing Todos

So far we’ve been adding on to the app shell component for each new feature. At this point our app.ts file is over 100 lines long. Not terrible, but starting to approach the area we’d want to break it up. For our editing feature, let’s define a new <todo-edit> element with its own mutation operation. We’ll fire up the good old generator to scaffold the files:

npm init @apollo-elements -- \
    component \
  --name todo-edit \
  --type mutation \
  --operation-name UpdateTodo
  --subdir '' \
  --overwrite \

At the editor prompt, paste in the following:

mutation UpdateTodo($input: TodoInput!) {
  updateTodo(input: $input) {
    id
    name
    complete
  }
}

Just like before, we’ll define the template and styles. The component features an input field for the text of the todo with a checkbox to indicate the todo’s status. Hitting the enter key on or blurring the input, or toggling the checkbox initiates the mutation.

@property({ attribute: 'data-id' }) todoId?: string;
@property({ attribute: 'data-name' }) todoName?: string;
@property({ attribute: 'data-complete', type: Boolean }) complete?: boolean;

@query('sl-input') input: HTMLInputElement;
@query('sl-checkbox') checkbox: HTMLInputElement;

render(): TemplateResult {
  return html`
    <sl-input label="To-Do Item"
              value="${this.todoName}"
              @keyup="${event => event.key === 'Enter' && this.mutate()}"
              ?disabled="${this.mutation.loading}"></sl-input>
    <sl-checkbox ?checked="${this.complete}"
                 ?disabled="${this.mutation.loading}"
                 @click="${this.mutate}">Complete</sl-checkbox>
  `;
}

mutate(): void {
  this.mutation.mutate({
    variables: {
      input: {
        todoId: this.todoId,
        name: this.input.value,
        complete: this.checkbox.checked,
      },
    },
  });
}