Build

Build a gRPC router plugin

wgc router plugin build

The build command generates gRPC code based on your GraphQL schema and compiles your plugin into platform-specific binaries.

Usage

wgc router plugin build [options] [directory]

Arguments

Argument	Description	Default
directory	Directory of the plugin	. (current directory)

Options

Option	Description	Default
--generate-only	Generate only the proto and mapping files, do not compile the plugin	false
--go-module-path <path>	Go module path to use for the plugin	github.com/wundergraph/cosmo/plugin
--debug	Build the binary with debug information for use with debuggers	false
--platform [platforms...]	Platform-architecture combinations (e.g., darwin-arm64 linux-amd64)	Host platform
--all-platforms	Build for all supported platforms	false
--skip-tools-installation	Skip tool installation	false
--force-tools-installation	Force tools installation regardless of version check or confirmation	false

Description

This command performs several steps to build your plugin:

1. Generate Proto and Mapping Files: Processes your GraphQL schema to generate Protocol Buffers definitions and mapping files
2. Generate gRPC Code: Uses the generated Proto files to create Go code for the gRPC service
3. Install Go Dependencies: Installs all required Go dependencies for your plugin
4. Build Binaries: Compiles the plugin for one or more platform-architecture combinations

If you only want to generate code but not compile the binary (useful when you’re updating your GraphQL schema), you can use the --generate-only flag.

Required Tools

The build command will automatically check for and install the necessary toolchain (like protoc, protoc-gen-go, etc.) when required tools can’t be found in the right version on your system. You can control this behavior with the --skip-tools-installation and --force-tools-installation flags.

For debugging your plugin, use the --debug flag to build with debug symbols. This enables debugging with tools like Delve, GoLand, or VS Code. See the debugging guide for detailed instructions.

You can also install the dependencies manually and use an IDE with Go support. The following table shows the current versions and download links for the required tools:

Tool	Version	Installation Link
Go	>=1.22.0 (Last 2 versions)	Releases
Protocol Buffers (protoc)	^29.3	Releases
protoc-gen-go	^1.34.2	GitHub Releases
protoc-gen-go-grpc	^1.5.1	GitHub Releases

Examples

Build for the current platform

wgc router plugin build ./my-plugin

Generate code only

wgc router plugin build --generate-only ./my-plugin

Build for multiple platforms

wgc router plugin build --platform darwin-arm64 linux-amd64 ./my-plugin

Build for all supported platforms

wgc router plugin build --all-platforms ./my-plugin

Supported Platforms

The following platform-architecture combinations are supported:

Platform	Description	When to use
linux-amd64	Linux on 64-bit Intel/AMD processors	Most Linux servers, including AWS EC2, Google Cloud, Azure VMs
linux-arm64	Linux on 64-bit ARM processors	ARM-based servers, AWS Graviton instances, Raspberry Pi 4
darwin-amd64	macOS on Intel processors	Intel-based Mac development machines
darwin-arm64	macOS on Apple Silicon (M1/M2)	Apple Silicon Mac development machines
windows-amd64	Windows on 64-bit Intel/AMD processors	Windows servers or development machines

When using the --all-platforms flag, binaries for all of the above platforms will be built.

Output

The build process creates several outputs:

• Generated Go code in the generated/ directory
• Compiled binaries in the bin/ directory, named according to the target platform (e.g., my-plugin-darwin-arm64, my-plugin-linux-amd64)

After building, you can configure the Cosmo Router to use your plugin by referencing the appropriate binary in your router configuration.

Ensure that the platform of your built plugin matches the platform where your Cosmo Router runs. For example, if you build your plugin on a Mac (darwin-arm64) but deploy your router on Linux (linux-amd64), you’ll need to specify --platform linux-amd64 during the build process. Using an incompatible plugin binary will result in runtime errors when the router attempts to load the plugin.