A working full-stack application and an engineering workflow for building the next one. Use GitHub’s Use this template → Create a new repository, then clone your new repository. Requires Bun 1.4.0 and Node 24 (for architecture and frontend lint tools).
bun install --frozen-lockfile
bunx playwright install chromium
bun run devOpen http://localhost:5173 and create an account with a passkey. Each account has private notes. Passkeys require localhost or HTTPS. Registration is open; decide your product’s onboarding policy before exposing a deployment. Accounts have no password or email recovery flow.
These are the defaults for applications built from this template. Extend the existing owner of a
responsibility before introducing another framework; discuss a replacement when a concrete product
requirement cannot fit the established approach. Package manifests and bun.lock own the versions.
| Framework or tool | What we use it for |
|---|---|
| Bun | Application runtime, workspace package management, scripts, tests, SQL access, and compilation into one executable. |
| TypeScript | Strict static typing across the backend, frontend, shared packages, and scripts. |
| Node.js | Runs the frontend ESLint and backend dependency checks during development and CI. |
| Elysia | HTTP routing, request and response schemas, boundary validation, and application composition. |
| Eden | Gives frontend API calls types derived directly from the Elysia application. |
| Elysia OpenAPI | Generates the API specification and interactive documentation from route schemas. |
| Better Auth and its passkey plugin | Account registration, WebAuthn passkey sign-in, and cookie sessions. |
| SQLite through Bun SQL | Stores application and authentication data in a local persistent database, with SQL migrations. |
| bun-sqlgen | Generates repository query result types from SQL and migrations; CI detects generated-type drift. |
| better-auth-bun-sql | Connects Better Auth to the application's Bun SQL database. |
| Framework or library | What we use it for |
|---|---|
| React and React DOM | Render the interface and manage transient component state. |
| Vite | Serves the frontend in development, proxies backend requests, and builds production assets. |
| TanStack Router | Owns file-based routes, navigation, guards, loaders, and typed URL state. |
| TanStack Query | Owns server data, query keys, caching, mutations, and invalidation. |
| TanStack Form | Owns form values, field validation, submission, and pending state. |
| Tailwind CSS | Styles layouts and components with utilities backed by shared semantic theme tokens. |
| Base UI | Provides accessible interaction primitives, including buttons and inputs. |
| shadcn/ui | Supplies the source-owned component conventions used by our shared Base UI primitives. |
| Class Variance Authority | Defines typed component variants, such as button size and appearance. |
| clsx and tailwind-merge | Compose conditional classes and resolve conflicting Tailwind utilities in the shared cn helper. |
| Fontsource | Bundles DM Sans and Geist Mono locally with the frontend. |
| tweakcn | Provides the Minimal Neutral theme whose tokens are checked into packages/ui. |
Zod is also included as an available schema-validation library, but the starter does not currently import it. Backend request validation uses Elysia schemas; add client schemas only for a concrete form or URL boundary, following the frontend guide.
| Tool | What we use it for |
|---|---|
| Bun test | Runs backend integration tests, frontend component tests, deployment tests, and compiled-binary checks. |
| React Testing Library and user-event | Test accessible component behavior through roles, labels, and realistic user interactions. |
| Happy DOM | Supplies the DOM environment for component tests running in Bun. |
| Playwright | Exercises real browser journeys and passkey ceremonies with disposable virtual authenticators. |
| Biome | Formats code and enforces general code-quality rules across the repository. |
| ESLint, TanStack Query rules, and shadcn lint | Enforce frontend query correctness and shared design-system conventions. |
| dependency-cruiser | Enforces backend layer boundaries and permitted dependency directions. |
| commitlint and Conventional Commits | Validate the commit and PR-title convention used by the delivery workflow. |
| Turborepo | Coordinates workspace tasks, dependency ordering, and caching. |
| GitHub Actions | Runs CI checks, builds and verifies the Linux binary, and uploads build and browser artifacts. |
| nibrun | Hosts the compiled application binary with HTTPS and persistent storage through the nib deployment CLI. |
apps/web/backend: Elysia, Eden types, Better Auth passkeys, Bun SQL/SQLite, generated SQL types. Models own domain rules, repositories own persistence, services own workflows, routes own transport.apps/web/frontend: React, Vite, TanStack Router/Query/Form, Tailwind, Base UI/shadcn primitives.packages/ui: shared primitives and semantic theme;packages/typescript-config: strict TypeScript.packages/build-tools: binary verification and explicit nibrun deployment targeting.packages/browser-testing: ephemeral virtual authenticators for real WebAuthn browser tests.AGENTS.mdand scoped guides: engineering judgment, ownership, trust, tests, and UI contracts..agents/skills: feature delivery, pull request creation, and nibrun deployment workflows.
The notes example demonstrates the complete vertical slice. Replace it with your product’s domain; retain the ownership, validation, query, authentication, and accessibility boundaries.
bun run dev:isolated:seeded # disposable database, real passkey signup, seeded through the UI
bun run fix:codestyle
bun run check:all
bun run test
bun run test:browser
bun run build # executable for this machine
bun run test:binarydev:isolated opens an unseeded browser. Both isolated modes use separate ports and temporary data,
and remove only their own data on shutdown. Browser checks cover registration, sign-in, session
changes, notes, and cross-account access. Screenshots go to ignored artifacts/.
After editing schema or repository SQL, run bun --filter @repo/web generate:queries and commit the
updated generated file. CI checks generation drift, types, formatting, frontend conventions,
backend dependency boundaries, tests, compiled Linux behavior, and the real browser journey.
This example button creates a deployment from the app binary in the rolling nibrun-latest
GitHub prerelease. After a push to main, the build workflow publishes it once the Linux binary
and browser checks pass. Pull requests only build and test; publishing uses GitHub's built-in
token and needs no nibrun credentials. The release notes and tag identify the source commit.
When creating a repository from this template, change the button's name and URL-encoded
binary URL to your app name and repository, keeping /releases/download/nibrun-latest/app.
You can then move the button to the top of your README.
Wait for the first successful main build to publish the asset before using the button.
The binary URL must be publicly accessible; private repositories can use the CLI instead.
For CLI deployments, install nib using https://nibrun.com/install.sh and run nib login yourself. Then:
bun run deploy --new my-app
bun run deploy --app exact-existing-slugThe deploy command builds for Linux x64 and embeds the frontend and SQL migrations into
apps/web/dist/app. bun run build:linux produces the same binary without deploying it.
CI uploads the verified executable as nibrun-binary; no deployment credentials are required in CI.
The server honors PORT, listens on 0.0.0.0, derives HTTPS origin from NIBRUN_HOSTNAME, and stores
SQLite and its generated private auth secret inside /app/data. Optional BASE_URL supports a
custom domain; keep the original nibrun hostname stable for existing passkeys. DATA_FOLDER and
BETTER_AUTH_SECRET can be overridden. Local defaults need no .env file; see apps/web/.env.example.
nibrun is a single VM with local persistent storage. Redeployments briefly interrupt service. Export and verify backups before changes to persistent data; exporting is not an automatic backup schedule. Follow the deployment skill and compatibility policy.
Use ship-change for feature work and open-pull-request for reviewed Conventional Commit PRs. The bootstrap application is deliberately generic; do not add a product’s integrations to the template unless they represent a demonstrated reusable need. Preserve new lessons as executable checks where possible and scoped guidance only when judgment is required.
Template generation copies a snapshot. Updates here do not automatically update repositories already created from it. Adopt later improvements through focused PRs in each consuming repository, reviewing its deployed data and local decisions. Do not overwrite a consumer’s engineering guides blindly.
Configure GitHub rulesets to require checks:required, build:required, browser:required, and
check-pr-title:required before merging, when supported by the repository’s account plan. Rulesets,
secrets, and environments are GitHub settings and are not copied by Use this template.