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 install cargo-xtaskcargo install cargo-scaffold
cargo-scaffoldto create the project.cargo-scaffold scaffold https://github.com/apollographql/router.git -r apollo-router-scaffold/templates/base
You will be asked some questions about your project. For the purposes of this tutorial name your project
After the project has been created change to the
The generated project has the following layout:
starstuff├── Cargo.toml # Dependencies are declared here├── README.md├── router.yaml # Router yaml config├── src│ ├── main.rs # Entry point.│ └── plugins # Custom plugins are located here.│ └── mod.rs└── xtask # Build support files├── Cargo.toml└── src└── 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.
To create a debug build use the following command.
Your debug binary is now located in
For production, you will want to create a release build.
cargo build --release
Your release binary is now located in
Download the example schemacurl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql
Run the Apollo Router
During development it is convenient to use
cargo runto run the Apollo Router as it willcargo 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.
From within your project directory scaffold a new plugincargo router plugin create hello_world
Select the type of plugin you want to scaffold:Select a plugin template:> "basic""auth""tracing"
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.
Add the plugin to the
router.yamlplugins:starstuff.hello_world:message: "starting my plugin"
Run the Apollo Router and see your plugin start upcargo 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
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