fireclass init

init is the only command that can create fireclass.json. It detects the project environment, asks for framework-specific paths, scaffolds missing files, and optionally installs dependencies.

Usage

fireclass init [options]

Complete the Firebase prerequisites before running the command. React and Express projects should prepare their recommended Firebase entry first; the CLI references an existing file without overwriting it.

Options

Detection

Project root

The CLI walks upward from the current directory and selects the nearest folder containing package.json.

Framework

Framework detection reads dependencies and devDependencies in this order:

1. next → Next.js
2. express → Express / Node.js
3. react plus react-dom → React

Next.js wins over React because Next projects also declare React.

In interactive mode, the detected framework is only the initial selection. With --yes, detection must succeed unless --framework is supplied.

Package manager

Detection checks:

1. The packageManager field in package.json.
2. pnpm-lock.yaml, yarn.lock, bun.lockb / bun.lock, then package-lock.json.
3. The package-manager user-agent environment value.

Interactive mode lets you change the result. --yes falls back to npm when no manager is detected.

Interactive flow

The command asks for:

1. Framework and package manager.
2. Firebase file and named export for React/Express.
3. Fireclass entry file.
4. Models directory.
5. Permission to overwrite an existing Fireclass entry.
6. Permission to install dependencies.

Projects with a src directory default to:

src/lib/firebase.ts
src/lib/fireclass.ts
src/models

Projects without src default to:

lib/firebase.ts
lib/fireclass.ts
models

For Firebase exports, enter a value such as db or a factory such as getDb(). The trailing parentheses are stored as factory: true and make the generated entry call the function.

Framework behavior

Every framework also installs class-validator, class-transformer, and reflect-metadata. React adds firebase; Express adds firebase-admin; Next.js adds firebase-admin and server-only.

Generated artifacts

init writes or manages:

• fireclass.json with the public schema URL, CLI version, framework, package manager, SDK, paths, and exports.
• A framework-specific Fireclass entry exporting initialized BaseModel, adapter, and React hooks where applicable.
• A Firebase entry for React/Express only when the configured file is missing.
• A starter todo.ts model when it is missing.
• Decorator flags in the effective TypeScript configuration.
• Next.js .env.local and .env.example, or Express .env.example.
• Gitignore entries for .env.local or .env.

The Fireclass entry does not re-export decorators or helpers. Generated models import Collection from the runtime SDK and BaseModel from the local entry.

Idempotency and reconfiguration

• Existing Firebase files are referenced, never overwritten.
• Existing starter models are skipped.
• Missing environment keys and gitignore entries are appended.
• Existing Fireclass entries are skipped unless interactive reconfiguration explicitly approves overwriting.
• Existing fireclass.json is displayed before interactive reconfiguration; answering no leaves the project untouched.
• --yes re-runs configuration without the confirmation prompt, rewrites fireclass.json, and still skips an existing Fireclass entry.

Examples

npx fireclass init

npx fireclass init --yes --framework react --pm pnpm

npx fireclass init --yes --framework express --pm npm --skip-install

After --skip-install, install the dependencies reported by the CLI before running doctor.

Failures

The command exits non-zero when:

• No parent package.json exists or it cannot be parsed.
• --yes cannot detect a framework and none was supplied.
• Dependency installation fails.
• A generated file cannot be written or another setup operation throws.

Cancelling an interactive prompt exits immediately without continuing the remaining setup.