Templates

A template is a working voidbase project somebody publishes so other people can start from it instead of from an empty directory. It stays in their repository under their licence; copying it gives you your own. Three ways to start from one, and one listing behind all of them.

From GitHub

Every listed template is a public GitHub repository with Use this template switched on, so starting is pressing that button and getting your own copy in your account. Browse them in the marketplace, and then follow the page for whichever shape it is: a voidbase project or a stack app.

From the CLI

voidbase init [dir] --template <name> takes a template the marketplace lists, and --template owner/name takes any public GitHub repository. The files of the default branch (or --ref) are downloaded from GitHub as a tarball and unpacked into the directory, which has to be empty or absent and defaults to the repository's name; nothing is cloned and no .git is left behind. The next steps are read from the template itself: bun install and its dev script for a package, voidbase serve for a PocketBase layout, bun install and bun run dev for a stack app.

voidbase templates                                   # what the marketplace lists: name, title, summary, repository
voidbase init --template voidbase-site               # a listed template, by name, into ./voidbase-site
voidbase init my-app --template acme/starter         # any public GitHub repository, into ./my-app
voidbase init my-app --template acme/starter --ref v2            # a branch or a tag instead of the default branch
voidbase templates --marketplace https://marketplace.example.com  # another marketplace's listing

voidbase templates, or voidbase init --template with no name, prints the listing. --marketplace <url> reads another marketplace's, and VOIDBASE_PLUGIN_MARKETPLACES applies here as it does for plugins. GitHub answers 404 for a private repository and a missing one alike, and the command says so.

From the cloud page

With GitHub connected, the cloud page offers a template when it creates an instance: the repository is created from it in your account in the same click and wired to the instance, so the instance deploys from a repository of your own and its plugins are commits. The same for an instance you already have, from its card.

Taking a template does not tie you to it. What you get is a repository, and from there it is an ordinary project: run it locally, make instances of it, or deploy it from a push.

The listing

One listing serves all three ways: registry/templates.json in the marketplace's repository, served to the CLI as the templates of the registry index, each entry a pointer at a repository with a title, a summary and the commit the audit read. A marketplace only lists templates; the repository is what you start from. The three listed first are real projects serving real traffic: the public demo as a voidbase project, and this site and the marketplace itself as stack apps.

What makes one worth publishing

A template is not a snippet and not a tutorial. Someone copies it, runs one command, and sees something working; anything short of that costs them more than starting fresh would.

my-template/
├─ pb_hooks/        or vb_hooks/ in a stack app: the behaviour someone inherits
├─ pb_migrations/   the collections, so the schema arrives with the code
├─ pb_secrets/      what has to be configured, declared with safe defaults
├─ README.md        what someone gets, and the first command to run
└─ LICENSE          so people know what they may do with it

The pieces that matter most are the least interesting ones. Migrations mean the schema arrives with the code instead of being a setup step. Declared secrets with defaults mean it runs before anything is configured. A README that says what someone gets is what makes the difference between a template and a repository.

Publishing yours

A submission is a GitHub issue, an automated audit reports on the repository before anyone decides, and a maintainer lists it. The seven checks it runs, and which four of them block, are on the publishing page.

One thing worth knowing before you spend time on it: turn on Template repository in your repository settings. Without it, Use this template does nothing; the CLI downloads the tarball and does not need it.