npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@supabase/typegen

v0.4.0

Published

Language registry for supabase gen types: maps each --lang to its generator

Readme

@supabase/typegen

The language registry behind supabase gen types --lang <language>. It maps each language name to the generator that renders PostgREST types for it, so that adding a language is a pull request in this repository plus a dependency bump in the Supabase CLI, with no per-language code in the CLI itself.

Status: alpha. The Host, TypegenLanguage, option and error types are the contract with the CLI and follow semver from 1.0.0 on; before that, minor versions may change them.

Where it sits

Supabase CLI          connects to the database, introspects it with the
                      introspect() re-exported here, looks --lang up here
      |
@supabase/typegen     this package: language name to generator
      |
      +-- in-process entry      imports a generator function and calls it
      |                         with the GeneratorMetadata object
      |
      +-- out-of-process entry  runs the language's own tool in the user's
                                project with the GeneratorMetadata JSON
                                document on stdin, reads the code from stdout

Introspection is not part of this package's logic. The consumer runs introspect() and hands the resulting GeneratorMetadata to the language it looked up here. introspect, Queryable, IntrospectOptions, GeneratorMetadata and GENERATOR_METADATA_VERSION are re-exported from @supabase/postgrest-typegen, so a consumer depends on this package alone: one dependency to bump, and the document is always produced by the same postgrest-typegen version the in-process generators were built against. That is why the dependency is pinned to an exact version rather than a range. As soon as each release is on npm, the Release postgrest-typegen workflow opens a typegen release pull request that bumps the pin. Depending on both packages directly would let a lockfile resolve two versions, introspecting with one and generating with the other.

The two kinds of generator relate to postgrest-typegen differently:

  • In-process generators import its types, so they depend on it. Today those are the three bundled inside postgrest-typegen; permanently it will be the TypeScript generator once it lives in supabase-js and is published to npm.
  • Out-of-process generators depend on nothing here. They read the JSON document, whose shape is published as generatorMetadataJsonSchema and versioned by GENERATOR_METADATA_VERSION, and can be written in any language. supabase_typegen for Dart was the first; supabase-typegen for Swift is the second.

This is why the registry is its own package rather than part of postgrest-typegen: once the TypeScript generator is imported from supabase-js, which itself imports postgrest-typegen's types, a registry inside postgrest-typegen would close a dependency cycle. A registry above both does not.

Languages

| --lang | Runs | How | Flags | | ------------ | -------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- | | typescript | in-process | generateTypescript from @supabase/postgrest-typegen | consumer: detect-one-to-one-relationships, postgrest-version, default-schema | | go | in-process | generateGo from @supabase/postgrest-typegen | | | python | in-process | generatePython from @supabase/postgrest-typegen | | | swift | out-of-process | supabase-typegen --access-control <level>, built | --swift-access-control internal\|public, --swift-typegen-source <source> | | dart | out-of-process | dart run supabase_typegen --output - in the project | |

The three in-process entries are a transition: as each generator relocates to its SDK repository (SDK-1641), its entry here changes to an out-of-process command, or for TypeScript to an import of the new npm package, and consumers notice nothing but a dependency bump.

Swift moved first. supabase-typegen is an executable in supabase-swift's tools/supabase-typegen, not a package dependency: as a SwiftPM product its swift-format dependency would pin every app's swift-syntax, and an Xcode project without a Package.swift has nothing to swift run from.

The output targets one commit's @Table macro, so the generator must match the project's supabase-swift. The entry builds it from source at a supabase-swift commit, which it picks in this order:

  1. --swift-typegen-source, when given. The value is read in a fixed order, without guessing:

    • A value that starts with ./, ../, / or ~/ is a local checkout. Relative paths must start with ./ or ../, so a folder named 3.0.0 is never read as a version, and ~ means the home folder. The entry checks that the checkout has tools/supabase-typegen, runs swift build -c release --package-path <checkout>/tools/supabase-typegen in the checkout's own .build folder, so later builds are incremental, and runs the binary from there. It never caches it, since the working tree can hold uncommitted changes. This is the form for working on the generator, or for a fork.
    • 40 hex characters are a commit SHA. An abbreviated SHA is refused.
    • A semantic version, with or without a leading v, is the commit its tag v<version> (or <version>) points at, per git ls-remote; an annotated tag's commit wins. A version below 3 is refused, since supabase-swift 2.x has no generator.
    • Anything else is a branch, resolved to its commit with git ls-remote on every run, so new commits are picked up. A branch name that starts with - or holds whitespace, .., control characters or anything else git could read as an option or a refspec is refused before git runs.

    A lookup that finds nothing names what it looked for, and for a branch name that is also a folder in cwd, the ./ form to build it.

  2. The supabase-swift pin of the nearest Package.resolved that has one: in cwd or a parent, SwiftPM's or Xcode's inside the .xcodeproj or .xcworkspace. Lockfiles without a supabase-swift pin are skipped. For a monorepo run from its root, when no parent has a pin, the entry also looks up to two levels below cwd, skipping .git, .build, node_modules, Pods and DerivedData; the pins found there must agree on the revision, or the run fails and asks for --swift-typegen-source. The pin's revision is built, so version, branch and revision pins all work.

  3. The latest supabase-swift 3.x release from git ls-remote --tags: the highest stable 3.x once there is one, the highest 3.x prerelease before that (with semantic version precedence, so alpha.10 follows alpha.9), and never another major version. A notice on stderr says so and asks to run from the app's directory, or to pass --swift-typegen-source, to match the pinned version.

Every run prints the commit it uses to stderr, for example Using branch `main` at `4f2a9c1…`.. Except for a local checkout, the build then goes:

  1. Only a 40-character lowercase hex SHA reaches git as a revision, a version must be a semantic version and a branch a plain branch name. Only regular files the user owns count as Package.resolved, so another user's file in a shared parent such as /tmp cannot pick the commit, and a malformed one counts as no pin.
  2. A binary already in $XDG_CACHE_HOME/supabase/typegen/<revision>/ (default ~/Library/Caches on macOS, ~/.cache elsewhere; an empty or relative XDG_CACHE_HOME is ignored) runs with no build.
  3. Otherwise it checks that git and swift (Swift 6.2 / Xcode 26 or newer) are on PATH and, for a commit that did not come from upstream's own tags or branches, that it is upstream's. GitHub serves every commit of the fork network through the upstream URL, pull request heads included, so a version pin's tag (<version> or v<version>, per git ls-remote) must point at the revision, and a branch pin's revision must be an ancestor of that upstream branch (a bare revision pin, or a SHA passed to --swift-typegen-source: the default branch), checked in a commits-only clone (--filter=tree:0, about 1.5 MB and a second). It then fetches the single commit into a temporary folder, checks that HEAD is the revision, and runs swift build -c release --package-path tools/supabase-typegen --disable-automatic-resolution. The flag builds the generator's committed Package.resolved exactly and fails rather than resolve other dependency versions. Linux adds --static-swift-stdlib, so the cached binary keeps working after the toolchain that built it is removed or upgraded. Git's repository variables (GIT_DIR, GIT_INDEX_FILE and the rest of git rev-parse --local-env-vars) are removed from these steps, so running inside a git hook cannot touch the user's repository.
  4. For a version, from the pin, the flag or the latest release, supabase-typegen --version must print that version.
  5. The binary is copied beside its cache path and renamed into place, so concurrent runs are safe. The temporary folder is removed in every case.

The first build prints a line to stderr and takes a few minutes, mostly compiling swift-syntax: about 5.5 minutes on an Apple M3 with Swift 6.4, and about the same on Linux aarch64 with Swift 6.2 in Docker on that machine. A pinned build trusts nothing the app does not already run: the supabase-swift source at the pinned commit, the generator's pinned dependencies and the user's toolchain. A version or the latest release trusts the tag at the time of the run, and a branch anyone who can push to it, which is why a branch is never a default. supabase-swift 2.x has no tools/supabase-typegen and fails with a request to update to 3.0.0-alpha.1 or newer. The entry never runs a supabase-typegen from PATH, and SUPABASE_TYPEGEN is gone: a stale binary could generate code for the wrong version without a warning, and a local checkout covers the development loop. Windows is not supported.

--swift-access-control lost private and package, which the new generator does not accept.

Using the registry

import {
  createNodeHost,
  findLanguage,
  introspect,
  TypegenError,
} from "@supabase/typegen";

const language = findLanguage(lang);
if (!language) {
  throw new Error(`unknown language ${lang}`);
}

const metadata = await introspect(pool, { includedSchemas: ["public"] });
const host = createNodeHost({ cwd: process.cwd() });
const code = await language.generate(metadata, { "swift-access-control": "public" }, host);
process.stdout.write(code);

languages is the full list in display order, and each entry's options describes its flags declaratively (name, audience, kind, default, help, choices), so a consumer can render every language's flags without knowing the languages. Option names are the flag names without dashes and are also the keys of the values passed to generate. Missing values take the defaults; unknown names and values outside a choice raise an InvalidOptionError.

audience says who sets an option. user options are the CLI flags; render options.filter((option) => option.audience === "user"). consumer options are set by the calling program from what it knows about the target and never shown to users. TypeScript has three: detect-one-to-one-relationships (default on; the consumer turns it off for PostgREST 9 and below, where one-to-one joins come back as arrays), postgrest-version (emitted as __InternalSupabase.PostgrestVersion) and default-schema (default public). postgres-meta's hosted route sets them from its detect_one_to_one_relationships query parameter, POSTGREST_VERSION and GENERATE_TYPES_DEFAULT_SCHEMA. The Supabase CLI already sniffs the local stack's PostgREST version and used to expose the first one inverted as --postgrest-v9-compat, usable only with --db-url; its adapter keeps that flag as a deprecated alias that sets the option to false.

generate sorts the metadata with sortGeneratorMetadata itself, so callers may pass introspect()'s output directly. It returns the complete contents of the generated file for every language, so the consumer writes the result as-is with no per-language handling. The in-process entries return the generator's output verbatim: every bundled generator ends its file with a single newline, and the registry adds one only when a Host.format implementation dropped it. For Dart it is the tool's stdout verbatim, which is what makes supabase gen types --lang dart match dart run supabase_typegen byte for byte.

Hosted consumers that cannot spawn processes, such as postgres-meta's /generators/* routes, filter on language.inProcess.

The Host

A Host is what the consumer knows and the registry does not:

  • cwd: the user's project directory. Out-of-process tools run there so they pick up the project's own toolchain and dependencies.
  • env: environment for spawned tools, usually process.env.
  • signal: optional AbortSignal; aborting cancels the generation and kills a spawned tool.
  • spawn(request): optional. Runs a command to completion and resolves with its exit code, stdout and stderr. It must reject with an error whose code is "ENOENT" when the executable is not found, as Node's child_process does. A host that cannot run processes leaves it out; an out-of-process language then fails with SpawnUnavailableError, so hosted consumers offer only inProcess languages.
  • format(code, fileName): optional. Replaces the formatter of in-process generators that format their own output. Only TypeScript does today, through oxfmt, with the file name output.ts. The CLI passes an identity function so its output stays byte-identical to what it emits today and oxfmt stays out of its bundle. Leave it out to get each generator's default, which for TypeScript needs oxfmt installed: it is an optional peer dependency, loaded only when the default formatter runs, so hosts that always pass format never need it.

createNodeHost({ cwd, env, signal, format }) is a ready-made Host on node:child_process for consumers without their own process runner. On Windows it resolves the command through PATH and PATHEXT and runs .bat and .cmd scripts through the command interpreter, since Flutter ships dart as dart.bat there and spawn cannot start those directly; a command it cannot find is reported as ENOENT like everywhere else. A host built on another process runner needs the same treatment; planSpawn is exported so it starts the same cmd.exe line, and the pieces it is built from (resolveWindowsCommand, isWindowsScript, quoteForCmd) are exported for a host that has to assemble the line itself. A token holding a double quote or a line break is refused, since cmd.exe toggles quoting on every " and nothing can escape it; a path holding % cannot be passed reliably either, since %VAR% expands even inside quotes.

Errors

Every failure the registry raises extends TypegenError and carries the language, so a consumer maps them to its own error model once:

  • InvalidOptionError (option): a value the language's option spec rejects.
  • SpawnUnavailableError (tool): an out-of-process language was asked to generate through a host without spawn.
  • ToolNotInstalledError (tool, installHint): the executable or package an out-of-process generator needs is missing in cwd. For Dart that is either the Dart SDK or the supabase_typegen dev dependency of the project.
  • ToolFailedError (command, exitCode, stderr): the tool exited unsuccessfully; the message includes its stderr.
  • MetadataRejectedError (extends ToolFailedError, adds version): the tool refused the GeneratorMetadata document, usually because it does not understand this GENERATOR_METADATA_VERSION. The fix is updating the tool or the CLI so both agree.

Anything a generator throws itself, or a spawn rejection other than a missing executable, passes through unchanged.

Adding a language

Add an entry to src/languages/ and list it in languages. Two shapes exist:

In-process (inProcessLanguage): wraps a generator function called in this process. Every dependency of that generator lands in the CLI bundle, so this is reserved for the transitional entries and, permanently, for TypeScript imported from supabase-js.

Out-of-process (externalLanguage): describes a command line. The registry runs it in the host's cwd with the sorted document from serializeGeneratorMetadata on stdin and returns its stdout as the generated code. The tool's contract:

  • Read the JSON document from stdin; its version is GENERATOR_METADATA_VERSION and its schema is generatorMetadataJsonSchema, both from @supabase/postgrest-typegen.
  • Write only the generated code to stdout; diagnostics and summaries go to stderr.
  • Exit 0 on success. The entry's classify maps the tool's other exits to the typed failures, for example Dart's exit 65 (data error) to MetadataRejectedError and its "could not find package" stderr to ToolNotInstalledError with a dart pub add hint.

Language flags are declared as OptionSpecs on the entry and reach generate as validated values. Keep names identical to the flags users already know, and mark settings that only a calling program supplies as audience: "consumer".

Testing splits by ownership: this package unit-tests each entry against a fake host (arguments, working directory, stdin document, error classification), the CLI keeps its end-to-end matrix for in-process languages plus a fake external tool for the handoff, and each SDK repository owns the end-to-end test of its tool against the CLI (supabase gen types --lang dart --local must produce the same file as dart run supabase_typegen --local).

Development

bun install
bun run test                 # bun:test, no Docker needed
bun run check-types          # tsc --noEmit
bun run check-types:consumer # type-check the way the CLI does, through @tsconfig/bun
bun run format-and-lint      # oxfmt + oxlint check
bun run knip                 # unused code and dependencies
bun run build                # emits dist/

Releases

Released with release-please as its own component, tagged typegen/vX.Y.Z, and published to npm as @supabase/typegen through OIDC trusted publishing. A change to the --lang list or to the Host, option or error types is a change to the CLI's public surface: describe it in the pull request so it reaches the release notes the CLI reads before bumping.