@vitibase/server

Server-side utilities for Vitibase — authentication, client creation and context injection for the API routes your application serves.

npm install @vitibase/server

import { withVitibase } from '@vitibase/server'

export default {
  fetch: withVitibase({ auth: 'user' }, async (req, ctx) => {
    const { data } = await ctx.supabase.from('orders').select('id, total')
    return Response.json({ user: ctx.userClaims?.sub, orders: data })
  }),
}

# .env — a project ref and two keys is a complete configuration
VITIBASE_PROJECT_REF=abcdefghijklmnopqrst
VITIBASE_ANON_KEY=eyJ...
VITIBASE_SERVICE_ROLE_KEY=eyJ...

What it reads

| Variable | Meaning | | ---------------------------------------------------- | ------------------------------------------------------ | | VITIBASE_PROJECT_REF | Your project ref. The URL and key set URL come from it | | VITIBASE_URL | A full project URL, if it is not on vitibase.in | | VITIBASE_ANON_KEY / VITIBASE_PUBLISHABLE_KEY | The key browsers use | | VITIBASE_SERVICE_ROLE_KEY / VITIBASE_SECRET_KEY | The key your server uses | | VITIBASE_PUBLISHABLE_KEYS / VITIBASE_SECRET_KEYS | A JSON object of named keys, for more than one | | VITIBASE_JWKS_URL / VITIBASE_JWKS | Only if you are not using the project's published set |

The key set URL is derived from the project, so you rarely set it: every Vitibase project publishes its public signing key at /auth/v1/.well-known/jwks.json, and that endpoint is reachable without an API key because the libraries that fetch it cannot send one.

Anything you pass in config.env wins over the environment, field by field.

Verifying a user, which needs asymmetric keys

auth: 'user' verifies an end user's access token against your project's published key set — no shared secret on your server. That works because Vitibase projects sign user tokens with an ES256 key and publish the public half; a project created before that needs migrating once (POST /platform/projects/{ref}/jwt-keys from the dashboard's API, Administrator only).

auth: 'publishable' and auth: 'secret' check API keys and work on any project.

The context keys keep their upstream names

ctx.supabase, ctx.supabaseAdmin, ctx.userClaims and ctx.jwtClaims are what the library sets, and this package does not rename them. A wrapper that renamed the keys in its documentation but not in the object would hand you undefined at runtime, which is a worse trade than a familiar name in your handler.

Everything else

Every entry point of the library underneath is re-exported at the matching path:

import { withVitibase } from '@vitibase/server/adapters/hono'
import { withPostgresClient } from '@vitibase/server/middleware/postgres'
import { resolveEnv } from '@vitibase/server/core'

The adapters (Hono, H3, Elysia, NestJS) and the Postgres middleware need their own framework installed — they are optional peers, so you only get what you use.

What this package is

A thin layer over @supabase/server, which it re-exports in full. What it adds is the part a rename could not: this platform's variable names, and a project ref that becomes both a URL and a key set URL. withSupabase and every other upstream export are still exported under their original names, so an existing codebase changes one import line.

Licence and attribution

Apache-2.0. Depends on @supabase/server, copyright Supabase, Inc. Supabase is a trademark of Supabase, Inc., which does not endorse Vitibase.