runable create

Use runable create to configure a Runable application interactively. The command presents the application workflows and then asks only the questions needed for the selected workflow.

pnpm create runable@latest

npm create runable@latest

yarn create runable

bun create runable@latest

deno -A npm:create-runable@latest

If @runablejs/cli is already installed in the project, the equivalent command is:

runable create

Create an application

Running the command without an option presents two choices:

• Add to an existing project — wires Runable into a backend project you already have.
• Start with a starter — scaffolds a new project from a full starter template.

The module workflow is intentionally not included in this prompt. Use the dedicated --module option when authoring a reusable module.

The starter workflow asks for a project name, backend framework, package manager, and whether dependencies should be installed. It includes complete templates for Express, Fastify, NestJS, AdonisJS, Hono, and Koa.

Each starter contains:

• a backend entry point with an /api/health route and the matching Runable adapter;
• a Vue application with a ready-to-edit home page;
• runable.config.ts with server-side rendering enabled;
• development, build, prepare, and typecheck scripts;
• the runtime and development dependencies required by the selected backend.

After creation, start the project with the selected package manager's dev script. The generated server listens on http://localhost:3000 by default.

Create a Runable module

Pass --module to skip the application selector and start the module scaffolder directly:

pnpm create runable@latest --module

npm create runable@latest -- --module

yarn create runable --module

bun create runable@latest --module

deno -A npm:create-runable@latest --module

With a locally installed CLI, run runable create --module.

The module workflow asks for:

1. Module name — a valid lowercase npm package name, optionally scoped.
2. Config key — the property consumers use in runable.config.ts; it defaults to the module name.
3. Backend framework — used by the generated playground application.
4. Package manager — detected from the current project when possible.
5. Install dependencies now?

It creates a new directory named after the module. The generated package contains AGENTS.md, TypeScript configuration, a publishable package.json, and a minimal runable.config.ts defined with defineModule(). Application files and backend code live in the playground rather than the module root. Because the framework packages are only needed to develop and build the module, runable, vue, and vue-router are added to root devDependencies rather than runtime dependencies.

It also creates a playground/ Runable application for developing the module locally using the selected backend starter. Its runable.config.ts writes generated output to the module root and declares modules: [".."], so it always loads the module locally without requiring the package to be published. Use playground:prepare and playground:build from the module root to run the corresponding Runable commands against that application. The playground has its own private package.json and is registered as a workspace of the module.

See Modules for the module API and authoring conventions.

Add to an existing project

Prompts, in order:

1. Backend framework — Express, Fastify, NestJS, AdonisJS, Hono, Koa, or "Other" (you configure the adapter yourself).
2. Directories — appDir (default app), outputDir (default .app), distDir (default .output), publicDir (default public). Press enter to accept the default.
3. Server entry file — offered only when a template exists for the selected framework (currently Express only). Declining, or picking another framework, skips this step; wire the adapter into your existing entry point manually — see Integrations for your backend.
4. Package manager — auto-detected from a lockfile in the current directory when possible.
5. Install dependencies now?

This mode then:

• copies the default Vue application into appDir (see app/);
• creates AGENTS.md at the project root;
• generates runable.config.ts with the chosen directories (see runable.config.ts);
• adds runable, vue, and vue-router to dependencies, and @runablejs/cli plus app:build/app:prepare scripts, into an existing package.json — without touching anything already declared there (see package.json);
• copies the server entry file, if requested;
• installs dependencies, if requested.

Any file that already exists (an app directory, server.ts, AGENTS.md, runable.config.ts) triggers an overwrite confirmation instead of being silently replaced.