5-Minute Quickstart

You have Node.js installed and five minutes free. That's enough to go from nothing to a plugin scaffold with passing tests, and to see how VeloCMS's own first-party plugins are structured. The result runs on your machine only: VeloCMS can't install a third-party plugin today.

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 and @velocms/plugin-types are published on npm as alpha releases, so expect breaking changes between versions. 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/. That output has the same shape as the bundles the V2 isolated-vm sandbox is designed to load. If tsc exits cleanly, the build is done. There is nowhere to upload it: VeloCMS doesn't install plugins from outside developers yet.

What's next?

The quickstart got you a working scaffold. The 30-minute tutorial walks through a complete example — 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.