5-Minute Quickstart

You have Node.js installed and five minutes free. That's enough to go from nothing to a working plugin scaffold with passing tests. Here's how.

Step 1 — Scaffold the plugin

Run the scaffolder anywhere you keep your projects. It prompts for a name, a slug, a category, and an author name — or pass --non-interactive to accept all defaults.

npx create-velocms-plugin my-first-plugin

The CLI creates a directory called my-first-plugin/ with a manifest, a runtime entry point, an optional admin component, a test file, and a tsconfig. It does not touch your global npm setup — every dependency is local to the plugin.

Step 2 — Install dependencies

cd my-first-plugin
npm install

Note: @velocms/plugin-sdk is not yet published on npm (coming Q3 2026). For now, fork the VeloCMS repository and import types directly from the source (src/lib/plugins/types.ts). Everything else is dev-only (TypeScript, Vitest). The total install is small — under 2 MB on disk.

Step 3 — Read the manifest

Open manifest.json. It's the single source of truth for what your plugin is allowed to do. The scaffolder generates a minimal example — notice that capabilities starts as ["content:read"], which is the lowest-risk option. You'll expand this only when your logic actually needs more access.

{
  "id": "com.yourname.my-first-plugin",
  "name": "My First Plugin",
  "version": "1.0.0",
  "description": "A minimal VeloCMS plugin",
  "capabilities": ["content:read"],
  "hooks": ["afterPostPublish"],
  "builtin": false,
  "enabled": true,
  "entry": "./dist/runtime.js"
}

Step 4 — Run the tests

npm test

Vitest runs the generated test file. The tests use @velocms/plugin-sdk/test-helpers — a lightweight in-memory mock of the VeloCMS runtime. No running server required. You should see four tests pass: manifest structure, required fields, handler execution, and the mock KV store.

Step 5 — Build

npm run build

TypeScript compiles to dist/. The output is what VeloCMS loads in the isolated-vm sandbox at hook invocation time. If tsc exits cleanly, the artifact is ready.

What's next?

The quickstart got you a working scaffold. The 30-minute tutorial builds something real — a Mailchimp sync that fires on every new member signup. It covers encrypted API key handling (critical for any integration that stores secrets) and how to build an admin settings UI, so the whole capability system clicks by the end.