Build - WunderGraph

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:

Detect Plugin Language For Building: The language of the plugin is detected based on the presence of a go.mod file for Go; if it does not exist, we check for a package.json file for TypeScript. If none of these conditions match, the command fails.
Generate Proto and Mapping Files: Processes your GraphQL schema to generate Protocol Buffers definitions and mapping files.
Generate gRPC Code: Uses the generated Proto files to create Go code for the gRPC service.
Install Language Specific Dependencies: Installs all required dependencies for your plugin.
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
bun	^1.2.15	GitHub Releases

When building TypeScript plugins, the protoc TS/JS equivalents of the above are obtained via the .bin folder in your plugin's node_modules; these versions can be customized by the package.json of the TS plugin.

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 code in the generated/ directory.
Compiled binaries and any relevant accompanying files 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.