Start a stack app

One application: pages, typed endpoints, background jobs and a database, which builds into a voidbase instance and deploys as a single Worker serving the site, the API and the admin panel from one address.

It is a Void app with an adapter added. The project stays a plain Void app the whole way through: the adapter generates the voidbase instance from it rather than asking you to keep one.

From an empty directory

mkdir my-app && cd my-app
bun add void && bunx void init          # scaffolds a Void app: pages/, routes/, db/, vite.config.ts
bun add @voidbase-cloud/voidbase

Then add the adapter to the Vite config, which is the only wiring there is. A framework plugin such as voidReact() sits beside it when void init picked one:

// vite.config.ts
import { defineConfig } from "vite";
import { voidPlugin } from "void";
import { voidbaseAdapter } from "@voidbase-cloud/voidbase/adapter/plugin";

export default defineConfig({ plugins: [voidPlugin(), voidbaseAdapter()] });

And ignore the two things that should never be committed: the generated instance, and the local values of your configuration.

.voidbase/
vb_secrets/secrets.json

What the project looks like

Everything above the gap is Void's and means what Void means by it. The three directories below it are the ones the adapter adds, each named for the voidbase thing it is, each optional, and each with its own page:

Build and run it

bun run build                                  # or: bunx --bun vite build, or: bunx voidbase adapt
bun .voidbase/main.ts --http 127.0.0.1:8090    # site at /, API at /api, panel at /_/

The build writes a complete voidbase project into .voidbase/: your pages as its static files, your routes, middleware, hooks, crons and queues compiled into its hook bundle, your collections as its migrations, your declaration as its pb_secrets. It is git-ignored, because it is output, and it is an ordinary instance in every other respect. Build with Bun: voidbase ships TypeScript sources and Vite loads its config through the runtime.

A route that reads or writes collections imports pb, authOf and requireAuth from @voidbase-cloud/voidbase/adapter; a route on one of voidbase's own paths (/api/collections, /api/files, /api/realtime and the rest) never runs, and the build warns and names it.

Deploy it

cd .voidbase && voidbase deploy      # the generated instance, like any project
voidbase sync                        # or from the root: builds, deploys, connects the repository

Everything on the project page applies from here: the same token and the same deploy. sync knows this layout by its vb_ directories and deploys from what the build generated. To have a push do it instead, so the site and its backend ship together on every commit, Deploy on every push is two commands and one dashboard step.

An installable app

The pwa option writes what an installable app needs from what the app already declares in void.json: the manifest, the icons resized from one file, and a service worker that precaches the shell and the hashed assets under a version hashed from those files, never touching /api or the panel. @voidbase-cloud/sdk/pwa registers it and shows the update prompt.

voidbaseAdapter({ pwa: { icon: "icon.svg" } })   // manifest.webmanifest, the icon set and sw.js into pb_public

voidbase update

Two things that are different

Two databases, on purpose. Void's db/ is your application's own tables, in Drizzle, typed end to end, for the data your code owns. Collections are for the data the admin panel and the SDK own, with API rules and a schema someone can change without a deploy. Both live in the same D1, most apps want both, and vb_migrations is where the second kind is written down.

Routes and hooks are not the same thing. A route in routes/ is an endpoint you call. A hook in vb_hooks runs because a record changed, whoever changed it, including someone clicking in the admin panel. Reach for the first when you are writing an API, the second when a rule has to hold no matter who is writing.

voidbase templates                                              # what the marketplace lists
voidbase init blog-api --template voidbase-site                 # by listed name
voidbase init blog-api --template voidbase-cloud/voidbase-demo  # any public repository, at its default branch
voidbase init blog-api --template acme/starter --ref v2         # at a branch or tag
voidbase init blog-api --template starter --marketplace https://templates.acme.internal   # another listing

bun add void && bunx void init && bun add @voidbase-cloud/voidbase

voidbase plugins add echo         # writes pb_plugins/echo and the lock entry, at the project root
git add pb_plugins voidbase.lock  # the build carries both into the generated app
bun run build && cd .voidbase && voidbase deploy   # or push, if a pipeline deploys