supabase-types-watch

Auto-regenerate Supabase TypeScript types whenever a migration changes — no more manual supabase gen types runs.

The Problem

Every time you write a new Supabase migration during local development, the TypeScript types in your project go stale. The official Supabase documentation recommends running supabase gen types typescript --local manually or setting up a nightly GitHub Action — but neither solution gives you instant feedback while actively developing migrations.

supabase-types-watch fills that gap: it watches your supabase/migrations/ directory and re-runs type generation automatically whenever a .sql file is added or changed.

Installation

npm install -D supabase-types-watch

Quick Start

Add it as a dev script alongside your framework's dev server:

{
  "scripts": {
    "dev": "concurrently \"next dev\" \"supabase-types-watch\""
  }
}

Install concurrently if you don't have it:

npm install -D concurrently

Usage with concurrently

# Next.js
"dev": "concurrently \"next dev\" \"supabase-types-watch\""

# Vite
"dev": "concurrently \"vite\" \"supabase-types-watch\""

# Remix
"dev": "concurrently \"remix dev\" \"supabase-types-watch\""

On startup, supabase-types-watch runs type generation once immediately, then enters watch mode and regenerates types on every migration change.

Configuration

All options can be set via CLI flags, a "supabase-types-watch" key in package.json, or a [typescript] section in supabase/config.toml. CLI flags take highest priority.

| Option | Default | Description | |---|---|---| | migrationsDir | supabase/migrations | Directory to watch for .sql files | | output | src/types/database.types.ts | Output path for generated TypeScript types | | debounceMs | 500 | Milliseconds to wait after a change before regenerating (prevents duplicate runs on bulk file operations) | | verbose | false | Print extra diagnostic output | | command | npx supabase gen types typescript --local | Shell command used to generate types |

package.json config block

{
  "supabase-types-watch": {
    "migrationsDir": "supabase/migrations",
    "output": "src/types/database.types.ts",
    "debounceMs": 500,
    "verbose": false
  }
}

CLI options

Options:
  --migrations-dir <path>   Override migrations directory
  --output <path>           Override output file path
  --debounce <ms>           Override debounce delay
  --verbose                 Enable verbose logging
  --command <cmd>           Override the gen types command
  -V, --version             Output the version number
  -h, --help                Display help

One-Time Run Mode

Run type generation once and exit (useful in CI or pre-commit hooks):

npx supabase-types-watch run

CI Usage

Add a one-time type generation step before your type-check step:

- name: Generate Supabase types
  run: npx supabase-types-watch run

- name: Type check
  run: tsc --noEmit

This ensures CI always uses fresh types without committing generated files.

How It Works

1. Watch — chokidar watches supabase/migrations/**/*.sql for add and change events.
2. Debounce — Multiple file events within debounceMs are collapsed into a single trigger to avoid redundant runs during migrations that write several files at once.
3. Generate — Node's child_process.spawn (via cross-spawn for Windows compatibility) runs the configured command and streams output directly to your terminal.
4. Resilient — A failed generation (non-zero exit code or missing CLI) is logged but does not kill the watcher. You can fix the migration and the next save will retry automatically.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes with tests
4. Run npm test && npm run lint to verify
5. Open a pull request

All contributions welcome!

License

MIT