Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TypedPocketBase
✓ import { TypedPocketBase } from './pocketbase-types'
✗ import TypedPocketBase from './pocketbase-types'
This is a named export from the generated type file, intended for type-asserting the PocketBase SDK instance.
Collections
✓ import { Collections } from './pocketbase-types'
✗ import Collections from './pocketbase-types'
A named export providing an enum or 'as const' object mapping collection names for type-safe string literals.
MyCollectionResponse
✓ import { MyCollectionResponse } from './pocketbase-types'
✗ import MyCollectionResponse from './pocketbase-types'
Individual collection response types are named exports. Replace 'MyCollection' with your actual collection name (e.g., `TasksResponse`).
Create, Update
✓ import { Create, Update } from './pocketbase-types'
✗ const Create = require('./pocketbase-types')
Utility types for creating and updating records within PocketBase, also named exports.
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.
import PocketBase from 'pocketbase';
import { TypedPocketBase } from './pocketbase-types';
import { Collections, Create, Update, TasksResponse, CommentsResponse, UsersResponse } from './pocketbase-types';
// First, generate your types. Run this command in your terminal:
// npx pocketbase-typegen --url https://myproject.pockethost.io --email admin@myproject.com --password 'secr3tp@ssword!'
const pb = new PocketBase('http://127.0.0.1:8090') as TypedPocketBase;
async function exampleUsage() {
// Fetch a single task with full type safety
const task = await pb.collection(Collections.Tasks).getOne('RECORD_ID');
console.log('Fetched task:', task.title);
// Example with expanded relations and JSON field types
type Metadata = { likes: number };
type Expand = { user: UsersResponse };
const commentResult = await pb.collection(Collections.Comments).getOne<CommentsResponse<Metadata, Expand>>('COMMENT_RECORD_ID', { expand: 'user' });
console.log('Comment metadata likes:', commentResult.metadata?.likes);
console.log('Comment user username:', commentResult.expand.user.username);
// Create a new user record
const newUser: Create<Collections.Users> = {
name: 'Jane Doe',
username: 'janedoe',
password: 'password123',
passwordConfirm: 'password123',
email: 'jane@example.com',
emailVisibility: true,
verified: false,
};
await pb.collection(Collections.Users).create(newUser);
console.log('User created successfully.');
// Update an existing user record
const updatedUser: Update<Collections.Users> = {
name: 'Jane Smith',
};
await pb.collection(Collections.Users).update('USER_RECORD_ID', updatedUser);
console.log('User updated successfully.');
}
exampleUsage().catch(console.error);
pocketbase-typegen --version
Errors
Common errors & fixes
TypeError: require is not a function
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.
fixEnsure 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.
TS2339: Property 'expand' does not exist on type '...' or Property 'user' does not exist on type '...'
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`.
fixEnsure 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. Error: Node.js v18.0.0 or higher is required.
You are attempting to run `pocketbase-typegen` with a Node.js version older than 18.
fixUpdate 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.
Error: Must specify --url, --db, or --json.
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).
fixProvide one of the required schema source options: `--url <your-pocketbase-url>`, `--db <path-to-db.db>`, or `--json <path-to-schema.json>`.
Audit
Dependencies
No dependency data recorded yet.