{"id":11571,"library":"pocketbase","title":"PocketBase JavaScript SDK","description":"The PocketBase JavaScript SDK is the official client library for interacting with the PocketBase API, supporting both browser and Node.js environments. It provides comprehensive functionalities for data management, user authentication (including password and OAuth2 flows), and real-time subscriptions. The current stable version is 0.26.8, with the project maintaining a frequent release cadence to deliver bug fixes, performance improvements, and feature parity with the core PocketBase server. Key differentiators include its seamless integration with the PocketBase ecosystem, robust type definitions, flexible authentication store options (e.g., `LocalAuthStore` for web, `AsyncAuthStore` for React Native), and a crucial `pb.filter()` helper for securely binding filter parameters to prevent string injection attacks when handling untrusted server-side input.","status":"active","version":"0.26.8","language":"javascript","source_language":"en","source_url":"git://github.com/pocketbase/js-sdk","tags":["javascript","pocketbase","pocketbase-js","js-sdk","javascript-sdk","pocketbase-sdk","typescript"],"install":[{"cmd":"npm install pocketbase","lang":"bash","label":"npm"},{"cmd":"yarn add pocketbase","lang":"bash","label":"yarn"},{"cmd":"pnpm add pocketbase","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"`fetch()` API polyfill for Node.js environments older than v17.","package":"cross-fetch","optional":true},{"reason":"`EventSource` polyfill for Node.js environments to enable real-time subscriptions.","package":"eventsource","optional":true},{"reason":"`EventSource` polyfill for React Native environments to enable real-time subscriptions.","package":"react-native-sse","optional":true}],"imports":[{"note":"PocketBase is exported as a default export for ES modules.","wrong":"import { PocketBase } from 'pocketbase';","symbol":"PocketBase","correct":"import PocketBase from 'pocketbase';"},{"note":"For CommonJS environments, explicitly import from the '/cjs' path.","wrong":"const PocketBase = require('pocketbase');","symbol":"PocketBase","correct":"const PocketBase = require('pocketbase/cjs');"},{"note":"Node.js requires an `EventSource` polyfill to use real-time subscriptions. Remember to assign it to `global.EventSource`.","wrong":"new EventSource(...)","symbol":"EventSource","correct":"import { EventSource } from 'eventsource'; global.EventSource = EventSource;"}],"quickstart":{"code":"import PocketBase from 'pocketbase';\nimport 'cross-fetch/polyfill'; // Only for Node < 17\n\nconst pb = new PocketBase('http://127.0.0.1:8090');\n\nasync function initializeApp() {\n  try {\n    // Example: Authenticate as an auth collection record\n    const userData = await pb.collection('users').authWithPassword('test@example.com', '123456');\n    console.log('User authenticated:', userData.record.email);\n\n    // Example: List and filter 'posts' collection records\n    const result = await pb.collection('posts').getList(1, 20, {\n      filter: pb.filter('status = true && created > {:date}', { date: new Date('2023-01-01T00:00:00Z') }),\n      sort: '-created'\n    });\n    console.log('Posts found:', result.items.length);\n\n    // Example: Create a new record\n    const newPost = await pb.collection('posts').create({\n      title: 'My new post',\n      content: 'This is some content.',\n      status: true,\n      author: userData.record.id\n    });\n    console.log('New post created:', newPost.id);\n\n  } catch (error) {\n    console.error('An error occurred:', error);\n    if (error.isAbort) {\n        console.error('Request was aborted.');\n    }\n  }\n}\n\ninitializeApp();","lang":"typescript","description":"Demonstrates initializing the PocketBase client, authenticating a user, fetching and filtering records, and creating a new record. Includes necessary polyfills for Node.js compatibility."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.26.6"},{"fix":"Ensure your application handles the absence of these query parameters if they were previously expected to be present with `null`/`undefined` values.","message":"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.","severity":"gotcha","affected_versions":">=0.26.7"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.26.0"},{"fix":"Install `cross-fetch` and import it as `import 'cross-fetch/polyfill';` at the entry point of your Node.js application.","message":"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.","severity":"gotcha","affected_versions":"<17.0.0 (Node.js)"},{"fix":"Install the appropriate `EventSource` polyfill and assign it to the global scope: `import { EventSource } from 'eventsource'; global.EventSource = EventSource;`.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"breaking","affected_versions":"<0.26.8"},{"fix":"Always use `pb.filter()` when constructing filter expressions from user-provided data, e.g., `filter: pb.filter('field = {:value}', { value: userInput })`.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `cross-fetch` (`npm install cross-fetch`) and add `import 'cross-fetch/polyfill';` to your application entry point.","cause":"Running PocketBase SDK in Node.js < 17 without a `fetch` polyfill.","error":"ReferenceError: fetch is not defined"},{"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.","cause":"Attempting to use PocketBase real-time subscriptions in Node.js without an `EventSource` polyfill.","error":"ReferenceError: EventSource is not defined"},{"fix":"For CommonJS, use `const PocketBase = require('pocketbase/cjs');`.","cause":"Incorrect CommonJS import path for `pocketbase` package.","error":"const PocketBase = require('pocketbase'); // Error: `PocketBase is not a constructor` or similar"},{"fix":"Update the `pocketbase` SDK to version `0.26.5` or newer, which includes a fix for better abort error detection in Safari.","cause":"This error or `DOMException.SyntaxError` can occur in Safari (pre v0.26.5) when an aborted request causes `response.json()` to fail.","error":"TypeError: Failed to parse JSON body from response"}],"ecosystem":"npm"}