Serverless Tool
Scaffold a distributable serverless tool with one npm-installed command line interface and one service that each consumer deploys to their own account.
Why Use This Command?
- Keeps the CLI and hosted service in one versioned workspace instead of treating the deployment platform as the product.
- Shares one checked, tested CLI foundation across every deployment target.
- Selects exactly one provider adapter: Cloudflare Workers or Vercel Functions.
- Includes local development, production builds, deployment, log tailing, and Vitest coverage for the selected platform.
Requirements
- Node.js runtime — Use any Node.js LTS release.
- Provider account — Deployment requires either a Cloudflare or Vercel account after the scaffold is created.
- Empty directory or monorepo root — Nova auto-detects whether to create a project or add the tool.
Usage
Options
| Flag | Description |
|---|---|
-d, --dry-run | Validate and preview the scaffold without writing files. |
--install | Install dependencies after scaffolding; this is the default. |
--no-install | Skip dependency installation. |
--name <name> | Project slug when creating a new monorepo; omit at an existing root. |
--non-interactive | Require every answer as a flag and do not open prompts. |
--workspace-name <name> | Workspace directory, npm binary, and the variable portion of the generated package name. |
--output <dir> | Output directory. |
--target <target> | Select cloudflare-workers or vercel-functions; defaults to cloudflare-workers. |
Target Layers
| Target | Service entry point | Development service | Deployment command | Log command |
|---|---|---|---|---|
cloudflare-workers | src/worker/index.ts | wrangler dev | wrangler deploy | wrangler tail |
vercel-functions | api/index.ts | vercel dev | vercel deploy --prod | vercel logs --follow |
Both targets include the same bin/cli.mjs, src/program.ts, starter status command, Nova-style CLI header, and CLI tests. Provider-specific source, TypeScript projects, dependencies, and scripts come only from the selected target layer.
Default Homepage
Both targets serve the same self-contained service card for GET /, with a violet project-initial logo, the generated project name, a Running badge, and a primary link to the Nova documentation. When urls.repository is set in nova.config.json, the page also shows a ghost-style GitHub button that opens the escaped repository URL in a new tab. The GitHub button is omitted when no repository URL is configured. HEAD / returns the same status and headers without a response body.
The page markup stays isolated so it can be restyled without changing request routing:
| Target | Homepage module |
|---|---|
cloudflare-workers | src/worker/landing-page.ts |
vercel-functions | src/function/landing-page.ts |
Requests to paths without a page return the matching HTTP 404 status with this JSON response:
{
"status": "error",
"message": "Not found"
}
Methods other than GET and HEAD at the root return HTTP 405, an Allow: GET, HEAD header, and the same JSON shape with the message Method not allowed.
Non-Interactive Mode
nova scaffold tool serverless --non-interactive --name my-tool --workspace-name gateway --output ./my-tool --target cloudflare-workers
nova scaffold tool serverless --non-interactive --workspace-name gateway --output ./packages/gateway --target vercel-functions
Omitting --target in non-interactive mode preserves the Cloudflare Workers default.
Registration
Nova registers the workspace with the tool role and distributable policy. The generated npm package uses {project-name}-tool-{workspace-name} while its executable keeps the shorter workspace name.
Nova also registers a same-named file artifact with the selected provider's runtime files, CLI, package metadata, and compiled output. Cloudflare Workers and Vercel keep distinct layouts while sharing the same assembly contract.