Quickstart

First, ensure you have Node.js 18+ installed. Then, install the Typesync CLI using npm:

npm install -g typesync-cli

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:

# 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

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:

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;
}

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.