Data and clients

JavaScript SDK

Build a JavaScript client that authenticates users, manages records and files, and receives realtime updates from PocketBase.

Use the official JavaScript SDK to connect a browser, Node.js, or React Native application to PocketBase. In this tutorial you will authenticate a user, create and query records, upload a file, and subscribe to record changes.

Before you begin

You need a running PocketBase server, a collection named posts with a title text field, and a client application that can install npm packages. Configure the collection's API rules before testing: createRule, listRule, viewRule, and updateRule determine which requests succeed. Use a test account and synthetic data.

Install the SDK in your application:

bash

npm install pocketbase

The SDK is asynchronous. Keep the PocketBase instance in a module shared by the code that performs authentication and data operations so its authenticated state is available to later calls.

Build the client workflow

Initialize the client

Import PocketBase and point it at your server.

import PocketBase from 'pocketbase';

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

The client is ready to make unauthenticated requests. Replace the local URL with the URL of your own server when you deploy the application.

Authenticate a user

Authenticate an auth record with its email and password.

try {
  const authData = await pb.collection('users').authWithPassword(
    'reader@example.com',
    'use-a-test-password'
  );
  console.log(authData.record.id);
} catch (error) {
  console.error('Sign-in failed', error);
}

On success, pb.authStore contains the session state and authData.record contains the authenticated record. Do not hard-code real credentials or log tokens in a production application.

Create and query records

Create a post, then request a filtered page of posts.

const created = await pb.collection('posts').create({
  title: 'A PocketBase note'
});

const page = await pb.collection('posts').getList(1, 30, {
  sort: '-created',
  filter: 'title ~ "PocketBase"'
});

console.log(created.id, page.items.length);

The create call returns the new record. The list call returns a paginated result with page, perPage, totalItems, totalPages, and items. A collection rule can filter the visible results or reject the request.

Update a record and upload a file

Send a partial update with update. To upload a file, pass a FormData value for a file field defined in the collection.

const updated = await pb.collection('posts').update(created.id, {
  title: 'An updated PocketBase note'
});

const body = new FormData();
body.append('title', updated.title);
body.append('attachment', fileInput.files[0]);
const withFile = await pb.collection('posts').update(created.id, body);
console.log(withFile.id);

update uses PATCH /api/collections/{collection}/records/{recordId} and accepts JSON or multipart form data. The file field must exist in the collection schema, and the update rule must permit the caller to change the record.

Subscribe to realtime changes

Subscribe to the collection after the client has been initialized.

const unsubscribe = await pb.collection('posts').subscribe('*', (event) => {
  console.log(event.action, event.record.id);
});

// Call this when the screen or component is disposed.
await pb.collection('posts').unsubscribe('*');

The callback receives a change action and record. Unsubscribe when the consuming view is disposed so a view does not retain a subscription after navigation.

✅When the workflow succeeds, the console shows an authenticated record ID, the created and updated post ID, a page count, and subsequent record change events.

Recover from common failures

A 403 response means the relevant collection rule does not permit the request, or the endpoint requires superuser access. Review the rule and test with the intended user role; do not weaken rules as a generic fix.
A 400 response usually indicates invalid field data or a malformed filter. Compare the payload and filter with the collection schema, then retry with the smallest valid request.
A missing record or collection produces a not-found response. Confirm the collection name and obtain the record ID from a successful create or list response.
A failed upload usually means the body is not multipart form data or the field is not a file field. Send FormData and use the exact schema field name.

Next steps

Continue with realtime subscriptions, files and storage, and API rules and filters. For a language alternative, see Dart SDK.