Pocketbase Typegen

Generate typescript definitions from your pocketbase.io schema.

Quickstart

npx pocketbase-typegen --url https://myproject.pockethost.io --email [email protected] --password 'secr3tp@ssword!'

This will produce types for all your PocketBase collections to use in your frontend typescript codebase.

Version Support

| PocketBase | pocketbase-typegen | npx command | | ---------- | ------------------ | ------------------------------------------------------------------------------ | | v0.23.x | v1.3.x | npx pocketbase-typegen --db ./pb_data/data.db --out pocketbase-types.ts | | v0.18.x | v1.2.x | npx [email protected] --db ./pb_data/data.db --out pocketbase-types.ts | | v0.8.x | v1.1.x | npx [email protected] --db ./pb_data/data.db --out pocketbase-types.ts | | v0.7.x | v1.0.x | npx [email protected] --db ./pb_data/data.db --out pocketbase-types.ts |

Usage

Options:
  -V, --version              output the version number
  -u, --url <url>            URL to your hosted pocketbase instance. When using this options you must also provide email and
                             password options or auth token option.
  --email <email>            Email for a pocketbase superuser. Use this with the --url option.
  -p, --password <password>  Password for a pocketbase superuser. Use this with the --url option.
  -t, --token <token>        Auth token for a pocketbase superuser. Use this with the --url option.
  -d, --db <path>            Path to the pocketbase SQLite database.
  -j, --json <path>          Path to JSON schema exported from pocketbase admin UI.
  --env [dir]                Use environment variables for configuration. Add PB_TYPEGEN_URL, PB_TYPEGEN_EMAIL, PB_TYPEGEN_PASSWORD
                             to your .env file. Optionally provide a path to a directory containing a .env file (default: true)
  -o, --out <path>           Path to save the typescript output file. (default: "pocketbase-types.ts")
  --no-sdk                   Removes the pocketbase package dependency. A typed version of the SDK will not be generated.
  -h, --help                 display help for command

URL example with email and password:

npx pocketbase-typegen --url https://myproject.pockethost.io --email [email protected] --password 'secr3tp@ssword!'

URL example with auth token:

You can generate such token via the above impersonate API or from the Dashboard > Collections > _superusers > {select superuser} > "Impersonate" dropdown option.

npx pocketbase-typegen --url https://myproject.pockethost.io --token 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

ENV example:

Also supports environment specific files such as .env.local (uses dotenv-flow)

npx pocketbase-typegen --env or npx pocketbase-typegen --env path/to/dir

.env variables include:

PB_TYPEGEN_URL=https://myproject.pockethost.io
[email protected]
PB_TYPEGEN_PASSWORD=secr3tp@ssword!
PB_TYPEGEN_TOKEN=eyJhbGciOiJI...ozhyQVfYm24

Database example:

npx pocketbase-typegen --db ./pb_data/data.db

JSON example (export JSON schema from the pocketbase admin dashboard):

npx pocketbase-typegen --json ./pb_schema.json

Shortcut

Add it to your projects package.json:

"scripts": {
  "typegen": "pocketbase-typegen --env",
},

Example Output

The output is a typescript file pocketbase-types.ts (example) which will contain:

• Collections An enum of all collections.
• [CollectionName]Record One type for each collection (eg ProfilesRecord).
• [CollectionName]Response One response type for each collection (eg ProfilesResponse) which includes system fields. This is what is returned from the PocketBase API.
  • [CollectionName][FieldName]Options If the collection contains a select field with set values, an enum of the options will be generated.
• CollectionRecords A type mapping each collection name to the record type.
• CollectionResponses A type mapping each collection name to the response type.
• TypedPocketBase A type for usage with type asserted PocketBase instance.

Example Usage

Using PocketBase SDK v0.18.3+, collections can be automatically typed using the generated TypedPocketBase type:

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

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

await pb.collection("tasks").getOne("RECORD_ID") // -> results in TaskResponse
await pb.collection("posts").getOne("RECORD_ID") // -> results in PostResponse

Alternatively, you can use generic types for each request, eg:

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

await pb.collection(Collections.Tasks).getOne<TasksResponse>("RECORD_ID") // -> results in TaskResponse

Example Advanced Usage

You can provide types for JSON fields and expanded relations by passing generic arguments to the Response types:

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

/**
  type CommentsRecord<Tmetadata = unknown> = {
    text: string
    metadata: null | Tmetadata // This is a json field
    user: RecordIdString // This is a relation field
  }
*/
type Metadata = {
  likes: number
}
type Expand = {
  user: UsersResponse
}
const result = await pb
  .collection(Collections.Comments)
  .getOne<CommentsResponse<Metadata, Expand>>("RECORD_ID", { expand: "user" })

// Now you can access the expanded relation with type safety and hints in your IDE
result.expand.user.username

Create/Update types

You can also type the create/update operations in two ways.

1. Using collection model directly (you need to know if your collection is base/auth, but you can use your own custom models):

import { Collections, CreateAuth, CreateBase, PostsRecord, UpdateAuth, UpdateBase, UsersRecord } from "./pocketbase-types"

// For base collections
const newPost: CreateBase<PostsRecord> = {
  title: 'Post title',
  description: 'Post description',
  creator: 'USER_ID',
  active: true
}
await pb.collection(Collections.Posts).create(newPost)

const updatedPost: UpdateBase<PostsRecord> = {
  title: 'New post title',
  description: 'Updated post description',
  active: false
}
await pb.collection(Collections.Posts).update('RECORD_ID', updatedPost)

// For auth collections
const newUser: CreateAuth<UsersRecord> = {
  name: 'Name',
  username: 'username',
  password: 'password',
  passwordConfirm: 'password',
  email: '[email protected]',
  emailVisibility: true,
  verified: false
}
await pb.collection(Collections.Users).create(newUser)

const updatedUser: UpdateAuth<UsersRecord> = {
  name: 'Name',
  email: '[email protected]',
  verified: false
}
await pb.collection(Collections.Users).update('RECORD_ID', updatedUser)

2. Using Collections enum (type auto-infer if collection is base/auth):

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

// Create
const newUser: Create<Collections.Users> = {
  name: 'Name',
  username: 'username',
  password: 'password',
  passwordConfirm: 'password',
  email: '[email protected]',
  emailVisibility: true,
  verified: false
}
await pb.collection(Collections.Users).create(newUser)

// Update
const updatedUser: Update<Collections.Users> = {
  name: 'Updated name',
  email: '[email protected]',
  verified: false
}
await pb.collection(Collections.Users).update('RECORD_ID', updatedUser)

Status