@devbie/fewbie-cli

Command-line tool for the Fewbie frontend framework. Scaffold Next.js projects from the Fewbie basic template, manage registry modules declared in fewbie.json, update framework-owned template files, and generate typed API request code from OpenAPI documents.

The generated projects use Next.js 16 (App Router), React 19 and Tailwind CSS v4, with shadcn-style UI primitives and design tokens already wired up.

Requirements

• Node.js >= 20

Installation

Run it directly with npx:

npx @devbie/fewbie-cli create my-app

Or install it globally:

npm install -g @devbie/fewbie-cli
fewbie --help

Quick start

# Scaffold a new project (writes an empty fewbie.json declaration)
npx @devbie/fewbie-cli create my-app

cd my-app
npm install
npm run dev

# Declare and install registry modules (dependencies installed automatically)
npx fewbie modules add api-client auth
npx fewbie modules add login-form

# Inspect project state
npx fewbie doctor
npx fewbie status

The fewbie.json declaration

The project root contains a declaration file that lists the registry modules the project enables:

{
  "modules": ["api-client", "auth", "login-form"]
}

It is the single source of truth for every module operation. A file that merely exists on disk (the starter template ships some registry files) does not count as installed. create writes an empty declaration; every other command reads or updates it.

Commands

fewbie create <project-name>

Create a new project from the Fewbie basic template.

fewbie modules

Bare invocation prints the module inventory. On a TTY it opens an interactive enable/disable picker; on a non-TTY (or with --json) it is read-only.

fewbie modules add <names...>

npm-style add: declares the named modules in fewbie.json and lands their files (dependency closure included, npm dependencies installed automatically).

fewbie modules apply

Reconcile the project with fewbie.json: restore missing files, land dependency closure members, install npm dependencies.

fewbie modules remove <names...>

Remove modules from the declaration. Files are deleted only while they are byte-identical to the registry copy; locally modified files are reported and kept. Removing a module still required by another declared module fails.

fewbie modules update [names...]

Update installed files to the registry source. Writes by default; missing files are reported as apply work rather than silently recreated.

fewbie template update [paths...]

Update framework-owned template files from the starter template. Pass path prefixes (e.g. src/app) to restrict the scope; no paths means every framework-owned asset.

Ownership follows ADR-025:

• framework-owned — overwritten by the template: next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs, components.json, .prettierignore, .env.example, src/instrumentation.ts, src/lib/utils.ts.
• mixed — only the block between /* fewbie:framework:start */ and /* fewbie:framework:end */ is updated (src/app/globals.css); host content outside the markers is preserved. A missing marker pair is reported, never guessed.
• host-owned — distributed once by create, never touched: src/app/layout.tsx, src/app/page.tsx, src/components/**, package.json, README.md, next-env.d.ts, AGENTS.md, CLAUDE.md.

fewbie apits [input]

Generate typed API request code from an OpenAPI document (a URL or a local JSON/YAML file). On the first run the command scaffolds apits.config.ts; subsequent runs generate the typed request layer via the @devbie/apits generator, installed into the project as a dev dependency.

fewbie doctor

Check project health: structure, the declared module set (from fewbie.json), partially installed modules, dependencies and design tokens. Missing fewbie.json is an error.

fewbie status

Print machine-readable project state as JSON (always JSON, no flag). Reports declared, installed, missing files and warnings, for automation.

Registry items

The built-in registry follows the shadcn item conventions (registry:lib, registry:component, registry:block):

An item whose target path also ships in the starter template must stay byte-identical to that template copy — fewbie create copies the whole template while fewbie modules add copies the item (and fewbie modules apply restores it on reconcile), so the same file has two delivery channels that fork if edited apart. npm run check:template-drift -w @devbie/fewbie-cli asserts this in CI and before publishing. npm run check:template-deps -w @devbie/fewbie-cli additionally compares the template's locked @devbie/* versions against npm latest (network; release checklist only).

Global options

Running fewbie with no arguments prints help and exits successfully.

Related packages

• @devbie/heartbeat-sdk — the basic template reports application liveness through instrumentation.ts when HEARTBEAT_ENDPOINT and HEARTBEAT_TOKEN are configured.
• @devbie/frontend-monitor-sdk — browser-side monitoring SDK available as the frontend-monitor-sdk registry item.

License

MIT