The Fireclass CLI detects Next.js, React, and Express projects, installs the correct SDK, records project structure in fireclass.json, generates models, and verifies local setup.

The same CLI is available through the unscoped fireclass launcher.

Requirements

• Node.js 18 or newer.
• A project containing package.json.
• TypeScript for generated models.
• Firebase project and framework-specific Firebase initialization completed before fireclass init.

Prepare the runtime first:

• Next.js prerequisites and setup
• React prerequisites and setup
• Express prerequisites and setup

The CLI references existing Firebase files and never overwrites them.

Run the CLI

npx fireclass --help
npx fireclass init

Equivalent commands:

npx @dharayush7/fireclass-cli init
npx fireclass init

When installed locally, both binary names are available:

fireclass doctor
fc doctor

Command overview

| Command | Purpose | | --- | --- | | fireclass init | Detect the framework and configure Fireclass | | fireclass model <Name> | Generate a typed model | | fireclass doctor | Check dependencies, paths, exports, and TypeScript decorators | | fireclass list | List discoverable models and collections | | fireclass ls | Alias for list | | fireclass config | Print the resolved fireclass.json |

Global options:

| Option | Purpose | | --- | --- | | -h, --help | Print global or command help | | -v, --version | Print the CLI version |

Unknown commands, missing required arguments, and command failures exit non-zero.

Project resolution and detection

Every command walks upward from the current directory to the nearest folder containing package.json. In a workspace, the nearest package controls the configuration.

Framework detection reads dependencies and dev dependencies:

1. next selects Next.js.
2. express selects Express or Node.js.
3. react plus react-dom selects React.

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

Package-manager detection checks:

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

Interactive mode lets you change detected values. Non-interactive mode falls back to npm when no package manager is detected.

fireclass init

fireclass init [options]

| Option | Purpose | | --- | --- | | -y, --yes | Accept detected defaults without prompts | | --framework <next|react|express> | Override framework detection | | --pm <pnpm|yarn|bun|npm> | Override package-manager detection | | --skip-install | Generate configuration without installing dependencies | | -h, --help | Print command help |

Interactive setup asks for:

1. Framework and package manager.
2. Firebase file and named export for React or Express.
3. Fireclass entry file.
4. Models directory.
5. Permission before replacing an existing Fireclass entry.
6. Permission before dependency installation.

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(). Parentheses record factory: true, causing the generated binding to call the function.

Framework behavior

| Framework | SDK | Firebase behavior | | --- | --- | --- | | Next.js | @dharayush7/fireclass-ssr | No Firebase file; credentials come from environment variables or ADC | | React | @dharayush7/fireclass-react | Firebase client SDK with a default db export | | Express | @dharayush7/fireclass-js | Firebase Admin with a default getDb() factory |

All frameworks install 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 Firebase export.
• A framework-specific Fireclass entry exporting initialized BaseModel, adapter, and React hooks where applicable.
• A Firebase entry for React or Express only when the configured file is missing.
• A starter Todo 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 private environment files.

Generated Fireclass entries do not re-export SDK decorators or helpers.

Idempotency

• Existing Firebase files are referenced and never overwritten.
• Existing starter models are skipped.
• Missing environment keys and gitignore entries are appended.
• Existing Fireclass entries require interactive overwrite approval.
• Existing configuration is displayed before interactive reconfiguration.
• --yes rewrites configuration with detected or supplied values while still skipping an existing Fireclass entry.

Use explicit framework and package-manager options when automating configured projects:

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

fireclass model

fireclass model [options] <name>

| Option | Purpose | | --- | --- | | -c, --collection <name> | Override the Firestore collection | | --dir <path> | Override the configured models directory for this command | | --force | Replace an existing model file | | -h, --help | Print command help |

Naming examples:

| Input | Class | File | Default collection | | --- | --- | --- | --- | | User | User | user.ts | users | | user-profile | UserProfile | user-profile.ts | userprofiles | | Category | Category | category.ts | categories | | Status | Status | status.ts | status |

Pluralization is intentionally simple. Use --collection when the desired Firestore name differs.

npx fireclass model User
npx fireclass model user-profile --collection user_profiles
npx fireclass model Order --dir src/entities

The generated model imports Collection directly from the configured SDK and BaseModel from the local Fireclass entry. Express relative imports use a Node ESM-compatible .js suffix.

--force replaces the entire target file; it does not merge fields.

fireclass doctor

fireclass doctor

Doctor performs local, read-only checks:

| Check | Result | | --- | --- | | fireclass.json | Must exist and parse | | Runtime SDK | Must be declared in dependencies or dev dependencies | | Common dependencies | Validator, transformer, and metadata packages must be declared | | Framework dependencies | Firebase package and server-only where required | | Fireclass entry | Configured path must exist | | Firebase entry | React or Express path must exist | | Firebase export | Simple named variable/function export is inspected | | Models directory | Configured directory is inspected | | TypeScript decorators | Both required compiler flags are checked |

Passed checks do not affect exit status. Warnings still exit successfully. Failed checks set exit code 1, making doctor suitable for CI.

Doctor does not connect to Firebase, compile application source, test Security Rules or indexes, or execute models.

fireclass list

fireclass list
fireclass ls

The command scans top-level TypeScript files in models.dir, excludes index.ts, sorts by filename, and looks for a class extending BaseModel plus a string-literal @Collection.

User -> "users"  (user.ts)

Nested directories, computed collection names, decorator aliases, and unusual formatting are not executed or deeply parsed. An empty models directory is not an error.

fireclass config

fireclass config

Prints the nearest project's parsed fireclass.json. It never modifies the file and does not validate paths, exports, credentials, or the public schema. Run doctor after manual changes.

fireclass.json

Every generated configuration references the public schema:

{
  "$schema": "https://fireclass.ayushdhar.com/schema.json",
  "version": "2.1.17",
  "framework": "react",
  "packageManager": "pnpm",
  "package": "@dharayush7/fireclass-react",
  "firebase": {
    "path": "src/lib/firebase.ts",
    "export": "db",
    "factory": false
  },
  "fireclass": {
    "path": "src/lib/fireclass.ts"
  },
  "models": {
    "dir": "src/models"
  }
}

Next.js uses firebase: null. Express normally records getDb with factory: true. Configuration contains paths and metadata only; never put Firebase credentials in this file.

Import ownership

Keep generated local Fireclass files focused on app-bound values:

• BaseModel
• adapter
• useQuery and useDoc for React

Import decorators and standalone helpers directly from the runtime SDK:

import { Collection } from "@dharayush7/fireclass-js";
import { serialize, runAction } from "@dharayush7/fireclass-ssr";
import { ValidationFailedError } from "@dharayush7/fireclass-react";

Documentation and examples

• CLI overview
• init
• model
• doctor
• list
• config
• fireclass.json reference
• Express example
• Next.js example
• React example

See CHANGELOG.md for version history and RELEASE_NOTES.md for the current release summary.

License

MIT. Copyright Ayush Dhar.