pocketbase-typegen

The generated pocketbase-types.ts file contains several key entities:

• Collections: A constant object mapping PascalCase names to collection IDs, with a companion union type.
• [CollectionName]Record: A type for each collection (e.g., ProfilesRecord).
• [CollectionName]Response: A response type for each collection (e.g., ProfilesResponse) including system fields.
• [CollectionName][FieldName]Options: If a collection has a select field, a const object and union type of the options are generated.
• CollectionRecords: A type mapping each collection name to its record type.
• CollectionResponses: A type mapping each collection name to its response type.
• TypedPocketBase: A type for use with a type-asserted PocketBase instance.

Use npx pocketbase-typegen to generate TypeScript definitions from your PocketBase schema. By providing a URL and superuser credentials (email/password or token), the tool will produce a pocketbase-types.ts file containing types for all your collections.

npx pocketbase-typegen --url https://myproject.pockethost.io --email admin@myproject.com --password 'secr3tp@ssword!'

You can trigger type generation using several different input methods:

• Auth Token: Use --token <token> (obtain via PocketBase Dashboard > Collections > _superusers > Impersonate).
• Environment Variables: Use --env to load PB_TYPEGEN_URL, PB_TYPEGEN_EMAIL, PB_TYPEGEN_PASSWORD, or PB_TYPEGEN_TOKEN from a .env file.
• Local SQLite DB: Use --db <path> to point directly to your data.db file.
• JSON Schema: Use --json <path> to point to a JSON schema exported from the PocketBase admin UI.

# Auth Token example
npx pocketbase-typegen --url https://myproject.pockethost.io --token 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

# Database example
npx pocketbase-typegen --db ./pb_data/data.db

# JSON example
npx pocketbase-typegen --json ./pb_schema.json

You can automate type generation so that it runs every time a collection is created, updated, or deleted. Create a generateHooks.pb.js file in your pb_hooks directory.

/// <reference path="../pb_data/types.d.ts" />

const generateTypes = (e) => {
  console.log("Collection changed - Running type generation...")
  const cmd = $os.cmd(
    "npx",
    "pocketbase-typegen",
    "--db",
    "pb_data/data.db",
    "--out",
    "../client/src/pocketbase-types.ts"
  )
  const result = toString(cmd.output())
  console.log(result)

  e.next()
}

onCollectionAfterCreateSuccess(generateTypes)
onCollectionAfterUpdateSuccess(generateTypes)
onCollectionAfterDeleteSuccess(generateTypes)

For advanced scenarios, you can pass generic arguments to your Response types to provide type safety for JSON fields and expanded relations (using PocketBase's expand feature).

import { Collections, CommentsResponse, UsersResponse } from "./pocketbase-types"

type Metadata = {
  likes: number
}
type Expand = {
  user: UsersResponse
}

const result = await pb
  .collection(Collections.Comments)
  .getOne<CommentsResponse<Metadata, Expand>>("RECORD_ID", { expand: "user" })

// Access expanded relation with type safety
result.expand.user.username

Instead of manually typing every request, you can cast your PocketBase instance to TypedPocketBase. This enables automatic type inference for all collection operations based on the generated types.

import { TypedPocketBase } from "./pocketbase-types"

const pb = new PocketBase("http://127.0.0.1:8090") as TypedPocketBase

// Results in inferred response types (e.g., TaskResponse, PostResponse)
await pb.collection("tasks").getOne("RECORD_ID")
await pb.collection("posts").getOne("RECORD_ID")

If you prefer not to use TypedPocketBase, you can use the generated Collections enum and specific response types manually in your calls.

import { Collections, TasksResponse } from "./pocketbase-types"

await pb.collection(Collections.Tasks).getOne<TasksResponse>("RECORD_ID")

The generated types include Create<T> and Update<T> helpers to ensure your payload matches the collection schema during write operations.

import { Collections, Create, Update } from "./pocketbase-types"

// Create
const newUser: Create<Collections.Users> = {
  name: "Name",
  username: "username",
  password: "password",
  passwordConfirm: "password",
  email: "user@mail.com",
  emailVisibility: true,
  verified: false,
}
await pb.collection(Collections.Users).create(newUser)

// Update
const updatedUser: Update<Collections.Users> = {
  name: "Updated name",
  email: "user@email.com",
  verified: false,
}
await pb.collection(Collections.Users).update("RECORD_ID", updatedUser)

You can import generateFromSchema to use the tool as a library within Vite plugins, build hooks, or custom scripts.

import { generateFromSchema } from "pocketbase-typegen"

// Load your schema however you like — from a JSON file, API, etc.
const collections = JSON.parse(await fs.readFile("./pb_schema.json", "utf8"))
const typeDefinitions = generateFromSchema(collections)

// Optional: omit TypedPocketBase type
// generateFromSchema(collections, { sdk: false })

If you use the --env flag (or if it is enabled by default), the CLI will look for the following environment variables to resolve the schema source. You can optionally provide a path to a directory containing a .env file using --env <dir>.

Required variables:

• PB_TYPEGEN_URL: The URL of your PocketBase instance.

Authentication variables (choose one):

• PB_TYPEGEN_TOKEN: An auth token for a superuser.
• PB_TYPEGEN_EMAIL and PB_TYPEGEN_PASSWORD: Superuser credentials.

# Example: Using a .env file in a specific directory
pocketbase-typegen --env ./config