pocketbase-jsvm

PocketBase JSVM

PocketBase embeds a Goja JavaScript engine for server-side extensions. Code runs inside the PocketBase process — synchronous, no Node/Browser APIs.

Version split — read this first

v0.23 is a breaking JSVM boundary. PocketHost runs both legacy (≤ v0.22) and modern (≥ v0.23) instances. Always confirm the instance PocketBase version before writing or porting hooks — do not mix APIs across versions.

When in doubt, open the JSVM reference for that version — hook names, route handler signatures, and $app methods differ. For mothership v0.39 port work, read v023-upgrade.md and the official JSVM upgrade guide.

Pre-flight checklist

Before writing hook code, verify:

• Target PocketBase version — use the matching JSVM docs (≤ v0.22 vs ≥ v0.23)
• No async/await, Promises, or .then()
• No fetch, setTimeout, setInterval, DOM APIs
• No Node built-ins (fs, http, path, etc.)
• Use require() for modules (CommonJS only)
• Use $app / record APIs — not new PocketBase()
• External HTTP via $http.send() (sync), not fetch
• $app.store() values that cross requests: JSON.stringify/parse at boundaries — never mutate get() results in place (app-store.md)
• Json fields, hook routers, client errors: skim quirks.md if behavior looks like Node

For full environment constraints, see constraints.md. Goja behavioral quirks (toString, hoisting, json fields, error sanitization): quirks.md.

File layout

pb_hooks/
├── main.pb.js          # auto-loaded entry hooks
├── config/
│   └── config.js       # shared module (require target)
└── posts.create.pb.js

• Only *.pb.js files are auto-loaded as hook entry points.
• Shared modules: plain .js files loaded via require().
• Use ${__hooks} for the hooks directory path:

const config = require(`${__hooks}/config/config.js`)

Hook file hot reload (in-process)

PocketBase watches hook JS on disk (pb_hooks/*.pb.js and files loaded via require()). When they change, it reloads hook code inside the running process — the PocketBase process does not exit. This is separate from PM2 or Docker restarts.

Operational implications:

• Do not git checkout, rsync, or deploy while PocketBase is running if the operation swaps hook files incrementally. A mid-checkout tree can be picked up and loaded as a torn mix of old and new code.
• Mothership: stop before branch switches or bulk hook deploys (e.g. v39.sh --forward keeps mothership stopped until checkout finishes, then pm2 reload).
• Customer instances on PocketHost: FTP/phio deploy restarts the instance container so hooks reload from a consistent tree — different mechanism, same “don’t run torn hooks” goal.

Hook categories

Names differ by version — check the JSVM reference for your target.

Collection-scoped hooks take the collection name/id as the last argument:

onRecordAfterCreateRequest((e) => {
  const record = e.record
  // ...
}, 'users')

Custom routes

≤ v0.22 — Echo-style context c, colon params:

routerAdd('POST', '/test/:testId', (c) => {
  const testId = c.pathParam('testId')
  return c.json(200, { testId })
})

≥ v0.23 — request event e, brace params:

routerAdd('POST', '/test/{testId}', (e) => {
  const testId = e.request.pathValue('testId')
  return e.json(200, { testId })
})

With auth middleware (≤ v0.22 mothership pattern):

routerAdd('PUT', '/api/instance/:id', (c) => {
  return require(`${__hooks}/mothership`).HandleInstanceUpdate(c)
}, $apis.requireRecordAuth())

Request body (≥ v0.23) — use e.bindBody() + DynamicModel, not JSON.parse(readerToString(e.request.body)):

let data = new DynamicModel({ trusted_ips: [] })
e.bindBody(data)
data = JSON.parse(JSON.stringify(data)) // required before destructuring / $common validators
const { trusted_ips } = data

Quick reads: e.requestInfo().body. Raw stream: readerToString(e.request.body) only for webhooks / signature verification.

Full guide: request-body.md (includes BadRequestError wrapping for client-visible validation errors). Official docs: Reading request body.

Request body (≤ v0.22):

const body = $apis.requestInfo(c).data

Clients call custom routes via pb.send() — see pocketbase-js-sdk.

Record operations

≥ v0.23 — direct $app methods:

routerAdd('PATCH', '/posts/{postId}', (e) => {
  const postId = e.request.pathValue('postId')
  let data = new DynamicModel({ status: '' })
  e.bindBody(data)
  data = JSON.parse(JSON.stringify(data))

  const record = $app.findRecordById('posts', postId)
  record.set('status', data.status)
  $app.save(record)

  return e.json(200, { record })
})

≤ v0.22 — go through $app.dao():

routerAdd('PATCH', '/posts/:postId', (c) => {
  const postId = c.pathParam('postId')
  const { status } = $apis.requestInfo(c).data

  const record = $app.dao().findRecordById('posts', postId)
  record.set('status', status)
  $app.dao().saveRecord(record)

  return c.json(200, { record })
})

Raw SQL when needed:

$app.db().newQuery('SELECT * FROM posts WHERE id = {:id}')
  .bind({ id: postId })
  .one()

External HTTP

Use synchronous $http.send():

const res = $http.send({
  url: 'https://api.example.com/webhook',
  method: 'POST',
  body: { email: record.get('email') },
  headers: { Authorization: 'Bearer ...' },
})

Environment variables

Only process.env is shimmed:

const value = process.env.MY_SECRET || ''

PocketHost injects env vars (e.g. ADMIN_SYNC in instance hooks).

Modules

// pb_hooks/utils.js
module.exports = {
  mkLog: (ns) => (...args) => console.log(`[${ns}]`, ...args),
}

// pb_hooks/main.pb.js
const { mkLog } = require(`${__hooks}/utils.js`)
const log = mkLog('main')

PocketHost specifics

• User hooks: upload to pb_hooks/ via FTP; changes restart the instance.
• Instance templates: packages/pockethost/src/instance-app/v22/ (≤ v0.22) and v23/ (≥ v0.23) — compare _ph_admin_sync.pb.js for a side-by-side API diff.
• Mothership hooks (≥ v0.23 / v0.39): packages/pockethost/src/mothership-app/pb_hooks/ — port guide in v023-upgrade.md. Source is src/lib/handlers/; see .cursor/rules/mothership-hooks.mdc
• Typings: instance-app/v22/types/types.d.ts (legacy instances); mothership-app/src/types/types.d.ts (control plane)
• PocketHost sandbox may restrict $os — avoid OS-level calls.

Mothership hook build boundary

Handlers compile with tsdown into pb_hooks/mothership.js and run in Goja, not Node.

1. Shared hook logic lives in packages/pockethost/src/common/ — must be JSVM-safe (sync, no Node/browser APIs).
2. Import via $common/<file> subpaths (tsconfig "$common/*": ["../common/*"]). Avoid runtime imports from the $common barrel.
3. After build, confirm no [UNRESOLVED_IMPORT] warnings — unresolved imports break validation silently at runtime.

// ✅ validateSshKey.ts — subpath bundles sshPublicKey.ts only
import { parseSshEd25519PublicKey } from '$common/sshPublicKey'

// ❌ tsdown won't resolve without tsconfig path
import { parseSshEd25519PublicKey } from 'pockethost/common'

// ❌ pulls unrelated common modules into pb_hooks
import { parseSshEd25519PublicKey } from '$common'

$app.store() concurrency

Concurrent hooks must not share live Goja objects via $app.store(). Use JSON string boundaries and setFunc for atomic read-modify-write. See app-store.md.

Examples

See hooks-examples.md for copy-paste patterns from this repo and PocketHost docs.

API reference

1. Pick the JSVM reference for the target version (see Version split above).
2. Cross-check generated typings — v22: instance-app/v22/types/types.d.ts; mothership: mothership-app/src/types/types.d.ts.
3. On a running instance, pb_data/types.d.ts matches that instance's PocketBase version.