Official JavaScript SDK (browser and node) for interacting with the PocketBase API.
<script src="/path/to/dist/pocketbase.umd.js"></script>
OR if you are using ES modules:
<script type="module">
import PocketBase from '/path/to/dist/pocketbase.es.mjs'
...
</script>
npm install pocketbase --save
// Using ES modules (default)
import PocketBase from 'pocketbase'
// OR if you are using CommonJS modules
const PocketBase = require('pocketbase/cjs')
๐ง For Node < 17 you'll need to load a
fetch()
polyfill. I recommend lquixada/cross-fetch:// npm install cross-fetch --save require('cross-fetch/polyfill');
๐ง Node doesn't have native
EventSource
implementation, so in order to use the realtime service (aka.client.realtime.subscribe()
) you'll need to load aEventSource
polyfill. I recommend EventSource/eventsource:// npm install eventsource --save global.EventSource = require('eventsource');
import PocketBase from 'pocketbase';
const client = new PocketBase('http://127.0.0.1:8090');
...
// list and filter "example" collection records
const result = await client.records.getList('example', 1, 20, {
filter: 'status = true && created > "2022-08-01 10:00:00"'
});
// authenticate as regular user
const userData = await client.users.authViaEmail('[email protected]', '123456');
// or as admin
const adminData = await client.admins.authViaEmail('[email protected]', '123456');
// and much more...
More detailed API docs and copy-paste examples could be found in the API documentation for each service.
PocketBase Web API supports file upload via multipart/form-data
requests,
which means that to upload a file it is enough to provide a FormData
object as body.
Here is a simple browser example of uploading multiple files together with some other regular fields:
<input type="file" id="fileInput" />
import PocketBase from 'pocketbase';
const client = new PocketBase('http://127.0.0.1:8090');
...
const formData = new FormData();
const fileInput = document.getElementById('fileInput');
// listen to file input changes and add the selected files to the form data
fileInput.addEventListener('change', function () {
for (let file of fileInput.files) {
formData.append('documents', file);
}
});
// set some other regular text field value
formData.append('title', 'Hello world!');
...
// upload and create new record
const createdRecord = await client.Records.create('example', formData);
All services return a standard Promise-based response, so the error handling is straightforward:
client.records.getList('example', 1, 50).then((result) {
// success...
console.log('Result:', result);
}).catch((error) {
// error...
console.log('Error:', error);
});
// OR if you are using the async/await syntax:
try {
const result = await client.records.getList('example', 1, 50);
console.log('Result:', result);
} catch (error) {
console.log('Error:', error);
}
The response error is normalized and always returned as ClientResponseError
object with the following public fields that you could use:
ClientResponseError {
url: string, // requested url
status: number, // response status code
data: { ... }, // the API JSON error response
isAbort: boolean, // is abort/cancellation error
originalError: Error|null, // the original non-normalized error
}
The SDK keeps track of the authenticated token and auth model for you via the client.authStore
instance.
The default LocalAuthStore
uses the browser's LocalStorage
if available, otherwise - will fallback to runtime/memory (aka. on page refresh or service restart you'll have to authenticate again).
The default client.authStore
extends BaseAuthStore
and has the following public members that you can use:
BaseAuthStore {
// base fields
token: string // the authenticated token
model: User|Admin|null // the authenticated User or Admin model
isValid: boolean // checks if the store has existing and unexpired token
// main methods
clear() // "logout" the authenticated User or Admin
save(token, model) // update the store with the new auth data
onChange(callback) // register a callback that will be called on store change
// cookie parse and serialize helpers
loadFromCookie(cookieHeader, key = 'pb_auth')
exportToCookie(options = {}, key = 'pb_auth')
}
To "logout" an authenticated user or admin, you can just call client.authStore.clear()
.
To "listen" for changes in the auth store, you can register a new listener via client.authStore.onChange
, eg:
const removeListener = client.authStore.onChange((token, model) => {
console.log('New store data:', token, model)
});
removeListener(); // (optional) removes the attached listener function
If you want to create your own AuthStore
, you can extend BaseAuthStore
and pass the new custom instance as constructor argument to the client:
import PocketBase, { BaseAuthStore } from 'pocketbase';
class CustomAuthStore extends BaseAuthStore {
save(token, model) {
super.save(token, model);
// your custom business logic...
}
}
const client = new PocketBase('http://127.0.0.1:8090', 'en-US', CustomAuthStore());
The SDK client will auto cancel duplicated pending requests for you.
For example, if you have the following 3 duplicated calls, only the last one will be executed, while the first 2 will be cancelled with ClientResponseError
error:
client.records.getList('example', 1, 20) // cancelled
client.records.getList('example', 1, 20) // cancelled
client.records.getList('example', 1, 20) // executed
To change this behavior, you could make use of 2 special query parameters:
$autoCancel
- set it tofalse
to disable auto cancellation for this request$cancelKey
- set it to a string that will be used as request identifier and based on which pending duplicated requests will be matched (default toHTTP_METHOD + url
, eg. "get /api/users?page=1")
Example:
client.records.getList('example', 1, 20); // cancelled
client.records.getList('example', 1, 20); // executed
client.records.getList('example', 1, 20, { '$autoCancel': false }); // executed
client.records.getList('example', 1, 20, { '$autoCancel': false }) // executed
client.records.getList('example', 1, 20, { '$cancelKey': "test" }) // cancelled
client.records.getList('example', 1, 20, { '$cancelKey': "test" }) // executed
To manually cancel pending requests, you could use client.cancelAllRequests()
or client.cancelRequest(cancelKey)
.
If you want to completelly disable the auto cancellation behavior, you could use the
client.beforeSend
hook and delete thereqConfig.signal
property.
Sometimes you may want to modify the request sent data or to customize the response.
To accomplish this, the SDK provides 2 function hooks:
-
beforeSend
- triggered right before sending thefetch
request, allowing you to inspect/modify the request config.const client = new PocketBase('http://127.0.0.1:8090'); client.beforeSend = function (url, reqConfig) { // For list of the possible reqConfig properties check // https://developer.mozilla.org/en-US/docs/Web/API/fetch#options reqConfig.headers = Object.assign({}, reqConfig.headers, { 'X-Custom-Header': 'example', }); return reqConfig; };
-
afterSend
- triggered after successfully sending thefetch
request, allowing you to inspect/modify the response object and its parsed data.const client = new PocketBase('http://127.0.0.1:8090'); client.afterSend = function (response, data) { // do something with the response state console.log(response.status); return Object.assign(data, { // extend the data... "additionalField": 123, }); };
Unfortunately, there is no "one size fits all" solution because each framework handle SSR differently (and even in a single framework there is more than one way of doing things).
But in general, the idea is to use a cookie based flow:
- Create a new
PocketBase
instance for each server-side request - "Load/Feed" your
client.authStore
with data from the request cookie - Perform your application server-side actions
- Before returning the response to the client, update the cookie with the latest
client.authStore
state
All BaseAuthStore
instances have 2 helper methods that
should make working with cookies a little bit easier:
// update the store with the parsed data from the cookie string
client.authStore.loadFromCookie('pb_auth=...');
// exports the store data as cookie, with option to extend the default SameSite, Secure, HttpOnly, Path and Expires attributes
client.authStore.exportToCookie({ httpOnly: false }); // Output: 'pb_auth=...'
Below you could find several examples:
SvelteKit
One way to integrate with SvelteKit SSR could be to create the PocketBase client in a hook handle
and pass it to the other server-side actions using the event.locals
.
// src/hooks.js
import PocketBase from 'pocketbase';
export async function handle({ event, resolve }) {
event.locals.pocketbase = new PocketBase("http://127.0.0.1:8090");
// load the store data from the request cookie string
event.locals.pocketbase.authStore.loadFromCookie(event.request.headers.get('cookie') || '');
const response = await resolve(event);
// send back the default 'pb_auth' cookie to the client with the latest store state
response.headers.set('set-cookie', event.locals.pocketbase.authStore.exportToCookie());
return response;
}
And then, in some of your server-side actions, you could directly access the previously created event.locals.pocketbase
instance:
// src/routes/login/+server.js
//
// creates a `POST /login` server-side endpoint
export function POST({ request, locals }) {
const { email, password } = await request.json();
const { token, user } = await locals.pocketbase.users.authViaEmail(email, password);
return new Response('Success...');
}
Nuxt 3
One way to integrate with Nuxt 3 SSR could be to create the PocketBase client in a nuxt plugin
and provide it as a helper to the nuxtApp
instance:
// plugins/pocketbase.js
import PocketBase from 'pocketbase';
export default defineNuxtPlugin((nuxtApp) => {
return {
provide: {
pocketbase: () => {
const client = new PocketBase('http://127.0.0.1:8090');
// load the store data from the request cookie string
client.authStore.loadFromCookie(nuxtApp.ssrContext?.event?.req?.headers?.cookie || '');
// send back the default 'pb_auth' cookie to the client with the latest store state
client.authStore.onChange(() => {
if (nuxtApp.ssrContext?.event?.res) {
nuxtApp.ssrContext.event.res.setHeader('set-cookie', client.authStore.exportToCookie());
}
});
return client;
}
}
}
});
And then in your component you could access it like this:
<template>
<div>
Show: {{ data }}
</div>
</template>
<script setup>
const { data } = await useAsyncData(async (nuxtApp) => {
const client = nuxtApp.$pocketbase();
// fetch and return all "demo" records...
return await client.records.getFullList('demo');
})
</script>
For Nuxt 2 you could use similar approach, but instead of
nuxtApp
you could use a store state to store/create the localPocketBase
instance.
Next.js
Next.js doesn't seem to have a central place where you can read/modify the server request and response.
There is support for middlewares,
but they are very limited and, at the time of writing, you can't pass data from a middleware to the getServerSideProps
functions (vercel/next.js#31792).
One way to integrate with Next.js SSR could be to create a custom PocketBase
instance in each of your getServerSideProps
:
import PocketBase, { BaseAuthStore } from 'pocketbase';
class NextAuthStore extends BaseAuthStore {
constructor(req, res) {
super();
this.req = req;
this.res = res;
this.loadFromCookie(this.req?.headers?.cookie);
}
save(token, model) {
super.save(token, model);
this.res?.setHeader('set-cookie', this.exportToCookie());
}
clear() {
super.clear();
this.res?.setHeader('set-cookie', this.exportToCookie());
}
}
export async function getServerSideProps({ req, res }) {
const client = new PocketBase("http://127.0.0.1:8090");
client.authStore = new NextAuthStore(req, res);
// fetch example records...
const result = await client.records.getList("example", 1, 30);
return {
props: {
// ...
},
}
}
export default function Home() {
return (
<div>Hello world!</div>
)
}
The most common frontend related vulnerability is XSS (and CSRF when dealing with cookies). Fortunately, modern browsers can detect and mitigate most of this type of attacks if Content Security Policy (CSP) is provided.
To prevent a malicious user or 3rd party script to steal your PocketBase auth token, it is recommended to configure a basic CSP for your application (either as meta
tag or HTTP header).
This is out of the scope of the SDK, but you could find more resources about CSP at:
const client = new PocketBase(
baseUrl = '/',
lang = 'en-US',
authStore = LocalAuthStore
);
Each instance method returns the
PocketBase
instance allowing chaining.
Method | Description |
---|---|
client.send(path, reqConfig = {}) |
Sends an api http request. |
client.cancelAllRequests() |
Cancels all pending requests. |
client.cancelRequest(cancelKey) |
Cancels single request by its cancellation token key. |
client.buildUrl(path, reqConfig = {}) |
Builds a full client url by safely concatenating the provided path. |
Each service call returns a
Promise
object with the API response.
Resource | Description |
---|---|
Admins | |
๐client.admins.authViaEmail(email, password, bodyParams = {}, queryParams = {}) |
Authenticate an admin account by its email and password and returns a new admin token and admin data. |
๐client.admins.refresh(bodyParams = {}, queryParams = {}) |
Refreshes the current admin authenticated instance and returns a new admin token and admin data. |
๐client.admins.requestPasswordReset(email, bodyParams = {}, queryParams = {}) |
Sends admin password reset request. |
๐client.admins.confirmPasswordReset(passwordResetToken, password, passwordConfirm, bodyParams = {}, queryParams = {}) |
Confirms admin password reset request. |
๐client.admins.getList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated admins list. |
๐client.admins.getFullList(batchSize = 100, queryParams = {}) |
Returns a list with all admins batch fetched at once. |
๐client.admins.getOne(id, queryParams = {}) |
Returns single admin by its id. |
๐client.admins.create(bodyParams = {}, queryParams = {}) |
Creates a new admin. |
๐client.admins.update(id, bodyParams = {}, queryParams = {}) |
Updates an existing admin by its id. |
๐client.admins.delete(id, queryParams = {}) |
Deletes an existing admin by its id. |
Users | |
๐client.users.listAuthMethods(queryParams = {}) |
Returns all available application auth methods. |
๐client.users.authViaEmail(email, password, bodyParams = {}, queryParams = {}) |
Authenticate a user account by its email and password and returns a new user token and user data. |
๐client.users.authViaOAuth2(clientName, code, codeVerifier, redirectUrl, bodyParams = {}, queryParams = {}) |
Authenticate a user via OAuth2 client provider. |
๐client.users.refresh(bodyParams = {}, queryParams = {}) |
Refreshes the current user authenticated instance and returns a new user token and user data. |
๐client.users.requestPasswordReset(email, bodyParams = {}, queryParams = {}) |
Sends user password reset request. |
๐client.users.confirmPasswordReset(passwordResetToken, password, passwordConfirm, bodyParams = {}, queryParams = {}) |
Confirms user password reset request. |
๐client.users.requestVerification(email, bodyParams = {}, queryParams = {}) |
Sends user verification email request. |
๐client.users.confirmVerification(verificationToken, bodyParams = {}, queryParams = {}) |
Confirms user email verification request. |
๐client.users.requestEmailChange(newEmail, bodyParams = {}, queryParams = {}) |
Sends an email change request to the authenticated user. |
๐client.users.confirmEmailChange(emailChangeToken, password, bodyParams = {}, queryParams = {}) |
Confirms user new email address. |
๐client.users.getList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated users list. |
๐client.users.getFullList(batchSize = 100, queryParams = {}) |
Returns a list with all users batch fetched at once. |
๐client.users.getOne(id, queryParams = {}) |
Returns single user by its id. |
๐client.users.create(bodyParams = {}, queryParams = {}) |
Creates a new user. |
๐client.users.update(id, bodyParams = {}, queryParams = {}) |
Updates an existing user by its id. |
๐client.users.delete(id, queryParams = {}) |
Deletes an existing user by its id. |
Realtime (for node environments you'll have to install an EventSource polyfill beforehand, eg. https://github.com/EventSource/eventsource) |
|
๐client.realtime.subscribe(subscription, callback) |
Inits the sse connection (if not already) and register the subscription. |
๐client.realtime.unsubscribe(subscription = "") |
Unsubscribe from a subscription (if empty - unsubscribe from all registered subscriptions). |
Collections | |
๐client.collections.getList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated collections list. |
๐client.collections.getFullList(batchSize = 100, queryParams = {}) |
Returns a list with all collections batch fetched at once. |
๐client.collections.getOne(id, queryParams = {}) |
Returns single collection by its id. |
๐client.collections.create(bodyParams = {}, queryParams = {}) |
Creates a new collection. |
๐client.collections.update(id, bodyParams = {}, queryParams = {}) |
Updates an existing collection by its id. |
๐client.collections.delete(id, queryParams = {}) |
Deletes an existing collection by its id. |
๐client.collections.import(collections, deleteMissing = false, queryParams = {}) |
Imports the provided collections. |
Records | |
๐client.records.getList(collectionIdOrName, page = 1, perPage = 30, queryParams = {}) |
Returns paginated records list. |
๐client.records.getFullList(collectionIdOrName, batchSize = 100, queryParams = {}) |
Returns a list with all records batch fetched at once. |
๐client.records.getOne(collectionIdOrName, id, queryParams = {}) |
Returns single record by its id. |
๐client.records.create(collectionIdOrName, bodyParams = {}, queryParams = {}) |
Creates a new record. |
๐client.records.update(collectionIdOrName, id, bodyParams = {}, queryParams = {}) |
Updates an existing record by its id. |
๐client.records.delete(collectionIdOrName, id, bodyParams = {}, queryParams = {}) |
Deletes an existing record by its id. |
Logs | |
๐client.logs.getRequestsList(page = 1, perPage = 30, queryParams = {}) |
Returns paginated request logs list. |
๐client.logs.getRequest(id, queryParams = {}) |
Returns a single request log by its id. |
๐client.logs.getRequestsStats(queryParams = {}) |
Returns request logs statistics. |
Settings | |
๐client.settings.getAll(queryParams = {}) |
Fetch all available app settings. |
๐client.settings.update(bodyParams = {}, queryParams = {}) |
Bulk updates app settings. |
๐client.settings.testS3(queryParams = {}) |
Performs a S3 storage connection test. |
๐client.settings.testEmail(toEmail, emailTemplate, queryParams = {}) |
Sends a test email. |
# run unit tests
npm test
# build and minify for production
npm run build