{"id":16490,"library":"pocketbase-typegen","title":"PocketBase Typegen","description":"PocketBase Typegen is a utility that generates TypeScript definitions directly from your PocketBase database schema. It supports various input sources including a live PocketBase instance URL, a local SQLite database file, or an exported JSON schema. The current stable version is `1.4.1`, with releases occurring regularly to maintain compatibility with new PocketBase versions and introduce new features. Key differentiators include the automatic generation of a `TypedPocketBase` type, which allows for fully type-safe usage of the PocketBase JavaScript SDK, as well as distinct types for individual collections, expand relations, and `Create`/`Update` operations, significantly enhancing developer experience and reducing runtime errors in TypeScript projects.","status":"active","version":"1.4.1","language":"javascript","source_language":"en","source_url":"git://github.com/patmood/pocketbase-typegen","tags":["javascript","pocketbase","typescript","typegen","type generation"],"install":[{"cmd":"npm install pocketbase-typegen","lang":"bash","label":"npm"},{"cmd":"yarn add pocketbase-typegen","lang":"bash","label":"yarn"},{"cmd":"pnpm add pocketbase-typegen","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a named export from the generated type file, intended for type-asserting the PocketBase SDK instance.","wrong":"import TypedPocketBase from './pocketbase-types'","symbol":"TypedPocketBase","correct":"import { TypedPocketBase } from './pocketbase-types'"},{"note":"A named export providing an enum or 'as const' object mapping collection names for type-safe string literals.","wrong":"import Collections from './pocketbase-types'","symbol":"Collections","correct":"import { Collections } from './pocketbase-types'"},{"note":"Individual collection response types are named exports. Replace 'MyCollection' with your actual collection name (e.g., `TasksResponse`).","wrong":"import MyCollectionResponse from './pocketbase-types'","symbol":"MyCollectionResponse","correct":"import { MyCollectionResponse } from './pocketbase-types'"},{"note":"Utility types for creating and updating records within PocketBase, also named exports.","wrong":"const Create = require('./pocketbase-types')","symbol":"Create, Update","correct":"import { Create, Update } from './pocketbase-types'"}],"quickstart":{"code":"import PocketBase from 'pocketbase';\nimport { TypedPocketBase } from './pocketbase-types';\nimport { Collections, Create, Update, TasksResponse, CommentsResponse, UsersResponse } from './pocketbase-types';\n\n// First, generate your types. Run this command in your terminal:\n// npx pocketbase-typegen --url https://myproject.pockethost.io --email admin@myproject.com --password 'secr3tp@ssword!'\n\nconst pb = new PocketBase('http://127.0.0.1:8090') as TypedPocketBase;\n\nasync function exampleUsage() {\n  // Fetch a single task with full type safety\n  const task = await pb.collection(Collections.Tasks).getOne('RECORD_ID');\n  console.log('Fetched task:', task.title);\n\n  // Example with expanded relations and JSON field types\n  type Metadata = { likes: number };\n  type Expand = { user: UsersResponse };\n  const commentResult = await pb.collection(Collections.Comments).getOne<CommentsResponse<Metadata, Expand>>('COMMENT_RECORD_ID', { expand: 'user' });\n  console.log('Comment metadata likes:', commentResult.metadata?.likes);\n  console.log('Comment user username:', commentResult.expand.user.username);\n\n  // Create a new user record\n  const newUser: Create<Collections.Users> = {\n    name: 'Jane Doe',\n    username: 'janedoe',\n    password: 'password123',\n    passwordConfirm: 'password123',\n    email: 'jane@example.com',\n    emailVisibility: true,\n    verified: false,\n  };\n  await pb.collection(Collections.Users).create(newUser);\n  console.log('User created successfully.');\n\n  // Update an existing user record\n  const updatedUser: Update<Collections.Users> = {\n    name: 'Jane Smith',\n  };\n  await pb.collection(Collections.Users).update('USER_RECORD_ID', updatedUser);\n  console.log('User updated successfully.');\n}\n\nexampleUsage().catch(console.error);","lang":"typescript","description":"Generates PocketBase TypeScript types from a remote instance and demonstrates fully type-safe interaction with the PocketBase SDK for fetching, creating, and updating records, including advanced use cases like expanded relations and custom JSON field types."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18 or newer.","message":"Version `1.4.1` and newer explicitly require Node.js v18 or higher. Running with older Node.js versions will result in execution errors.","severity":"breaking","affected_versions":">=1.4.1"},{"fix":"Review any code that explicitly relied on TypeScript `enum` behavior for generated types; adapt to `as const` object usage.","message":"Starting with version `1.4.0`, `pocketbase-typegen` now emits `as const` objects with a companion union type instead of TypeScript `enum`s. This change improves compatibility with `--erasableSyntaxOnly` and related TypeScript compiler options.","severity":"breaking","affected_versions":">=1.4.0"},{"fix":"Update your PocketBase backend instance to `v0.23.x` or newer to match the typegen tool's compatibility.","message":"Version `1.3.0` introduced breaking changes to support PocketBase `v0.23.x`. Ensure your PocketBase backend is updated to a compatible version if you are using `pocketbase-typegen v1.3.0` or newer.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Upgrade your PocketBase JS SDK to `v0.18.3+` or use the `--no-sdk` flag when generating types if an upgrade is not feasible.","message":"The `TypedPocketBase` type, which provides full SDK-wide type assertion, requires PocketBase JavaScript SDK `v0.18.3+`. If you are using an older SDK version with `pocketbase-typegen v1.2.0` or newer, you must pass the `--no-sdk` option during type generation to avoid compatibility issues.","severity":"gotcha","affected_versions":">=1.2.0"},{"fix":"Always include `--email` and `--password` (or `--token`) when using `--url` to authenticate with your PocketBase instance.","message":"When generating types from a remote PocketBase instance using the `--url` option, you must provide authentication credentials via `--email` and `--password`, or an `--token`. Failing to do so will prevent the tool from accessing your schema.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) or that you are importing the generated types using `import` statements in `.js` or `.ts` files.","cause":"Attempting to use `pocketbase-typegen` in a CommonJS (`require()`) environment when it is primarily an ESM package or your generated types are imported in an ESM context.","error":"TypeError: require is not a function"},{"fix":"Ensure you are passing the `Expand` generic to your response type (e.g., `CommentsResponse<Metadata, Expand>`) and that your PocketBase query includes the `{ expand: 'relationFieldName' }` option.","cause":"This typically occurs when trying to access an expanded relation (`result.expand.user`) without providing the correct `Expand` generic type to the response, or without actually requesting the expansion from PocketBase via the `{ expand: 'field' }` option in `getOne`/`getList`.","error":"TS2339: Property 'expand' does not exist on type '...' or Property 'user' does not exist on type '...'"},{"fix":"Update your Node.js installation to version 18 or newer. You can use a tool like `nvm` (Node Version Manager) to easily manage multiple Node.js versions.","cause":"You are attempting to run `pocketbase-typegen` with a Node.js version older than 18.","error":"Error: Node.js v18.0.0 or higher is required."},{"fix":"Provide one of the required schema source options: `--url <your-pocketbase-url>`, `--db <path-to-db.db>`, or `--json <path-to-schema.json>`.","cause":"The `pocketbase-typegen` CLI tool was invoked without specifying a source for the PocketBase schema (either a remote URL, local database file, or JSON schema export).","error":"Error: Must specify --url, --db, or --json."}],"ecosystem":"npm"}