> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anonymous.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Firetype
> Typesafe ODM for Firestore - Complete guide to getting started
**Typesafe ODM for Firestore** - A lightweight wrapper that adds type safety and schema validation
to your Firestore database operations in TypeScript.
[](https://badge.fury.io/js/%40anonymous-dev%2Ffiretype)
[](https://opensource.org/licenses/MIT)
Firetype extends the existing Firestore SDK functionality while maintaining all its native features
and requiring the original SDK to be installed. It provides a folder-based schema definition system
that automatically generates fully type-safe APIs for your Firestore collections and documents.
⚠️ **Important**: Firetype extends the Firestore SDK and is not a replacement. You'll still need
to install and use either `firebase-admin` or `firebase/firestore` as your primary SDK.
## ✨ Features
* 🎯 **Full Type Safety**: Complete TypeScript type inference for all Firestore operations with zero
runtime overhead
* 📁 **Folder-Based Schema**: Organize your database structure naturally in directories, including
nested collections
* 🔄 **Runtime Validation**: Optional Zod-powered schema validation with detailed error messages
* 🛠️ **Powerful CLI**: Generate type definitions with flexible configuration options
* ⚡ **SDK Agnostic**: Works seamlessly with both `firebase-admin` and `firebase/firestore` SDKs
* 🔗 **Nested Collections**: Full support for subcollections with automatic path generation
* 📊 **Collection Groups**: Type-safe collection group queries across all subcollections
* 🎨 **Zero Config**: Just define your schemas and let Firetype handle the rest
## 📦 Installation
Install Firetype using your preferred package manager:
```bash theme={null}
# npm
npm install @anonymous-dev/firetype
# yarn
yarn add @anonymous-dev/firetype
# pnpm
pnpm add @anonymous-dev/firetype
# bun
bun add @anonymous-dev/firetype
```
### Peer Dependencies
Firetype requires one of the following Firestore SDKs (choose based on your environment):
```bash theme={null}
# For server-side applications (Node.js, Cloud Functions, etc.)
npm install firebase-admin
# For client-side applications (browsers, React Native, etc.)
npm install firebase
```
💡 **Tip**: Firetype works with both SDKs simultaneously if you need to support both client and
server environments.
## 🚀 Quick Start
Get started with Firetype in 5 minutes. This guide shows you how to set up type-safe Firestore
operations.
### 1. Set up your schema directory
Create a directory structure for your Firestore database schemas:
```bash theme={null}
mkdir -p schemas/database
```
### 2. Define your first collection schema
Create `schemas/database/users/schema.ts`:
```typescript theme={null}
import { z } from 'zod';
export const schema = z.object({
name: z.string().min(1, 'Name is required'),
email: z.string().email('Invalid email format'),
age: z.number().int().positive().optional(),
createdAt: z.date(),
metadata: z.object({
lastLogin: z.date().optional(),
isVerified: z.boolean().default(false),
preferences: z.record(z.string()).optional(),
}),
});
```
### 3. Generate type definitions
Use the Firetype CLI to generate your types:
```bash theme={null}
# Generate types for both admin and client SDKs (output written to input folder)
npx @anonymous-dev/firetype generate --input=./schemas/database
```
```bash theme={null}
# Generate only admin SDK types
npx @anonymous-dev/firetype generate --mode=admin --input=./schemas
```
```bash theme={null}
# Generate only client SDK types
npx @anonymous-dev/firetype generate --mode=client --input=./schemas
```
This creates an `index.ts` file in your input folder with your fully typed Firestore API.
### 4. Use in your application
#### Server-side (Admin SDK)
```typescript theme={null}
import { createFireTypeAdmin } from './types';
import { getFirestore } from 'firebase-admin/firestore';
const db = getFirestore();
const firetype = createFireTypeAdmin(db);
// Type-safe collection operations
const usersCollection = firetype.users.getCollectionRef();
const allUsers = await usersCollection.get();
// Type-safe document operations
const userDoc = firetype.users.getDocumentRef('user123');
const userSnapshot = await userDoc.get();
const userData = userSnapshot.data(); // Fully typed!
// Add new user with validation
await usersCollection.add({
name: 'John Doe',
email: 'john@example.com',
age: 30,
createdAt: new Date(),
metadata: {
isVerified: false,
preferences: { theme: 'dark' },
},
});
```
#### Client-side (Web SDK)
```typescript theme={null}
import { createFireTypeClient } from './types';
import { getFirestore, getDocs } from 'firebase/firestore';
const db = getFirestore();
const firetype = createFireTypeClient(db);
// Type-safe operations
const usersRef = firetype.users.getCollectionRef();
const usersSnapshot = await getDocs(usersRef);
usersSnapshot.forEach((doc) => {
const user = doc.data(); // Fully typed user object
console.log(`${user.name}: ${user.email}`);
});
```
### 5. Add subcollections (Optional)
Create nested collections by adding subdirectories. For user comments:
`schemas/database/users/comments/schema.ts`:
```typescript theme={null}
import { z } from 'zod';
export const schema = z.object({
content: z.string().min(1, 'Comment cannot be empty'),
authorId: z.string(),
createdAt: z.date(),
likes: z.number().default(0),
});
```
Now you can access nested collections:
```typescript theme={null}
// Get comments for a specific user
const userComments = firetype.users.comments.getCollectionRef({
usersId: 'user123',
});
const comments = await userComments.get();
```
## 📚 Documentation Sections
Learn how to define your Firestore schemas with Zod
Complete guide to the Firetype command-line interface
Detailed API documentation with examples
Real-world usage examples and patterns
## 🆘 Need Help?
Common issues and their solutions