PocketBase JavaScript SDK

Common errors

• ReferenceError: fetch is not defined

  cause Running PocketBase SDK in Node.js < 17 without a `fetch` polyfill.
  fix Install `cross-fetch` (`npm install cross-fetch`) and add `import 'cross-fetch/polyfill';` to your application entry point.

• ReferenceError: EventSource is not defined

  cause Attempting to use PocketBase real-time subscriptions in Node.js without an `EventSource` polyfill.
  fix Install `eventsource` (`npm install eventsource`) and add `import { EventSource } from 'eventsource'; global.EventSource = EventSource;` (or `react-native-sse` for React Native) to your application entry point.

• const PocketBase = require('pocketbase'); // Error: `PocketBase is not a constructor` or similar

  cause Incorrect CommonJS import path for `pocketbase` package.
  fix For CommonJS, use `const PocketBase = require('pocketbase/cjs');`.

• TypeError: Failed to parse JSON body from response

  cause This error or `DOMException.SyntaxError` can occur in Safari (pre v0.26.5) when an aborted request causes `response.json()` to fail.
  fix Update the `pocketbase` SDK to version `0.26.5` or newer, which includes a fix for better abort error detection in Safari.

Warnings

• breaking The default batch size for `pb.collection('collectionName').getFullList()` was increased from 500 to 1000 for consistency with the Dart SDK and v0.23+ API limits. This may affect memory usage or pagination logic in applications that relied on the previous default.
  Fix: Adjust any client-side logic that assumes a maximum batch size of 500 when using `getFullList()`. Consider explicit `batch` parameter if the change is problematic.
• gotcha When using `pb.files.getURL()`, passing `null` or `undefined` as query parameter values will now cause those parameters to be skipped from the generated URL, matching the behavior of fetch methods.
  Fix: Ensure your application handles the absence of these query parameters if they were previously expected to be present with `null`/`undefined` values.
• breaking When submitting an object with `Blob` or `File` fields, `undefined` properties are now ignored during `FormData` conversion, aligning with how `JSON.stringify` works. This change ensures consistency but might alter submitted data if `undefined` values were implicitly relied upon.
  Fix: Review any code that sends form data containing `Blob`/`File` fields and `undefined` properties. Explicitly set properties to `null` if you intend for them to be part of the payload, or remove them entirely if they should not be sent.
• gotcha Node.js versions older than 17 require a `fetch()` API polyfill (e.g., `cross-fetch`) to function correctly, as `fetch` is not natively available in those versions.
  Fix: Install `cross-fetch` and import it as `import 'cross-fetch/polyfill';` at the entry point of your Node.js application.
• gotcha Node.js environments require an `EventSource` polyfill (e.g., `eventsource` for server, `react-native-sse` for React Native) to use PocketBase's real-time subscriptions, as `EventSource` is not a native global object.
  Fix: Install the appropriate `EventSource` polyfill and assign it to the global scope: `import { EventSource } from 'eventsource'; global.EventSource = EventSource;`.
• breaking The `authWithOAuth2()` `Promise` was not properly rejecting when manually cancelled via `pb.cancelRequest()`, especially when waiting for a real-time subscription. This behavior is now corrected.
  Fix: Update to v0.26.8 or later to ensure `authWithOAuth2()` cancellations correctly propagate. If stuck on an older version, implement custom timeout/rejection logic.
• gotcha When accepting untrusted user input as `filter` string arguments in Node.js or Deno server-side list queries, it is strongly recommended to use `pb.filter(expr, params)` to prevent string injection attacks. This helper automatically escapes placeholder parameters.
  Fix: Always use `pb.filter()` when constructing filter expressions from user-provided data, e.g., `filter: pb.filter('field = {:value}', { value: userInput })`.

Install

• npm install pocketbase npm
• yarn add pocketbase yarn
• pnpm add pocketbase pnpm

Imports

• PocketBase
  wrong:

  import { PocketBase } from 'pocketbase';

  correct:

  import PocketBase from 'pocketbase';

  PocketBase is exported as a default export for ES modules.
• PocketBase
  wrong:

  const PocketBase = require('pocketbase');

  correct:

  const PocketBase = require('pocketbase/cjs');

  For CommonJS environments, explicitly import from the '/cjs' path.
• EventSource
  wrong:

  new EventSource(...)

  correct:

  import { EventSource } from 'eventsource'; global.EventSource = EventSource;

  Node.js requires an `EventSource` polyfill to use real-time subscriptions. Remember to assign it to `global.EventSource`.

Quickstart

Demonstrates initializing the PocketBase client, authenticating a user, fetching and filtering records, and creating a new record. Includes necessary polyfills for Node.js compatibility.

import PocketBase from 'pocketbase';
import 'cross-fetch/polyfill'; // Only for Node < 17

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

async function initializeApp() {
  try {
    // Example: Authenticate as an auth collection record
    const userData = await pb.collection('users').authWithPassword('test@example.com', '123456');
    console.log('User authenticated:', userData.record.email);

    // Example: List and filter 'posts' collection records
    const result = await pb.collection('posts').getList(1, 20, {
      filter: pb.filter('status = true && created > {:date}', { date: new Date('2023-01-01T00:00:00Z') }),
      sort: '-created'
    });
    console.log('Posts found:', result.items.length);

    // Example: Create a new record
    const newPost = await pb.collection('posts').create({
      title: 'My new post',
      content: 'This is some content.',
      status: true,
      author: userData.record.id
    });
    console.log('New post created:', newPost.id);

  } catch (error) {
    console.error('An error occurred:', error);
    if (error.isAbort) {
        console.error('Request was aborted.');
    }
  }
}

initializeApp();