Couchbase Capella Starter with Next.js

Couchbase Capella Starter with Next.js is an open-source quickstart from the Couchbase examples organization that demonstrates a working create-read-update-delete (CRUD) application for user profiles, with a Next.js front end and a Couchbase Capella or Couchbase 7+ database as the data store.

What is Couchbase Capella Starter with Next.js?

It is a deployable sample application, not a theme: it ships a Next.js UI plus the backend code needed to read and write user profile documents in Couchbase. You supply database credentials through environment variables (CB_USERNAME, CB_PASSWORD, CB_CONNECT_STRING, CB_BUCKET), and the app returns a running profile manager where you can create, update, and delete records. It runs locally on Node.js 24 LTS at localhost:3000, or on Vercel via a one-click clone-and-deploy link that opens the Couchbase Capella integration flow to pick database resources. The code is maintained by Couchbase under the couchbase-examples GitHub organization.

What makes it stand out?

• Next.js full stack — one project serves both the front-end profile UI and the API/fetch layer, with fetch URLs built from a dynamic origin instead of a hard-coded localhost address.
• Tailwind CSS styling — the interface is styled with Tailwind utility classes.
• Couchbase Capella integration — a Vercel integration ID wires the deployment to Capella and lets you create a free database during the deploy flow.
• Local Couchbase 7+ support — point CB_CONNECT_STRING at couchbase://localhost for a local or Docker database.
• Seeded sample data — a MOCK_DATA.json file holds 15 mocked user documents; npm run load-sample-data inserts them, and the build step also attempts to create the collection and load data.
• Setup scripts — npm run init-db:local, npm run build-indexes, and npm run init-db:default create the bucket, collection, and required indices.
• Integration tests — a test suite runs with npm test after database setup.
• GitPod and CI support — a .env.default file keeps testing and GitPod instances working, and build scripts have :no-env variants for Vercel-style system environment injection.

Who should use Couchbase Capella Starter with Next.js?

• Next.js developers evaluating Couchbase: get a runnable CRUD reference before committing to the SDK.
• Backend engineers learning Capella: see how bucket, scope, collection, and index setup map to real application code.
• Vercel users: deploy a database-backed app without configuring hosting manually.
• Tutorial followers: run the same code in GitPod or locally with the seeded sample data.

What can you do with Couchbase Capella Starter with Next.js?

• Ship a working profile manager: deploy to Vercel and immediately create, update, and delete user profile documents.
• Bootstrap a new project: fork the repository and replace the profile schema with your own documents.
• Test against a local database: run Couchbase in Docker and use npm run init-db:local plus npm run load-sample-data.
• Study index creation: use npm run build-indexes to see which indices a query needs on Capella.

How does it work?

On Vercel you click the Deploy link, follow the integration prompts to select Capella resources, then explore the deployed app. Locally you clone the repo, run npm install, copy .env.local.example to .env.local and fill in the credentials, create the bucket and collection, run the setup scripts, and start with npm run dev.

FAQ

What bucket and collection does this starter need?

It expects a bucket named user_profile and, inside the _default scope, a collection named profile. On Capella you create both manually before running npm run build-indexes, because the initialization script only provisions these automatically for local databases.

Why do I get "Query failed: bucket not found" or an infinite loading state?

That error means no data is being returned from the database. Check that CB_BUCKET names the right bucket, that the scope is _default, and that a collection named profile exists.

What causes a 504 Gateway Timeout after deploying?

It usually means the app cannot reach the database. Verify the environment variables, allow the client IP addresses, confirm the database user credentials match, and check whether the database was deleted.

Can I run this outside Vercel?

Yes. The Vercel deployment steps are Vercel-specific, so other platforms should adapt the local run instructions instead, using the package.json build scripts that are not postfixed with :no-env.

What runtime does it require?

Running locally needs Node.js 24 LTS with npm, a Couchbase Capella database or a local Couchbase 7+ instance, and a code editor.

Pricing

The starter code is free and open source, and the Vercel integration flow lets you sign up for a free Couchbase Capella database if you do not already have one.

Alternatives

Supabase offers a Next.js quickstart template that pairs the same framework with a Postgres backend instead.