@dharayush7/fireclass-cli

Framework-aware Fireclass setup, typed model generation, configuration inspection, and project diagnostics.

CLI documentation | Configuration | Packages | GitHub | npm

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.