Skip to main content
1

Install Typesync CLI

First, ensure you have Node.js 18+ installed. Then, install the Typesync CLI using npm:
npm install -g typesync-cli
2

Create your schema

Create a directory within your project to store your Typesync definition files. A common practice is to name this directory definition.
mkdir definition
cd definition
Next, create a YAML file named models.yml in the definition directory. This file will contain the schema definitions for your Firestore documents. Here’s a sample schema:
You can also define your models in JSON files. Typesync accepts YAML, JSON or even a combination of both!
models.yml
# yaml-language-server: $schema=https://schema.typesync.org/v0.13.json

UserRole:
  model: alias
  docs: Represents a user's role within a project.
  type:
    type: enum
    members:
      - label: Owner
        value: owner
      - label: Admin
        value: admin
      - label: Member
        value: member

User:
  model: document
  path: users/{userId}
  docs: Represents a user that belongs to a project.
  type:
    type: object
    fields:
      username:
        type: string
        docs: A string that uniquely identifies the user within a project.
      role:
        type: UserRole
      website_url:
        type: string
        optional: true
      created_at:
        type: timestamp
3

Generate type definitions

You can now generate the types for the relevant environment. For example, if your project is a Node.js backend that uses Firebase Admin SDK (version 11), run the following command:
typesync generate-ts --definition 'definition/**/*.yml' --target firebase-admin@11 --outFile models.ts
This command tells Typesync to:
  • take all .yml files in the definition directory as the schema definition
  • generate TypeScript interfaces for use with the Firebase Admin SDK (version 11)
  • write the generated types to the models.ts file in the current directory
Here’s what the generated TypeScript file might look like:
models.ts (backend)
import type { firestore } from 'firebase-admin';

/** Represents a user's role within a project. */
export type UserRole = 'owner' | 'admin' | 'member';

/** Represents a user that belongs to a project. */
export interface User {
  /** A string that uniquely identifies the user within a project. */
  username: string;
  role: UserRole;
  website_url?: string;
  created_at: firestore.Timestamp;
}
4

Integrate into your development workflow

You should regenerate your types anytime the schema changes. To streamline development, consider integrating the Typesync generation command into your build process or CI/CD pipeline.

​
Version Control

Decide if you want to version control the generated files. It can be beneficial for ensuring consistency across environments but may require additional maintenance.

​
Multiple Files

As your project grows, you might want to split your schema into multiple YAML/JSON files. Typesync will automatically handle all files matching the pattern that you provide to it through the --definition option.