Getting Started / create-sentroy-app

Start a project

create-sentroy-app scaffolds a Next.js or React Router v7 project already wired to Sentroy — end-user Auth, Storage and transactional Email. Pick shadcn/ui or Material UI, choose only the services you need, and start building in seconds — with every secret key kept safely server-side.

Quick start#

One command. The CLI asks a few questions, then generates a ready-to-run app.

npm create sentroy-app@latest

Then follow the printed next steps:

cd my-sentroy-app

# fill in .env.local with your Sentroy keys (see below)
npm run dev
# → http://localhost:3000

What the CLI asks#

Everything is à la carte — you only get the code for what you pick.

Framework

Next.js (App Router) — server route handlers + httpOnly cookies. Or React Router v7(framework mode) — Vite + SSR, with loaders/actions and resource routes plus a signed cookie session. Both keep your secret keys server-side; a pure client-only SPA isn't offered because it can't hold the master keys safely.

UI library

shadcn/ui — Tailwind CSS v4 with self-contained, copy-paste primitives (Button, Input, Card…). Or Material UI — @mui/material v6 with Emotion (SSR-ready on both frameworks). Both ship the exact same pages and logic; only the presentation differs.

Services

Select any subset of Auth, Storage and Email. Unselected services are pruned entirely — no routes, no pages, no dependencies. A generated lib/features.ts records your choice and drives the nav.

Auth provider

When you pick Auth, choose how it's managed: Sentroy Auth Project (hosted user pool, no database — the aps_ proxy + httpOnly cookie flow), or better-auth (self-hosted users in SQLite) with Sign in with Sentroy (OAuth/ OIDC federation). The better-auth option needs one extra step after install: npx @better-auth/cli@latest migrate to create its tables.

Package manager & git

Choose npm / pnpm / yarn / bun (auto-detected from how you invoked the command) and whether to git init. Dependencies install automatically unless you skip.

Security model#

Secrets never reach the browser. This is the single most important thing the starter gets right for you.

Auth. Your Auth Project aps_ key is the master key to your entire user pool. The starter uses it only server-side — Next.js route handlers (app/api/auth/*) or React Router resource routes/actions — which proxy to auth.sentroy.com and set an httpOnly cookie session. Access tokens (RS256 JWTs) are verified against the project JWKS with jose. The browser only ever talks to your own app routes.

Storage & Email. Your company stk_ access token is used only in app/api/storage/* and app/api/email/send — file uploads and sends are proxied through the server.

What gets generated#

A clean App Router project — only the selected services included.

my-sentroy-app/
├─ app/
│  ├─ api/
│  │  ├─ auth/{login,signup,logout,session,password-reset}/route.ts
│  │  ├─ storage/{upload,list}/route.ts
│  │  └─ email/send/route.ts
│  ├─ login/  signup/  forgot-password/  dashboard/    # auth pages
│  ├─ storage/page.tsx                                  # upload + list
│  ├─ email/page.tsx                                    # send form
│  ├─ layout.tsx  page.tsx  providers.tsx
├─ lib/
│  ├─ auth-server.ts   session.ts        # aps_ proxy + cookie + JWKS
│  ├─ sentroy-server.ts                  # stk_ company client (SDK)
│  └─ features.ts                        # which services are enabled
├─ middleware.ts                         # protects /dashboard
├─ components/                           # UI (shadcn or MUI)
└─ .env.local

Environment variables#

The CLI writes a commented .env.local containing exactly the keys for the services you chose.

Auth

# aps_ is the master key to your user pool — SERVER-ONLY.
SENTROY_AUTH_BASE_URL=https://auth.sentroy.com
SENTROY_AUTH_PROJECT_SLUG=your-project-slug
SENTROY_AUTH_API_KEY=aps_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Public — only used to verify JWTs against the project JWKS.
NEXT_PUBLIC_SENTROY_AUTH_PROJECT_SLUG=your-project-slug

Create an Auth Project and copy its slug + aps_ key — see Auth Projects.

Storage & Email

# stk_ is company-scoped admin — SERVER-ONLY.
SENTROY_BASE_URL=https://sentroy.com
SENTROY_COMPANY_SLUG=your-company-slug
SENTROY_ACCESS_TOKEN=stk_...

# Storage
SENTROY_STORAGE_BUCKET=uploads

# Email (verify a sending domain first)
SENTROY_EMAIL_FROM=[email protected]
SENTROY_EMAIL_DOMAIN_ID=your-domain-id

Generate a company access token and (for email) verify a domain — see Storage and Mail.

Add shadcn components & presets#

The shadcn variant is a standard shadcn project — extend it with the registry, blocks and theme presets.

The generated app ships a components.json (for both Next.js and React Router), so the shadcn CLI works against it directly:

# any component or block from the shadcn registry
npx shadcn@latest add button card dialog
npx shadcn@latest add dashboard-01

The shadcn variant uses CSS-variable theming (cssVariables: true) with the standard token set (--background, --primary, --muted, --ring…) in globals.css, so theme presets recolor the whole app out of the box. The Material UI variant is themed via app/theme.ts instead.

Where to go next#

The generated app is a starting point — extend it with the full Sentroy feature set.

Auth — add MFA, magic links, social federation and hosted UI: Auth Projects.
Storage — buckets, thumbnails and the React MediaManager.
Email — templates, audiences, webhooks and logs: Mail.

PreviousOverview Next Mail