To use plugins that are not bundled with the default Apollo Router distribution you will need to create your own Apollo Router binary.

This page will walk you through creating your own Router binary from scratch, and creating a simple plugin.

Prerequisites

To compile the Apollo Router you will need to have the following installed.

• rust 1.61.0
• nodejs 16.9.1

Once you have the basics installed, install cargo-xtask and cargo-scaffold

1
cargo install cargo-xtask
2
cargo install cargo-scaffold

Create new project

1. Use cargo-scaffold to create the project.

   1
   cargo-scaffold scaffold https://github.com/apollographql/router.git -r apollo-router-scaffold/templates/base

   Copy

   You will be asked some questions about your project. For the purposes of this tutorial name your project starstuff.

2. After the project has been created change to the starstuff directory

   1
   cd starstuff

   Copy

   The generated project has the following layout:

1
starstuff
2
├── Cargo.toml       # Dependencies are declared here
3
├── README.md
4
├── router.yaml      # Router yaml config
5
├── src
6
│   ├── main.rs      # Entry point.
7
│   └── plugins      # Custom plugins are located here.
8
│       └── mod.rs
9
└── xtask            # Build support files
10
    ├── Cargo.toml
11
    └── src
12
        └── main.rs

The Apollo Router uses an auto discovery mechanism for plugin discovery, so any plugins that are added via dependency will automatically be available to the Router at runtime.

Compile the Router

To create a debug build use the following command.

1
cargo build

Your debug binary is now located in target/debug/router

For production, you will want to create a release build.

1
cargo build --release

Your release binary is now located in target/release/router

Run the Apollo Router

1. Download the example schema

   1
   curl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql

   Copy

2. Run the Apollo Router

   During development it is convenient to use cargo run to run the Apollo Router as it will

   1
   cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql

   Copy

Create a plugin

1. From within your project directory scaffold a new plugin

   1
   cargo router plugin create hello_world

   Copy

2. Select the type of plugin you want to scaffold:

   1
   Select a plugin template:
   2
   > "basic"
   3
   "auth"
   4
   "tracing"

   Copy

   The different templates are:

   • basic - a barebones plugin.
   • auth - a basic authentication plugin that could make an external call.
   • tracing - a plugin that adds a custom span and a log message.

   Choose basic.

3. Add the plugin to the router.yaml

   1
   plugins:
   2
     starstuff.hello_world:
   3
       message: "starting my plugin"

   Copy

4. Run the Apollo Router and see your plugin start up

   1
   cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql

   Copy

   In your output you should see something like:

   1
   2022-05-21T09:16:33.160288Z  INFO router::plugins::hello_world: starting my plugin

   Copy

Remove a plugin

From within your project run the following command. It makes a best effort to remove the plugin, but your mileage may vary.

1
cargo router plugin remove hello_world