![\"Fireclass](\"https://fireclass.ayushdhar.com/logo.png\"){kind=logo}
\n \n\n \n \n \n
\n Type-safe Firestore models for Next.js App Router with Firebase Admin, server-only boundaries, Server Actions, and RSC serialization.\n
\n\n\n Setup |\n API reference |\n App Router guide |\n GitHub |\n npm\n
\n\n@dharayush7/fireclass-ssr is the Fireclass runtime for Next.js App\nRouter. It combines the Firebase Admin model API with memoized initialization,\nServer Action error handling, and a React Server Component serialization bridge.\n\n## Runtime boundaries\n\n| Import | Environment | Purpose |\n| --- | --- | --- |\n| @dharayush7/fireclass-ssr | Server Components, Route Handlers, Server Actions | Models, Firebase Admin, actions, and serialization |\n| @dharayush7/fireclass-ssr/client | Client Components | Pure serialization types and date revival only |\n\n> **Never import the root entry in a Client Component.** It imports\n> server-only and Firebase Admin. Use the /client\n> entry for Serialized, serialize,\n> serializeList, and reviveDates.\n\n## Installation\n\n~~~bash\nnpm install @dharayush7/fireclass-ssr firebase-admin class-validator class-transformer reflect-metadata server-only\n~~~\n\nEnable decorators in the TypeScript configuration that compiles models:\n\n~~~jsonc\n{\n \"compilerOptions\": {\n \"experimentalDecorators\": true,\n \"emitDecoratorMetadata\": true\n }\n}\n~~~\n\n## Firebase credentials\n\nFor local development, add service-account values to a gitignored\n.env.local:\n\n~~~bash\nFIREBASE_PROJECT_ID=your-project-id\nFIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project-id.iam.gserviceaccount.com\nFIREBASE_PRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\"\n~~~\n\nCredential resolution order is:\n\n1. Explicit serviceAccount passed to getFireclass or\n initFireclassAdmin.\n2. FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, and\n FIREBASE_PRIVATE_KEY.\n3. Fallback aliases PROJECT_ID, CLIENT_EMAIL, and\n PRIVATE_KEY.\n4. Application Default Credentials.\n\nEscaped \\n sequences in private keys are restored automatically.\n\n> **No separate Firebase file is recommended.** Fireclass owns the memoized\n> Firebase Admin initialization through getFireclass().\n\n## Create the server binding\n\n~~~ts\n// src/lib/fireclass.server.ts\nimport \"reflect-metadata\";\nimport \"server-only\";\nimport { getFireclass } from \"@dharayush7/fireclass-ssr\";\n\nexport const { BaseModel, adapter } = getFireclass();\n~~~\n\nOnly initialized values belong in this local file. Import\nCollection, serializeList,\nrunAction, and other standalone helpers directly from the SDK.\n\n## Define a server-only model\n\n~~~ts\n// src/models/post.ts\nimport \"server-only\";\nimport { Collection } from \"@dharayush7/fireclass-ssr\";\nimport { IsDate, IsString, Length } from \"class-validator\";\nimport { Type } from \"class-transformer\";\nimport { BaseModel } from \"../lib/fireclass.server\";\n\n@Collection(\"posts\")\nexport class Post extends BaseModelrunAction returns:\n\n~~~ts\ntype ActionResultgetFireclass(options?) | Return the process-global BaseModel and AdminAdapter binding |\n| initFireclassAdmin(options?) | Initialize and cache Admin Firestore |\n| resetFireclassAdmin() | Clear Fireclass Admin references for isolated tests |\n| FireclassAdminOptions | Explicit credentials and project id |\n| runAction(fn) | Convert Fireclass errors into ActionResult |\n| serialize(model) | Convert one model to an RSC-safe plain object |\n| serializeList(models) | Convert a model list |\n| reviveDates(value, keys) | Convert selected top-level ISO strings back to Date |\n| Serialized | Recursive serialized model type |\n| Node and core exports | Models, decorators, queries, adapters, validation, and errors |\n\n### Initialization behavior\n\nThe first getFireclass() call initializes Firebase Admin and\ncreates the adapter. Later calls return the same object; later options do not\nreplace the cached binding.\n\ninitFireclassAdmin() reuses an existing Firebase Admin app when one\nexists. resetFireclassAdmin() clears Fireclass's Admin references\nbut does not delete Firebase Admin apps or clear an already-created\ngetFireclass() binding.\n\n### Serialization behavior\n\nserialize copies own enumerable fields and recursively converts\nDate values to ISO strings. Prototype methods are excluded.\n\nreviveDates creates a shallow copy and converts only selected\ntop-level string fields. It does not traverse nested paths.\n\n## CLI setup\n\nRun the CLI after credentials exist:\n\n~~~bash\nnpx fireclass init\nnpx fireclass doctor\nnpm run build\n~~~\n\nChoose Next.js App Router. The CLI writes fireclass.json, a\nserver-only Fireclass entry, environment templates, decorator flags, and a\nstarter model. It uses firebase: null because this SDK owns Admin\ninitialization.\n\n## Documentation and examples\n\n- [Next.js installation](https://fireclass.ayushdhar.com/docs/installation/nextjs)\n- [Complete SSR API](https://fireclass.ayushdhar.com/docs/api/ssr)\n- [Next.js App Router guide](https://fireclass.ayushdhar.com/docs/guides/nextjs)\n- [Core model API](https://fireclass.ayushdhar.com/docs/api/core)\n- [Runnable Next.js application](https://github.com/dharayush7/fireclass-cli/tree/main/example/fireclass-next-app)\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history and\n[RELEASE_NOTES.md](./RELEASE_NOTES.md) for the current release summary.\n\n## License\n\nMIT. Copyright Ayush Dhar.\n","readmeFilename":"README.md"}