Generate commands

vitnode generate (alias vitnode g) writes plugin API code and registers it where VitNode reads it: a new module goes into buildApiPlugin({ modules }) or its parent module's modules, and a new route goes into its module's routes. Nothing is discovered at runtime, so src/config.api.ts still shows every module the plugin serves.

Where to run itCopy Anchor Link

Run it inside the plugin, through the plugin's own vitnode:

cd plugins/site-notes
pnpm vitnode g module notes

The workspace root does not depend on @vitnode/core, so pnpm vitnode is not found there. From the root, point pnpm at the plugin:

pnpm --filter site-notes exec vitnode g module notes

Which plugin it writes toCopy Anchor Link

When several plugins qualify and there is no terminal to ask (CI, a script), the command lists them and exits with code 2. Pass --project to choose.

Only plugins can be targets. The plugin needs src/config.api.ts and the plugin-bound builders in src/api/builders.ts; create-vitnode-app --plugin writes both. When builders.ts is missing, the generator creates it from src/manifest.gen.ts, with all five bound builders:

import { bindApiPlugin } from "@vitnode/core/api/lib/bind-api-plugin";

import { manifest } from "@/manifest.gen";

const apiBuilders = bindApiPlugin(manifest);

/** The API builders, bound to this plugin's id. */
export const buildModule = apiBuilders.buildModule;
export const buildRoute = apiBuilders.buildRoute;
export const buildQueueTask = apiBuilders.buildQueueTask;
export const defineCacheEntry = apiBuilders.defineCacheEntry;
export const defineEvent = apiBuilders.defineEvent;

When src/manifest.gen.ts is missing too, run vitnode build in the plugin once to write it. An existing builders.ts must export at least buildModule and buildRoute.

OptionsCopy Anchor Link

Every generate command accepts:

In an interactive terminal, the command asks for anything it cannot work out, such as a missing parent module or a route's method. Without one (CI, a script), it stops and names the flag to pass.

g moduleCopy Anchor Link

vitnode g module <path>:

g routeCopy Anchor Link

vitnode g route <module path>/<route name>:

--permission and --declare-permission only apply to routes in the admin module tree. On any other route they stop the command.

g serviceCopy Anchor Link

vitnode g service <module path> takes --admin, with the same meaning as for modules. The module must already exist. It writes createXService = (_deps: XServiceDeps) => ({}) with db as the only dependency and no operations, and changes no route.

g resource --kind apiCopy Anchor Link

vitnode g resource <name> --kind api:

The resource's module must be new or have no routes yet. The generator creates no table, migration or storage. Every service operation rejects with a <Name>NotImplementedError until you implement it, and each route maps that error to 501 with { "error": "not_implemented", "message": "..." }, declared in its responses.

g resource --kind contentCopy Anchor Link

vitnode g resource <name> --kind content takes:

The name is a single segment, such as articles; --admin and --permission-module do not apply. The result is administrative only, with no public API, member writes or publication, and the command never writes or applies a migration. See Generate a content type for the files it writes and how it handles permissions.

Route names and pathsCopy Anchor Link

Every route gets its own file in the module's routes/ folder. notes/list writes src/api/modules/notes/routes/list.route.ts, and notes.module.ts imports it from ./routes/list.route.

A route's file name and its URL are separate. These five names imply a method and a path:

Any other name needs --method and --path, or answers to the prompts in an interactive terminal. archive.route.ts is not served at /archive unless you say so.

What a generated route doesCopy Anchor Link

• GET answers 200 with sample data, { "sample": true, "message": "..." } plus any path parameters, and a response schema that matches it exactly. Replace both.
• POST, PUT and PATCH validate their path parameters and a JSON body, an empty z.object({}) for you to fill in. DELETE validates only its path parameters. All four answer 501 Not Implemented, so a client never sees a fake success.
• Admin routes add adminStaffPermission with a typed reference, such as staffPermissions.admin.notes.canCreate, and a 403 response. The permission must be declared in src/staff-permissions.ts, or added with --declare-permission. When the plugin's admin module mounts Content Engine modules and the permission module is not declared, g route only warns, because a content type may declare it. g resource --admin always requires declared permissions.

A staff permission decides who may call a route. It does not check access to a particular record, so do that in the handler when it matters.

Safety rulesCopy Anchor Link

• Dry run first. --dry-run resolves, validates and formats everything, then prints the exact diff instead of writing.

• No overwrites. An existing file, an identifier the target file already declares, or a module name already registered stops the command before anything is written. There is no --force.

• No duplicate endpoints. A new route is checked against every route the plugin's module tree reaches, and against the other routes of the same command, such as a resource's five. Full paths are joined the way Hono mounts modules, so a notes route GET /drafts and a notes/drafts route GET / are both GET /notes/drafts. Parameter names don't count (/{id} and /{noteId} are the same route), but a trailing slash does, because routing is strict. The error names the method and path, the route that already answers it, and where the new one would go:

  Copy Text

  ✖ GET /notes/drafts already exists.
    listDraftsRoute in src/api/modules/notes/drafts/routes/list.route.ts (module "notes/drafts") answers GET /notes/drafts.
    Destination: showDraftsNotesRoute in src/api/modules/notes/routes/show-drafts.route.ts (module "notes", path /drafts).
    Nothing was written.

  A module registered under several parents is checked at every mount. If first and second both list notesModule, its GET /items answers both GET /first/notes/items and GET /second/notes/items, and a new route on either path is refused.

  The generator cannot check parts of the tree it cannot read: the Content Engine modules under /admin/content, a module entry it cannot resolve, or a module that mounts itself through its own children. A new route under one of them is still written, with a warning that the check is incomplete.

• Names are kept, not rewritten. Module and route names are lower-case kebab-case, because a module name is its URL segment. myNotes is refused with a suggestion (my-notes). .., absolute paths and backslashes are refused outright.

• Edits are surgical. The generator parses your files and inserts text at exact positions, so comments, options and the VitNodeApiPlugin type stay as they were. New imports go in alphabetical order within their group.

• Formatting follows the project. New and changed files are formatted with the project's own oxfmt and config. A file you edited earlier is formatted only if it was already formatted, so the diff never touches code the generator did not add. Without oxfmt in the project, the summary says the code was not formatted.

• Writes are checked and rolled back. Every file is re-read just before writing; if one changed in the meantime, nothing is written. If a write fails halfway, the files already written are restored. A crash during the final renames can still leave some files written, which is why the summary lists every file.

Supported source patternsCopy Anchor Link

The generator reads your source and never runs it. It follows these patterns:

buildApiPlugin({
  manifest,
  modules: [notesModule, adminModule],
  permissionStaff: staffPermissions,
});

export const staffPermissions = defineStaffPermissions(manifest, {
  admin: { notes: ["can_create"] },
});

import { adminNotesModule } from "./notes/notes.module";

export const adminModule = buildModule({
  name: "admin",
  routes: [],
  modules: [adminNotesModule],
});

• modules and routes are array literals, and name is a string literal.
• Each array entry is an identifier that resolves to a const x = buildModule({...}) or buildRoute({...}) in the plugin, declared in the same file or imported with @/ or a relative path.
• buildContentAdminModule(...) and buildContentPublicModule(...) are recognized as the generated content module. They take no hand-written routes or child modules.
• permissionStaff is an identifier for an exported defineStaffPermissions(manifest, {...}) call in another file of the plugin, normally staffPermissions in src/staff-permissions.ts, whose admin entry is an object literal with array literals inside. The generator reads and declares permissions in that call, and generated routes import the export and use typed references such as staffPermissions.admin.notes.canCreate. An inline object, or a definition inside config.api.ts, stops the command with the steps to move it. See Permission references.

Other shapes, such as a spread inside modules, a variable holding the array, or a module from another package, stop the command when it has to search or edit that array. It writes nothing and prints the lines to add by hand. Elsewhere in the tree such entries only limit the duplicate-endpoint check, with a warning. A route whose method or path cannot be read also gets a warning, since the check could not cover it.

Which property the generator editsCopy Anchor Link

An object literal can name the same property twice or merge in a spread, and JavaScript keeps the value that comes last. The generator reads and edits only that effective property. This applies to modules, routes, permissionStaff, its admin entry and each module entry in it, and the contentTypes of buildContentAdminModule(...) and adminNav:

When it stops, it names the line that decides and what to change by hand:

✖ The modules of buildApiPlugin cannot be read or edited safely.
  At src/config.api.ts:15: a spread after modules may replace it.
  Nothing was written.
  To wire it by hand:
    Create notes/notes.module.ts next to the parent module (src/api/modules/ for a top-level one):
      export const notesModule = buildModule({ name: "notes", routes: [] });
    Import notesModule in src/config.api.ts and add it to buildApiPlugin({ modules }).

After generatingCopy Anchor Link

• Types. The plugin's own pages see new routes at once: its types/api-registry.gen.d.ts imports VitNodeApiPlugin from src/config.api.ts, so nothing needs regenerating. An app sees them once the plugin's declarations are rebuilt, which vitnode dev does on save; otherwise run vitnode build in the plugin. See How the fetcher knows your routes.
• URLs. A plugin is mounted at /{plugin id} under the app's API base path, /api in the starter apps. notes/list in site-notes answers GET /api/site-notes/notes.
• Checks. After a build, run vitnode plugin validate to load the plugin the way an app does, and vitnode doctor to find unregistered modules, undeclared permissions and duplicate endpoints.

RelatedCopy Anchor Link