Quickstart

Next.js Quickstart

Add StateAnchor to a Next.js project with API routes. You’ll get a gate verdict on every PR in about 5 minutes.

Step 1 -- Add stateanchor.yaml to your repo root

This file is the single source of truth for the gate. Describe your API routes (the ones you want to protect from breaking changes):

service: my-nextjs-app
version: "1.0.0"

server:
  base_url: https://my-app.vercel.app/api
  auth:
    type: bearer

endpoints:
  - name: getUser
    method: GET
    path: /user
    description: Get the authenticated user profile

  - name: listProjects
    method: GET
    path: /projects
    description: List all projects for the authenticated user

  - name: createProject
    method: POST
    path: /projects
    description: Create a new project
    body:
      name: string
      description: string

Not sure what to put here? Use the YAML Scaffolder → or read the full stateanchor.yaml reference.

Step 2 -- Add the GitHub Action

Create .github/workflows/stateanchor.yml in your repo:

name: StateAnchor Gate

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  id-token: write   # GitHub OIDC -- no API key secret needed
  contents: read
  pull-requests: write

jobs:
  stateanchor-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: stateanchor-hq/sync-action@v1
        with:
          mode: enforce
          annotate-pr: 'true'
          enforce-on-prs: 'true'

The action uses GitHub OIDC -- no API key or secret required in most cases. See the GitHub Action reference for all options.

Step 3 -- Connect your repo at stateanchor.dev

Sign in and connect your GitHub repo. StateAnchor will sync automatically on your next push.

→ Connect a repo (free)

Step 4 -- Local validation with stateanchor check

Before pushing, you can validate your stateanchor.yaml locally. Run this from your repo root:

node bin/stateanchor-check.js

This runs 17 structural rules and outputs ERR / WARN / INFO findings. No network call. No authentication required. Exit 1 on ERR findings.

See the CLI reference for flags (--config, --fail-on, --json).

What to expect

• First sync:StateAnchor builds the initial IR snapshot. No gate verdict on the first sync -- it’s the baseline.
• Subsequent PRs:every push diffs your spec against the prior snapshot. ERR findings block the merge; WARN findings are flagged but don’t block; INFO findings pass silently.
• Gate blocked? See Handling a block -- you can fix the spec, file a scoped exception, or roll back.

Related

• stateanchor.yaml reference -- full spec for all fields
• Gate kinds reference -- all 33 ERR / WARN / INFO kinds
• GitHub Action reference -- inputs, outputs, OIDC, mode options
• CLI reference -- full stateanchor check documentation
• Handling a block -- what to do when the gate returns ERR