Use Voltbase with Next.js

Create a Voltbase project, add sample data, and query it from a Next.js App Router app.

1. Create a Voltbase project

Sign up or sign in
Create an organization and a project
Open API and copy the Project URL, anon key, and (for server-only writes) the service role key

You can also create projects from the dashboard after signing in — no CLI required for this quickstart.

2. Set up your database

In the dashboard, open Database and create a instruments table (or run SQL):

schema.sql

create table instruments (
  id bigint generated always as identity primary key,
  name text not null
);

insert into instruments (name)
values ('violin'), ('viola'), ('cello');

alter table instruments enable row level security;

create policy "public read"
on instruments for select
to anon
using (true);

Why RLS?

With a public SELECT policy for anon, the browser anon key can read rows. Writes still need auth policies or the service role on the server.

3. Create a Next.js app

terminal

npx create-next-app@latest voltbase-nextjs --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"
cd voltbase-nextjs

Use the App Router so you can query from Server Components with the anon key.

4. Declare environment variables

Create .env.local at the project root and paste your dashboard values:

.env.local

NEXT_PUBLIC_VOLTBASE_URL=https://YOUR_API/api/projects/YOUR_SLUG
NEXT_PUBLIC_VOLTBASE_ANON_KEY=your-anon-key

NEXT_PUBLIC_ vars are available in the browser and on the server. Add a non-public service role var only if you need writes from Route Handlers or Server Actions.

Keep the service role server-only

Never put the service role key in client bundles. Use the anon key in the browser; use the service role only in server routes, Server Components, or backend jobs.

5. Create a Voltbase client

Install the SDK, then add a small helper:

terminal

npm install voltbase-js

src/lib/voltbase.ts

import { createClient } from 'voltbase-js';

export function createVoltbaseClient() {
  return createClient(
    process.env.NEXT_PUBLIC_VOLTBASE_URL!,
    process.env.NEXT_PUBLIC_VOLTBASE_ANON_KEY!,
  );
}

6. Query Voltbase from Next.js

Add a Server Component page that selects from instruments:

src/app/instruments/page.tsx

import { createVoltbaseClient } from '@/lib/voltbase';

export default async function InstrumentsPage() {
  const voltbase = createVoltbaseClient();
  const { data: instruments, error } = await voltbase
    .from('instruments')
    .select('id, name')
    .order('id', 'asc');

  if (error) {
    return <p>Failed to load: {error.message}</p>;
  }

  return (
    <ul>
      {(instruments ?? []).map((row) => (
        <li key={row.id}>{row.name}</li>
      ))}
    </ul>
  );
}

Next: Auth, Realtime, or the Todo + RLS example.