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.