pocketbase-schema

Type-safe PocketBase development — automatically.

pocketbase-schema is a utility that generates TypeScript types directly from your PocketBase collections. It’s built for developers who want stronger guarantees, better autocomplete, and fewer runtime surprises when building on top of PocketBase.

Links:

• GitHub: https://github.com/odama626/pocketbase-schema
• npm: https://www.npmjs.com/package/@sparkstone/pocketbase-schema

What it does

• Automatic type generation
  Pull your PocketBase schema and generate complete TypeScript definitions for collections and records.

• Collections enum
  Access collection names as constants instead of raw strings for safer queries.

• Field option enums
  Automatically generate enums for select fields to ensure strict typing.

• CLI & API support
  Run it as a command-line tool or import it into your Node.js toolchain.

• Local-first configuration
  Uses cosmiconfig, so configuration can live in a config file, package.json, or a custom location.

Installation

npm install @sparkstone/pocketbase-schema --save-dev

or

pnpm add @sparkstone/pocketbase-schema --save-dev

Usage

Generate types from an exported PocketBase schema:

pocketbase-schema generate \
  --input=pb_schema.json \
  --output=src/lib/pb-types.ts

Or use it programmatically:

import { generate } from "@sparkstone/pocketbase-schema";

generate({
  input: "./pb_schema.json",
  output: "./src/lib/pb-types.ts",
});

Configuration

Configuration is handled via cosmiconfig. Supported formats include .json, .yaml, .js, or .ts.

Example .pocketbase-schema.config.ts:

export default {
  email: "admin@example.com",
  password: "yourpassword",
  url: "http://127.0.0.1:8090",
  schema: {
    outputPath: "src/lib/pb.schema.json",
  },
  types: {
    outputPath: "src/lib/pb.types.ts",
  },
};

Be sure to add your config file to .gitignore to avoid leaking credentials.

Using the generated types

import PocketBase from "pocketbase";
import { Collections, Posts } from "./pb.types";

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

const posts = await pb.collection(Collections.Posts).getFullList<Posts>();

Expanding relations

The recommended pattern is to extend generated types:

import { Posts, Comments, Reactions } from "./pb.types";

interface Post extends Posts {
  expand: {
    comments: Comments[];
    reactions: Reactions[];
  };
}

pb.collection(Collections.Posts).getFullList<Post>({
  expand: "comments,reactions",
});

Why it exists

PocketBase makes it easy to move fast, but keeping frontend and backend schemas in sync can quietly become a source of bugs. pocketbase-schema turns your PocketBase schema into a single source of truth for types, eliminating copy-paste definitions and fragile string-based queries.

“We built pocketbase-schema because we love PocketBase — and we wanted full type safety without manual copy-pasting.” — The Sparkstone Team

This remind you of a problem you've been dealing with?

I'd be happy to discuss it with you and see if it's something we could turn into a solution.