Silverbulletbeta
Back to Getting Started
Getting Started

Create your first Silverbullet project

Updated August 22nd, 202633 views

Silverbullet is a full-stack TypeScript boilerplate. Instead of copying files by hand, you scaffold a new project from the template with a single script, then fill in your own credentials.

Scaffold the project

Run this from the directory where the project should live — for example ~/Projects:

Bash 
sh sb/scripts/new-project.sh <name>

The script does the whole setup for you:

  • Clones the template into <name>/ and wires the original repo as upstream, with pushing disabled.

  • Copies apps/client to apps/<name>-client, renaming its package and Wrangler names.

  • Copies example.env to .env.

  • Installs dependencies, creates the first commit, and creates and pushes a private GitHub repository via the gh CLI.

The template's own apps/client is left untouched. That is deliberate — keeping it pristine is what makes future updates from the template merge cleanly.

Fill in your environment

Configuration lives in the root .env, copied from example.env. Edit that one file: pnpm install runs a postinstall script that regenerates apps/api/.env, apps/cron/.env, and apps/queue/.env from it. Those copies carry a "DO NOT EDIT" header and are overwritten on every install, so never edit them directly.

Per-environment templates are also provided: staging.env, production.env, and test.env.

Before your first run you will need connection details for at least Postgres and Redis. A full app also expects MailerSend, S3, Google and Apple OAuth clients, Paddle, OpenAI, and a generated BETTER_AUTH_SECRET.

Set up the database

The schema is defined in code with Drizzle. Apply it to your fresh database:

Bash 
pnpm --filter=@repo/drizzle db:migrate
pnpm --filter=@repo/drizzle db:seed

The seed step is optional and only needed if you want starter data.

Run the apps

There are no per-app scripts in the root package.json. Run each app through its own workspace filter:

Bash 
pnpm --filter=<name>-client dev
pnpm --filter=api dev
pnpm --filter=queue dev
pnpm --filter=cron dev

The client runs on http://localhost:3000. For everyday feature work the client and API are usually enough — start the queue and cron apps when you are working on background jobs or scheduled tasks.

Check your work

Two commands cover most of it:

Bash 
pnpm lint
pnpm test

Linting is enforced by a pre-commit hook, so a commit will be blocked until it passes.

Next steps

  • Read How the monorepo is organized to learn where your code belongs.

  • Read Pull template updates into your project before your first update, so your migrations and client survive it.