Skip to content

Quick Start: create-centrali-app

Scaffold a Centrali-powered app with one command.

Prerequisites

Create Your App

npx @centrali-io/create-centrali-app my-app

You'll be prompted to choose:

  • Template: SaaS Starter, API Starter, Jobs Starter, React + Vite, or Next.js
  • TypeScript: Yes (default) or No

Pass flags to skip the prompts:

# Next.js (TypeScript) — fully non-interactive
npx @centrali-io/create-centrali-app my-app --template=nextjs --typescript

# React + Vite
npx @centrali-io/create-centrali-app my-app --template=react-vite --typescript

# JavaScript instead of TypeScript
npx @centrali-io/create-centrali-app my-app --template=react-vite --no-typescript

Add --typescript for a non-interactive run

A project name and --template= alone still leave the TypeScript toggle to prompt. Add --typescript (or --yes) when scripting or running in CI.

Which credential do I need?

Centrali credentials are not interchangeable, and this is the most common first-run problem. Pick the one your template uses:

Credential Where it runs Can it create a collection?
Service account (CENTRALI_CLIENT_ID + CENTRALI_CLIENT_SECRET) Server only Yes
Publishable key (NEXT_PUBLIC_CENTRALI_PK / VITE_CENTRALI_PK) Safe in the browser No

A publishable key can read collections and — with an explicit per-slug scope — create records. It cannot create a collection: the platform rejects every non-GET /collections request made with a publishable key. Anything that provisions a schema needs a service account.

Never prefix a secret with NEXT_PUBLIC_ or VITE_

Those values are inlined into your JavaScript bundle at build time and served to every visitor. A service account client secret must only ever be read on the server.

Where to get them

  • Publishable key: Console → ACCESS → Publishable Keys → Create Key. Select which collections and actions the key can access.
  • Service account: Console → ACCESS → Service Accounts. Create one, then add it to the workspace_developers group (or a custom group with the required permissions) so it is permitted to create collections. Being able to obtain a token does not by itself grant access to a resource.

Configure Environment

The fastest way to set up your environment variables:

cd my-app
npx @centrali-io/create-centrali-app env

This detects which template you generated, prompts only for the variables that template actually reads, and writes .env.local. Secrets are entered hidden and masked on screen.

Or configure manually — copy .env.example to .env.local and fill in your values:

This template uses a single server-side credential path. There are no NEXT_PUBLIC_ Centrali variables to set.

CENTRALI_API_URL=https://centrali.io
CENTRALI_WORKSPACE=your-workspace-slug
CENTRALI_CLIENT_ID=sa_your_client_id
CENTRALI_CLIENT_SECRET=sk_your_client_secret

VITE_CENTRALI_API_URL=https://centrali.io
VITE_CENTRALI_WORKSPACE=your-workspace-slug
VITE_CENTRALI_PK=pk_live_your_publishable_key

These use a service account on the server and a publishable key in the browser.

# Server-side (API routes and server components only)
CENTRALI_API_URL=https://centrali.io
CENTRALI_WORKSPACE=your-workspace-slug
CENTRALI_CLIENT_ID=sa_your_client_id
CENTRALI_CLIENT_SECRET=sk_your_client_secret

# Client-side (safe for browser)
NEXT_PUBLIC_CENTRALI_API_URL=https://centrali.io
NEXT_PUBLIC_CENTRALI_WORKSPACE=your-workspace-slug
NEXT_PUBLIC_CENTRALI_PK=pk_live_your_publishable_key

CENTRALI_WORKSPACE is the workspace slug

Use the slug from Console → Settings, not the display name. Set CENTRALI_API_URL to the root domain (https://centrali.io) — the SDK derives api.centrali.io itself.

Create the collection

The nextjs, api, jobs and saas templates ship a setup script that creates the collections and sample data they expect. Run it once:

npm install
npm run setup

This is what makes a brand-new workspace work — these templates do not assume a collection already exists.

Run

npm run dev

Your app starts at http://localhost:3000 (Next.js-based templates) or http://localhost:5173 (React + Vite).

Templates

Template Stack Credentials npm run setup
nextjs Next.js 16 + TailwindCSS 4 Service account (server only) yes
api Next.js 16, REST CRUD + explorer Service account + publishable key yes
jobs Next.js 16, functions + triggers + dashboard Service account + publishable key yes
saas Next.js 16 + Clerk, multi-tenant Clerk + service account yes
react-vite React 19 + Vite + TailwindCSS 4 Publishable key (browser) no

Next.js template

  • Next.js 16 App Router + TailwindCSS 4
  • One credential path: a server-side service account, used by both server components and route handlers
  • / lists collections; /collections/[slug] lists that collection's records
  • Forms post to API routes (/api/collections, /api/records), which call Centrali server-side
  • Pages opt out of static prerendering, so credentials are read per request

React + Vite template

  • React 19 + Vite + TailwindCSS 4
  • Browser-only SDK usage with a publishable key
  • Single page with state-based navigation
  • Reads collections and creates records within the key's scopes; it cannot create a collection

Before you deploy

The example API routes have no application-level access control

The route handlers in these templates hold service account credentials and do not check who is calling them. Deployed on a public URL as-is, anyone who finds them can read and write your workspace. Before exposing one:

  1. Add your own authentication and authorization to the route handlers.
  2. Use a separate service account and workspace for production.
  3. Decide deliberately what the browser may do, using a publishable key with explicit per-slug scopes.

A successful deploy is not evidence that access control is correct.

Each template includes a DEPLOY.md with Vercel and Netlify steps and the environment variables to set. You can also generate platform-specific commands:

npx @centrali-io/create-centrali-app env --format=vercel
npx @centrali-io/create-centrali-app env --format=netlify

Secret values are masked in that output by default; pass --show-secrets to print them.

Using Your Own Auth Provider

Once your app needs per-user access, keep the server-side path and add your own auth provider (Clerk, Auth0, …), passing user tokens to the SDK.

Next Steps