Rudder Create Plugin

Create a Rudder Plugin

Use this skill when the task is to create, scaffold, or document a Rudder plugin.

1. Ground rules

Read these first when needed:

1. doc/engineering/PLUGIN_AUTHORING_GUIDE.md
2. packages/plugins/sdk/README.md
3. doc/engineering/PLUGIN_RUNTIME_CONTRACT.md only for future-looking context

Current runtime assumptions:

• plugin workers are trusted code
• plugin UI is trusted same-origin host code
• worker APIs are capability-gated
• plugin UI is not sandboxed by manifest capabilities
• no host-provided shared plugin UI component kit yet
• ctx.assets is not supported in the current runtime

2. Preferred workflow

Use the scaffold package instead of hand-writing the boilerplate:

pnpm --filter @rudderhq/create-rudder-plugin build
node packages/plugins/create-rudder-plugin/dist/index.js  --output 

For a plugin that lives outside the Rudder repo, pass --sdk-path and let the scaffold snapshot the local SDK/shared packages into .rudder-sdk/:

pnpm --filter @rudderhq/create-rudder-plugin build
node packages/plugins/create-rudder-plugin/dist/index.js @acme/plugin-name \
  --output /absolute/path/to/plugin-repos \
  --sdk-path /absolute/path/to/rudder/packages/plugins/sdk

Recommended target inside this repo:

• packages/plugins/examples/ for example plugins
• another packages/plugins// folder if it is becoming a real package

3. After scaffolding

Check and adjust:

• src/manifest.ts
• src/worker.ts
• src/ui/index.tsx
• tests/plugin.spec.ts
• package.json

Make sure the plugin:

• declares only supported capabilities
• does not use ctx.assets
• does not import host UI component stubs
• keeps UI self-contained
• uses routePath only on page slots
• is installed into Rudder from an absolute local path during development

4. If the plugin should appear in the app

For bundled example/discoverable behavior, update the relevant host wiring:

• bundled example list in server/src/routes/plugins.ts
• any docs that list in-repo examples

Only do this if the user wants the plugin surfaced as a bundled example.

5. Verification

Always run:

pnpm --filter  typecheck
pnpm --filter  test
pnpm --filter  build

If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.

6. Documentation expectations

When authoring or updating plugin docs:

• distinguish current implementation from future spec ideas
• be explicit about the trusted-code model
• do not promise host UI components or asset APIs
• prefer npm-package deployment guidance over repo-local workflows for production

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Undertone0809
• Source: Undertone0809/rudder
• License: Apache-2.0
• Homepage: https://rudder.zeeland.studio

Install and usage instructions live in the source repository linked above.