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.
PocketBase
✓ import PocketBase from 'pocketbase';
✗ import { PocketBase } from 'pocketbase';
PocketBase is exported as a default export for ES modules.
PocketBase
✓ const PocketBase = require('pocketbase/cjs');
✗ const PocketBase = require('pocketbase');
For CommonJS environments, explicitly import from the '/cjs' path.
EventSource
✓ import { EventSource } from 'eventsource'; global.EventSource = EventSource;
✗ new EventSource(...)
Node.js requires an `EventSource` polyfill to use real-time subscriptions. Remember to assign it to `global.EventSource`.
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();
Debug
Known issues
breakingThe 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.fixAdjust any client-side logic that assumes a maximum batch size of 500 when using `getFullList()`. Consider explicit `batch` parameter if the change is problematic.
affects: >=0.26.6
gotchaWhen 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.fixEnsure your application handles the absence of these query parameters if they were previously expected to be present with `null`/`undefined` values.
affects: >=0.26.7
breakingWhen 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.fixReview 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.
affects: >=0.26.0
gotchaNode.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.fixInstall `cross-fetch` and import it as `import 'cross-fetch/polyfill';` at the entry point of your Node.js application.
affects: <17.0.0 (Node.js)
gotchaNode.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.fixInstall the appropriate `EventSource` polyfill and assign it to the global scope: `import { EventSource } from 'eventsource'; global.EventSource = EventSource;`. affects: *
breakingThe `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.fixUpdate to v0.26.8 or later to ensure `authWithOAuth2()` cancellations correctly propagate. If stuck on an older version, implement custom timeout/rejection logic.
affects: <0.26.8
gotchaWhen 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.fixAlways use `pb.filter()` when constructing filter expressions from user-provided data, e.g., `filter: pb.filter('field = {:value}', { value: userInput })`. affects: *
Errors
Common errors & fixes
ReferenceError: fetch is not defined
Running PocketBase SDK in Node.js < 17 without a `fetch` polyfill.
fixInstall `cross-fetch` (`npm install cross-fetch`) and add `import 'cross-fetch/polyfill';` to your application entry point.
ReferenceError: EventSource is not defined
Attempting to use PocketBase real-time subscriptions in Node.js without an `EventSource` polyfill.
fixInstall `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
Incorrect CommonJS import path for `pocketbase` package.
fixFor CommonJS, use `const PocketBase = require('pocketbase/cjs');`. TypeError: Failed to parse JSON body from response
This error or `DOMException.SyntaxError` can occur in Safari (pre v0.26.5) when an aborted request causes `response.json()` to fail.
fixUpdate the `pocketbase` SDK to version `0.26.5` or newer, which includes a fix for better abort error detection in Safari.
Audit
Dependencies
cross-fetchoptional`fetch()` API polyfill for Node.js environments older than v17.
eventsourceoptional`EventSource` polyfill for Node.js environments to enable real-time subscriptions.
react-native-sseoptional`EventSource` polyfill for React Native environments to enable real-time subscriptions.