Public API

context

import { context } from "@budibase/backend-core"

context.doInTenant(tenantId: string, task: () => Promise<T>): Promise<T>
context.getTenantId(): string
context.getAppId(): string | undefined
context.doInAppContext(appId: string, task: () => Promise<T>): Promise<T>

Wraps execution in an async-local-storage scope that carries tenant and app identity. Use it at the top of every request handler so that all downstream calls (db, cache, etc.) automatically resolve to the correct tenant/app without passing context explicitly.

auth

import { auth } from "@budibase/backend-core"

auth.buildAuthMiddleware(
  strategies: string[],
  opts?: { publicAllowed?: boolean }
): Koa.Middleware

auth.authenticate(ctx: Koa.Context): Promise<void>

Provides Koa-compatible JWT and cookie-based authentication middleware. Use buildAuthMiddleware as a route-level or global middleware; it populates ctx.user with the authenticated user object or throws a 401.

cache

import { cache } from "@budibase/backend-core"

// Generic cache operations
cache.get(key: string): Promise<any>
cache.store(key: string, value: any, ttl?: number): Promise<void>
cache.delete(key: string): Promise<void>

// User cache
cache.user.getUser(userId: string): Promise<User | null>
cache.user.invalidateUser(userId: string): Promise<void>

// Invite cache
cache.invite.getInvite(code: string): Promise<Invite | null>
cache.invite.saveInvite(code: string, invite: Invite): Promise<void>

Thin wrappers over Redis for common Budibase data types. Prefer cache.user.* over raw cache.get when working with user objects to benefit from built-in serialization and invalidation logic.

db

import { db } from "@budibase/backend-core"

db.getDB(dbName: string): PouchDB.Database
db.dbExists(dbName: string): Promise<boolean>
db.init(): void

Abstracts PouchDB/CouchDB access. Call db.init() once at startup. Use db.getDB to obtain a database handle scoped to the current context.

security / permissions

import { permissions, roles } from "@budibase/backend-core"

permissions.checkPermission(
  userRole: string,
  resource: string,
  level: string
): boolean

roles.getRole(roleId: string): Promise<Role>

Role-based access control primitives. Use checkPermission inside route guards to assert that the current user has sufficient privilege before executing business logic.

Working examples

Scenario - Multi-tenant request handler

Wrapping an Express-style handler in a Budibase tenant context so that all downstream db/cache calls resolve correctly.

import Koa from "koa"
import Router from "koa-router"
import { context, db, env } from "@budibase/backend-core"
import dotenv from "dotenv"

dotenv.config()
db.init()

const app = new Koa()
const router = new Router()

router.get("/api/data", async (ctx) => {
  const tenantId = ctx.headers["x-budibase-tenant"] as string ?? "default"

  await context.doInTenant(tenantId, async () => {
    const database = db.getDB(`${tenantId}_myapp`)
    const result = await database.allDocs({ include_docs: true })
    ctx.body = result.rows.map((r) => r.doc)
  })
})

app.use(router.routes())
app.listen(3000)

Scenario - User session validation

Validating an inbound JWT and retrieving the cached user profile.

import { auth, cache, context } from "@budibase/backend-core"
import Koa from "koa"

const app = new Koa()

// Apply auth middleware globally
app.use(auth.buildAuthMiddleware([], { publicAllowed: false }))

app.use(async (ctx) => {
  // ctx.user is now populated by the auth middleware
  const userId: string = (ctx as any).user._id

  await context.doInTenant((ctx as any).user.tenantId, async () => {
    // Attempt cache hit before going to DB
    const cachedUser = await cache.user.getUser(userId)

    if (cachedUser) {
      ctx.body = { source: "cache", user: cachedUser }
    } else {
      ctx.body = { source: "db", userId }
    }
  })
})

app.listen(3001)

Scenario - Cache-backed invite flow

Storing and retrieving an invite code using the invite cache module.

import { cache, context } from "@budibase/backend-core"
import { v4 as uuidv4 } from "uuid"

async function createInvite(email: string, tenantId: string): Promise<string> {
  const code = uuidv4()
  await context.doInTenant(tenantId, async () => {
    await cache.invite.saveInvite(code, {
      email,
      tenantId,
      createdAt: Date.now(),
    } as any)
  })
  return code
}

async function redeemInvite(code: string, tenantId: string) {
  return context.doInTenant(tenantId, async () => {
    const invite = await cache.invite.getInvite(code)
    if (!invite) throw new Error("Invite not found or expired")
    return invite
  })
}

// Usage
;(async () => {
  const code = await createInvite("user@example.com", "acme")
  console.log("Invite code:", code)
  const invite = await redeemInvite(code, "acme")
  console.log("Redeemed:", invite)
})()

File walkthrough

• backend-core/ - The primary library; all backend primitives live here. Entry point is src/index.ts.
• backend-core/src/auth/ - JWT and cookie authentication, session creation, and token verification.
• backend-core/src/cache/ - Redis-backed cache helpers for users, invites, password resets, and generic key-value.
• backend-core/src/context/ - Async-local-storage context providing tenant/app scope to the entire call stack.
• backend-core/src/db/ - PouchDB/CouchDB abstraction layer; database initialization and access helpers.
• backend-core/src/security/ - Roles, permissions, sessions, and encryption utilities.
• backend-core/src/middleware/ - Koa middleware: error handling, auth, audit logging.
• backend-core/src/objectStore/ - S3-compatible object storage client wrappers.
• backend-core/src/redis/ - Raw Redis client (RedisClient) and distributed lock implementation (redlockImpl).
• backend-core/src/events/ - Internal event bus for audit and analytics events.
• backend-core/src/errors/ - Typed error classes (exported directly from the package root).
• backend-core/src/constants/ - Shared string constants for DB names, roles, and misc values.
• backend-core/src/docIds/ - Helpers for generating and parsing Budibase document ID formats.
• backend-core/src/tenancy/ - Tenant lookup and management (re-exported via the tenancy compatibility shim).
• backend-core/src/utils/ - General utilities including Duration helpers.
• backend-core/src/environment.ts - Typed environment variable access; use env rather than process.env directly.
• bbui/ - Svelte component library; not required for backend-only integrations.
• server/ - Full Budibase API server; reference for route and middleware composition patterns.
• worker/ - Background job processing service using Bull queues.
• shared-core/ - Pure utility functions shared between frontend and backend.
• string-templates/ - Handlebars template engine used in automations and bindings.
• types/ - Central TypeScript type definitions referenced across all packages.

Common pitfalls and fixes

• Missing NODE_ENV: Many guards branch on NODE_ENV=production; omitting it enables test/mock paths silently. Always set it explicitly.
• Redis connection not established: cache.* and locks.* throw ECONNREFUSED if Redis is not running before the first call. Ensure Redis is up and REDIS_URL/REDIS_PASSWORD are set before importing cache modules.
• CouchDB not initialized: Calling db.getDB before db.init() throws or returns a broken client. Always call db.init() at application startup.
• Tenant context missing: Calling context.getTenantId() outside a doInTenant block throws No tenant ID found. Wrap every request handler with context.doInTenant.
• ESM/CJS interop: backend-core ships CommonJS. If your project uses "type": "module", add "moduleResolution": "node16" and import via createRequire or set "esModuleInterop": true in tsconfig.
• PouchDB native modules: pouchdb-find requires leveldown which has a native addon. Run npm rebuild leveldown if you see MODULE_NOT_FOUND errors after changing Node versions.

Vibe-coding prompt template

I have copied the Budibase backend-core source into my project at `libs/backend-core/`
and have a USAGE.md at the project root describing all public exports and setup steps.

The upstream package is `budibase_budibase` (backend domain), packages subtree.

Please help me integrate backend-core into my existing Express/Koa TypeScript project by:

1. Reading USAGE.md and source/backend-core/src/index.ts to understand every top-level export.
2. Adding the correct tsconfig path aliases for `@budibase/backend-core` and `@budibase/types`.
3. Creating an `src/lib/budibase.ts` initialisation module that loads dotenv, calls db.init(),
   and exports a configured Koa middleware stack using auth and middleware exports.
4. Showing me how to wrap my existing route handlers with context.doInTenant so that
   cache and db calls resolve correctly for multi-tenant use.
5. Adding a /health endpoint that checks Redis connectivity via the cache module.
6. Pointing out any missing environment variables based on backend-core/src/environment.ts.

Work step by step, show all imports using the real symbol names from USAGE.md,
and do not invent any APIs that are not listed there.

License and credit

The upstream license is defined in source/backend-core/LICENSE (see that file in the source tree; the Budibase repository uses the GPL-3.0 license for community edition code and a proprietary license for pro/enterprise modules - verify the specific file before distribution).

Upstream project: Budibase on GitHub. The backend-core package is maintained by the Budibase core team.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.