Quickstart
Install Typesync CLI
First, ensure you have Node.js 18+ installed. Then, install the Typesync CLI using npm:
npm install -g typesync-cli
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!
# yaml-language-server: $schema=https://schema.typesync.org/v0.8.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
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
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 thedefinition
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;
}
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.