Introduction
VitNode is a plugin-based framework for community apps - a TanStack Start front end, a Hono API, Postgres, and an AdminCP you do not have to build.
VitNode gives you the parts of an application nobody enjoys writing twice: accounts, roles, sessions, staff permissions, uploads, search, an admin panel and a content layer - already built, already migrated, already translated. Your own features arrive as plugins that claim URLs, database tables, API routes and AdminCP screens as first-class citizens rather than as bolted-on extras.
Underneath it is an ordinary modern stack: a TanStack Start front end on Vite and React 19, a Hono API that owns every security decision, and Drizzle over Postgres.
You are reading the canary docs
These pages track the canary line (VitNode 2.0), which moves quickly. If a
page and the code disagree, the code wins - and a
contribution fixing the page is very welcome.
Quick start
bun create vitnode-app@canarypnpm create vitnode-app@canarynpx create-vitnode-app@canaryThe CLI asks which shape you want - Single App (a TanStack Start app with the
Hono API mounted inside it at /api), Monorepo App (front end and API served
separately) or Only API - then scaffolds it, generates your first migration
and, if you let it, installs everything. The full walkthrough, including the
first sign-in, is in Getting started.
What you need
| Software | Minimum | Recommended | What it is for |
|---|---|---|---|
| Node.js | 22 | 24 | Runs the Hono API, the Vite dev server and the built Nitro server. |
| Postgres | 17 | 17.5 | Every table VitNode has: users, roles, sessions, languages, files, content, search. |
| pnpm | 11 | 11.9 | Installing packages and running scripts - the manager this repository pins. |
| bun or npm | – | – | Fully supported alternatives; the CLI writes whichever you pick. |
Where those numbers come from, so you can check them: engines.node in the root
package.json says >=22, .nvmrc says 22, and CI builds on Node 24 with
pnpm@11.9.0 (the version pinned by packageManager). Numbers we can point at
beat numbers that merely sound reassuring, which is why bun and npm have none -
nothing in the repository pins them, and create-vitnode-app records whichever
release you already have.
Why the table says 17
Every migration in this repository was generated against Postgres 17. The
bundled docker-compose.yml does not pull the stock image, though - it builds
docker/postgres/Dockerfile, which is postgres:17.5-alpine plus a hunspell
Polish dictionary and a registered polish text-search configuration, because
the stock image ships neither and Postgres full-text search is the default
search engine. Older majors are untested rather than
known-broken.
Optional services
None of these are required to run VitNode. Each one turns on a capability, and each one is a small block of config away.
| Service | Package | What it adds |
|---|---|---|
| Redis 8 | built in | A shared cache on c.get("cache"), cached session lookups, and a rate limiter that holds across instances. |
| Docker | – | Postgres and Redis locally with one docker:dev, using the compose file the CLI writes for you. |
| Elasticsearch 9 | @vitnode/elasticsearch | Moves search off Postgres full-text, which is the default engine. |
| SMTP | @vitnode/nodemailer | Transactional email through any SMTP server. |
| Resend | @vitnode/resend | Transactional email through Resend's API instead. |
| S3 or Cloudflare R2 | @vitnode/s3 | File uploads in object storage instead of on the API's disk. |
| Supabase | @vitnode/supabase-storage | Uploads in Supabase buckets - and a managed Postgres to aim POSTGRES_URL at. |
| node-cron | @vitnode/node-cron | Runs scheduled tasks in-process, without an external scheduler. |
| Captcha | built in | Cloudflare Turnstile or reCAPTCHA v3 on sign-up and password reset. |
| SSO | built in | Sign in with Discord, Google or Facebook. |
| AI | built in | Model access through the Vercel AI SDK registry on c.get("ai"). |
How this section is organised
The sidebar has five groups, and they run roughly in the order you will need them:
| Group | What lives there |
|---|---|
| Start here | Installing, plugin creation, deployment and shape of an app: Getting started, Create a plugin, Deployments, Architecture. |
| Framework | The TanStack Start runtime: Routing, Data loading, Fetcher, Cache, Database, i18n. |
| Extend VitNode | Your own features: Content Engine, Roles, Events. |
| Services | Things VitNode talks to: Search, Storage, Email, Cron, WebSocket, Redis. |
| Operate | Keeping it running smoothly: Debugging, Swagger, Contribution. |
Where to go next
Create a plugin
The VitNode way: build features as installable plugins
Getting started
From the CLI to your first admin sign-in
Deployments
Take your VitNode app live with self-hosted or cloud configs
Architecture
Where TanStack Start, TanStack Query and Hono meet
Routing
Plugin route manifests, shells and route modules
Content Engine
Declare a content type, get the CRUD and AdminCP for free