TrueClaradocs
GitHub
Start/Quickstart

Quickstart

Install TrueClara on one production Next.js app, connect the route graph, and confirm deploy-attributed behavior signals.

Onboarding Repo (THEME (light))
Onboarding starts at the repo wizard — point trueclara at the Next.js app it should learn.

This path gets a Next.js app from no signal to a working TrueClara project. It mirrors the product model: one project represents one runtime environment, with the parser, runtime SDK, and deploy uploads feeding the same route graph.

Route graph

Upload the static graph from @trueclara/parser so Map, route matching, deploy diffs, and setup health have a source of truth.

Runtime events

Install @trueclara/next to send route and transition counters after your app has analytics consent.

Deploy records

Upload each production release so observations can point at the commit and graph version that changed behavior.

Before you start

  • A TrueClara account.
  • A Next.js app using the App Router or Pages Router.
  • Permission to install dependencies and edit the app shell.
  • A CI environment that can store TRUECLARA_PROJECT_KEY as a secret.

Use separate TrueClara projects for production and staging. Do not model environments inside one project.

1. Create a project

Open the app onboarding flow and choose the path that matches your repository.

  • Connect GitHub when the production app is available from the account you are using. TrueClara creates the workspace and project, then starts the parser flow.
  • Create manually when the repo is private to another host, when GitHub access is not available, or when you want to wire installation yourself.

The project gives you two different keys:

KeyWhere it belongsPurpose
NEXT_PUBLIC_TRUECLARA_KEYBrowser runtimeIdentifies the project for SDK event delivery.
TRUECLARA_PROJECT_KEYCI or server-side secretsAuthenticates graph and deploy uploads.

2. Install the runtime SDK

From the Next.js app root, run the install command shown in your project setup screen.

Terminal
NEXT_PUBLIC_TRUECLARA_KEY=<project-public-key> npx @trueclara/install

The installer adds @trueclara/next, writes the public key, and wraps the app with TrueClaraProvider. If it cannot safely edit your layout, it prints the manual provider change.

Manual setup:

TSX
import { TrueClaraProvider } from "@trueclara/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TrueClaraProvider publicKey={process.env.NEXT_PUBLIC_TRUECLARA_KEY!}>
          {children}
        </TrueClaraProvider>
      </body>
    </html>
  );
}

3. Upload the route graph

Run the parser from the app root and upload the full output. Do not reduce it to a list of routes.

Terminal
npx @trueclara/parser . --pretty -o trueclara-graph.json
curl -X POST https://api.trueclara.com/v1/static-graphs \
  -H "Content-Type: application/json" \
  -H "X-Trueclara-Project-Key: $TRUECLARA_PROJECT_KEY" \
  --data-binary @trueclara-graph.json

The graph powers route matching, Map, setup health, deploy diffs, and observation context.

4. Add deploy attribution

Upload a deploy record at the same boundary your team treats as production.

YAML
name: trueclara-deploy

on:
  push:
    branches: [main]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @trueclara/parser . --pretty -o trueclara-graph.json
      - run: node scripts/post-trueclara-deploy.mjs
        env:
          TRUECLARA_PROJECT_KEY: ${{ secrets.TRUECLARA_PROJECT_KEY }}
          TRUECLARA_ENVIRONMENT: production

Deploy attribution is what turns traffic changes into release evidence. Without it, TrueClara can show traffic and graph health, but observations cannot name the likely release boundary.

5. Verify setup

Observations List (THEME (light))
Observations are the operational queue once graph, runtime, and deploy signals arrive.

The setup strip should show these checks turning healthy:

Graph received

Map has routes, layouts, and edges from the parser output.

SDK installed

The provider is present in the app shell and uses the public key for this project.

First event received

Runtime counters are arriving after analytics consent permits delivery.

Deploy received

CI uploaded a release with commit metadata and the graph that shipped.

6. Mark value routes

Mark routes that represent product or revenue outcomes, such as signup completion, checkout success, onboarding completion, workspace creation, or upgrade confirmation.

Value routes let TrueClara prioritize route and edge regressions by downstream impact. A drop on /pricing matters more when it stops sessions from reaching /checkout/success.

Next