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

The only runtime dependency is @velocms/plugin-sdk. 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), admin settings UI, and how to push a draft to the marketplace review queue.