---
title: "Quick start for Next.js"
description: "Add MainSDK to a Next.js App Router app, guard one route with auth.require, run it in local mode with a test user and pass mainsdk check."
section: "getting-started"
status: "Planned for 0.5"
spec: "public-beta"
canonical: "https://mainsdk.dev/docs/getting-started/quickstart-nextjs"
updated: "2026-10-28"
---

# Quick start for Next.js

> Add MainSDK to a Next.js App Router app, guard one route with auth.require, run it in local mode with a test user and pass mainsdk check.

Status: Planned for 0.5 · Canonical: https://mainsdk.dev/docs/getting-started/quickstart-nextjs · Updated: 2026-10-28

You will add MainSDK to a Next.js app, guard one route and run it with no account or key. It takes about 10 minutes. Next.js support covers the App Router.

## 1. Initialise

Run this in the root of a Next.js app. It writes `main.yaml` with local drivers and tells your coding agent the rules.

```bash
npx mainsdk init
```

## 2. Mount MainSDK

```ts title="proxy.ts"
import { mainsdk } from 'mainsdk/next'

export const proxy = mainsdk.proxy()
```

## 3. Guard a route

```ts title="app/api/me/route.ts"
import { auth } from 'mainsdk'
import { withMainSDK } from 'mainsdk/next'

// One route that needs a signed-in user: anyone else gets a 401 problem with a fix.
export const GET = withMainSDK(async (req) => {
  const session = await auth.require(req)
  return Response.json({ user: session.user })
})
```

## 4. Run it in local mode

In local mode the bearer token `dev_ada` stands for a test person called `ada`. It works only on loopback, under `mainsdk dev`.

```bash
npx mainsdk dev -- npm run dev
curl -i localhost:3000/api/me
curl -i -H "Authorization: Bearer dev_ada" localhost:3000/api/me
```

The first call answers `401` with a problem body that carries `MAIN-AUTH-0001` and a fix. The second answers `200` with the user.

## Check it

```bash
npx mainsdk check
```

The check passes when it prints `Passed`. It fails on a key in code, an undeclared network call or an unguarded action, and names the fix for each. Run it in CI too.

## What the sample app is

The finished app is in the repository under `apps/examples/nextjs`. CI installs it, starts it in local mode, requests the signed-in route and runs `mainsdk check`, so these steps cannot drift from the code. MainSDK is pre-release and no package is published yet: until the first beta, run the sample from a checkout.