Next.js quickstart

Get a fresh Next.js app from nothing to a signed-in user, using the published @timonier/nextjs package. Part 1 creates a project and an app in your operator dashboard; Part 2 wires the SDK into the app.

Part 1 — create a project and an app

Open your platform's operator dashboard. Sign-up and sign-in share one screen — if you don't have an operator account yet, entering your email there creates one.

Enter your email and click Sign in, then enter the 6-digit code from the email.

The dashboard walks you straight into creating your first project.

2. Create a project

From Projects, create a new project: give it a display name and a slug, then confirm.

3. Create an app

From the project's apps list, create a new app. Fill in:

Display name and Slug — anything you like.
Redirect URI 1 — http://localhost:3000/api/timonier/callback for local development. This is where @timonier/nextjs receives the sign-in callback.
Signup enabled — leave this checked (it's checked by default). If you uncheck it, the sign-up step later in this guide is rejected by the platform.

Confirm, then save your credentials.

4. Get your three values

Open the app's Integration tab. You'll need three values from the .env.local block shown there for Part 2:

TIMONIER_PLATFORM_URL=<your platform URL>
TIMONIER_PROJECT_SLUG=<your project slug>
TIMONIER_APP_SLUG=<your app slug>

The tab derives the scheme for you when the hostname is localhost, 127.0.0.1, or ::1, writing http:// there. For any other hostname it always writes https:// — if you're self-hosting on a real hostname and your data plane serves plain HTTP, change the scheme to http:// yourself, or your app can't reach it.

Part 2 — wire up the app

5. Create a Next.js app

npx --yes create-next-app@latest myapp --ts --app --no-tailwind --eslint --no-src-dir --import-alias "@/*" --use-npm

This scaffolds an App Router, TypeScript project in myapp/, no src/ directory.

6. Scope the registry

cd myapp
echo "@timonier:registry=https://npm.registry.timonier.eu/" >> .npmrc

7. Install

npm install @timonier/nextjs

8. Scaffold the integration

npx timonier-nextjs init runs the bin of the scoped package @timonier/nextjs — it only resolves from node_modules/.bin once that package is installed in the current directory (step 7). Run it from anywhere else — a parent directory, a fresh shell, before step 7 — and npx falls back to the public registry looking for a package literally named timonier-nextjs, which does not exist there:

npm error 404 Not Found - GET https://registry.npmjs.org/timonier-nextjs - Not found
npm error 404  The requested resource 'timonier-nextjs@*' could not be found

That 404 means the wrong directory or a skipped step 7 — not a missing product. Continue directly from step 7, still inside myapp from step 6:

# from inside myapp/ — the same directory as steps 6 and 7
npx timonier-nextjs init

It asks three questions, in order. Answer with the values from Part 1, step 4:

Platform URL (e.g. https://auth.example.com): <your platform URL>
Project slug: <your project slug>
App slug: <your app slug>

init writes .env.local — including a generated TIMONIER_SESSION_SECRET and TIMONIER_POST_SIGN_IN_PATH — and scaffolds a sign-in page, a sign-up page, a profile page that shows signed-in state, and the callback route handler, then wraps your layout in <AuthProvider>.

9. Signed-in state

init already scaffolds app/profile/page.tsx, which shows signed-in state via useUser(), and writes TIMONIER_POST_SIGN_IN_PATH=/profile so sign-up and sign-in land you there automatically. No extra configuration or page to write — visit http://localhost:3000/profile after signing in to see it.

10. Run it

npm run dev

Visit http://localhost:3000/sign-up, enter your email, then the 6-digit code from your inbox.

You should see Signed in as your email. That's a working integration.

API reference

This guide covers sign-up and sign-in only. For every export, prop, and hook @timonier/nextjs provides, read the README that ships inside the installed package: node_modules/@timonier/nextjs/README.md.