Home

Generating TypeScript Types

How to generate types for your API and Supabase libraries.

Supabase APIs are generated from your database, which means that we can use database introspection to generate type-safe API definitions.

Generating types using Supabase CLI#

The Supabase CLI is a single binary Go application that provides everything you need to setup a local development environment.

You can install the CLI via npm or other supported package managers. The minimum required version of the CLI is v1.8.1.


_10
npm i supabase@">=1.8.1" --save-dev

Login with your Personal Access Token:


_10
npx supabase login

Generate types for your project to produce the types/supabase.ts file:


_10
npx supabase gen types typescript --project-id "$PROJECT_REF" --schema public > types/supabase.ts

These types are generated from your database schema. Given a table public.movies, the generated types will look like:


_10
create table public.movies (
_10
id bigint generated always as identity primary key,
_10
name text not null,
_10
data jsonb null
_10
);

./database.types.ts

_28
export type Json = string | number | boolean | null | { [key: string]: Json | undefined } | Json[]
_28
_28
export interface Database {
_28
public: {
_28
Tables: {
_28
movies: {
_28
Row: {
_28
// the data expected from .select()
_28
id: number
_28
name: string
_28
data: Json | null
_28
}
_28
Insert: {
_28
// the data to be passed to .insert()
_28
id?: never // generated columns must not be supplied
_28
name: string // `not null` columns with no default must be supplied
_28
data?: Json | null // nullable columns can be omitted
_28
}
_28
Update: {
_28
// the data to be passed to .update()
_28
id?: never
_28
name?: string // `not null` columns are optional on .update()
_28
data?: Json | null
_28
}
_28
}
_28
}
_28
}
_28
}

Using TypeScript type definitions#

You can supply the type definitions to supabase-js like so:

./index.tsx

_10
import { createClient } from '@supabase/supabase-js'
_10
import { Database } from './database.types'
_10
_10
const supabase = createClient<Database>(process.env.SUPABASE_URL, process.env.SUPABASE_ANON_KEY)

Helper types for tables and joins#

You can use the following helper types to make the generated TypeScript types easier to use.

Sometimes the generated types are not what you expect. For example, a view's column may show up as nullable when you expect it to be not null. Using type-fest, you can override the types like so:

./database-generated.types.ts

_10
export type Json = // ...
_10
_10
export interface Database {
_10
// ...
_10
}

./database.types.ts

_20
import { MergeDeep } from 'type-fest'
_20
import { Database as DatabaseGenerated } from './database-generated.types'
_20
export { Json } from './database-generated.types'
_20
_20
// Override the type for a specific column in a view:
_20
export type Database = MergeDeep<
_20
DatabaseGenerated,
_20
{
_20
public: {
_20
Views: {
_20
movies_view: {
_20
Row: {
_20
// id is a primary key in public.movies, so it must be `not null`
_20
id: number
_20
}
_20
}
_20
}
_20
}
_20
}
_20
>

You can also override the type of an individual successful response if needed:


_10
const { data } = await supabase.from('countries').select().returns<MyType>()

Type shorthands#

The generated types provide shorthands for accessing tables and enums.

./index.ts

_10
import { Database, Tables, Enums } from "./database.types.ts";
_10
_10
// Before 😕
_10
let movie: Database['public']['Tables']['movies']['Row'] = // ...
_10
_10
// After 😍
_10
let movie: Tables<'movies'>

Response types for complex queries#

supabase-js always returns a data object (for success), and an error object (for unsuccessful requests).

These helper types provide the result types from any query, including nested types for database joins.

Given the following schema with a relation between cities and countries:


_10
create table countries (
_10
"id" serial primary key,
_10
"name" text
_10
);
_10
_10
create table cities (
_10
"id" serial primary key,
_10
"name" text,
_10
"country_id" int references "countries"
_10
);

We can get the nested CountriesWithCities type like this:


_15
import { QueryResult, QueryData, QueryError } from '@supabase/supabase-js'
_15
_15
const countriesWithCitiesQuery = supabase.from('countries').select(`
_15
id,
_15
name,
_15
cities (
_15
id,
_15
name
_15
)
_15
`)
_15
type CountriesWithCities = QueryData<typeof countriesWithCitiesQuery>
_15
_15
const { data, error } = await countriesWithCitiesQuery
_15
if (error) throw error
_15
const countriesWithCities: CountriesWithCities = data

Update types automatically with GitHub Actions#

One way to keep your type definitions in sync with your database is to set up a GitHub action that runs on a schedule.

Add the script above to your package.json to run it using npm run update-types


_10
"update-types": "npx supabase gen types typescript --project-id \"$PROJECT_REF\" > types/supabase.ts"

Create a file .github/workflows/update-types.yml with the following snippet to define the action along with the environment variables. This script will commit new type changes to your repo every night.


_39
name: Update database types
_39
_39
on:
_39
schedule:
_39
# sets the action to run daily. You can modify this to run the action more or less frequently
_39
- cron: '0 0 * * *'
_39
_39
jobs:
_39
update:
_39
runs-on: ubuntu-latest
_39
env:
_39
SUPABASE_ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
_39
PROJECT_REF: <your-project-id>
_39
steps:
_39
- uses: actions/checkout@v2
_39
with:
_39
persist-credentials: false
_39
fetch-depth: 0
_39
- uses: actions/setup-node@v2.1.5
_39
with:
_39
node-version: 16
_39
- run: npm run update-types
_39
- name: check for file changes
_39
id: git_status
_39
run: |
_39
echo "status=$(git status -s)" >> $GITHUB_OUTPUT
_39
- name: Commit files
_39
if: ${{contains(steps.git_status.outputs.status, ' ')}}
_39
run: |
_39
git add types/database/index.ts
_39
git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
_39
git config --local user.name "github-actions[bot]"
_39
git commit -m "Update database types" -a
_39
- name: Push changes
_39
if: ${{contains(steps.git_status.outputs.status, ' ')}}
_39
uses: ad-m/github-push-action@master
_39
with:
_39
github_token: ${{ secrets.GITHUB_TOKEN }}
_39
branch: ${{ github.ref }}

Alternatively, you can use a community-supported GitHub action: generate-supabase-db-types-github-action.

Resources#

© Supabase Inc—ContributingAuthor StyleguideOpen SourceSupaSquad