Try Apollo Studio

Creating a custom Apollo Router binary

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.

Note: The Apollo Router is made available under the Elastic License v2.0 (ELv2). Read our licensing page for more details.


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

cargo install cargo-xtask
cargo install cargo-scaffold

Create new project

  1. Use cargo-scaffold to create the project.

    cargo-scaffold scaffold -r apollo-router-scaffold/templates/base

    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

    cd starstuff

    The generated project has the following layout:

├── Cargo.toml # Dependencies are declared here
├── router.yaml # Router yaml config
├── src
│ ├── # Entry point.
│ └── plugins # Custom plugins are located here.
│ └──
└── xtask # Build support files
├── Cargo.toml
└── src

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.

cargo build

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

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

cargo build --release

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

Run the Apollo Router

  1. Download the example schema

    curl -sSL > supergraph-schema.graphql
  2. Run the Apollo Router

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

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

If you are using managed federation you can set APOLLO_KEY and APOLLO_GRAPH_REF environment variables instead of specifying the supergraph as a file.

Create a plugin

  1. From within your project directory scaffold a new plugin

    cargo router plugin create hello_world
  2. Select the type of plugin you want to scaffold:

    Select a plugin template:
    > "basic"

    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

    message: "starting my plugin"
  4. Run the Apollo Router and see your plugin start up

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

    In your output you should see something like:

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

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.

cargo router plugin remove hello_world
Edit on GitHub
Native Rust plugins
Rhai scripts (experimental)