# Stopnetic installation instructions for a coding agent: Next.js

Guide revision: 2026-11-10.

## Task and boundaries

Integrate Stopnetic into the owner's existing project. Inspect first and follow
the owner's/project's instructions. Preserve UI, routes, authentication, data
permissions, SSR, hydration, middleware and package-manager choice. Do not replace
the application with a demo. Follow the owner's deployment process and report
anything incomplete rather than claiming untested protection.

This public guide contains no credentials. Never request secrets in chat, print
them, commit environment files, or expose them in browser code. If settings are
missing, explain which variable names the owner must configure in Integration,
their ignored server environment file, and hosting settings. Do not invent
credentials or weaken checks to proceed.

## 1. Inspect compatibility and existing files

- Find package.json, the lockfile, app/ or src/app/, existing Proxy/middleware,
  API handlers, Server Functions, hosting configuration and cache behavior.
- Guided setup requires **Next.js 16 App Router and Node.js 20.9 or newer**.
  Installing the package alone does not create the integration files.
- Other frameworks need the Stopnetic JavaScript agent guide.
- For Next.js 14/15 or Pages Router, explain the necessary migration first.
  Do not run a major framework migration unless the owner has authorized it.

When an upgrade is authorized, review the official migration guide and run:

```sh
node --version
npx @next/codemod@canary upgrade 16
# Only if synchronous request APIs still need migration:
npx @next/codemod@canary next-async-request-api .
npm run build
```

Review codemod changes and run the application's tests. This does not convert
Pages Router to App Router. Do not enable unrelated features to hide migration
errors. Reference: https://nextjs.org/docs/app/guides/upgrading/version-16

## 2. Configure the website server

The owner adds the website in Stopnetic, completes required account/domain
verification, and creates an installation key in **Integration**. Save actual
values in the website's ignored .env/.env.local and its hosting SERVER settings:

| Variable | Source |
| --- | --- |
| STOPNETIC_WEBSITE_ORIGIN | Canonical HTTPS website origin |
| STOPNETIC_SITE_ID | Site ID from Integration |
| STOPNETIC_API_URL | Decision endpoint URL from Integration |
| STOPNETIC_API_TOKEN | Private one-time installation key; retain a valid existing key |
| STOPNETIC_DECISION_PUBLIC_KEY | Complete public Ed25519 PEM from Integration |
| STOPNETIC_COOKIE_SECRET | Separate private random secret; retain an existing valid secret |

Preserve STOPNETIC_DECISION_ADDITIONAL_PUBLIC_KEYS if Integration supplies it.
Never copy the service's private signing key to a customer's application.
Do not use NEXT_PUBLIC_ prefixes for these settings.

The installer generates a cookie secret in .env.local if missing. Save the same
value privately in hosting settings and reuse it across workers/deployments.
Do not regenerate a working secret on every deployment.

Use the exact local env format copied from Integration. Keep the public PEM's
BEGIN/END lines and newlines; literal \n escapes are supported. Hosting fields
take values only, without the variable name or additional quotes. Do not flatten
PEM newlines into spaces. Local files do not configure hosting automatically.

## 3. Preview and apply a NEW integration

Run in the website project. These examples use npm; adapt to its existing package
manager without adding competing lockfiles. Read the installed SDK README/help.

```sh
npm install @stopnetic/next
npm exec --no -- stopnetic-next init --site --dry-run
```

Inspect the preview. If no existing files need manual merging, apply and check:

```sh
npm exec --no -- stopnetic-next init --site
npm exec --no -- stopnetic-next check
npm exec --no -- stopnetic-next check-config --production
npm run build
```

Expected outputs are stopnetic.guard.ts/.js, proxy.ts/.js,
app/api/stopnetic/verify/route.ts/.js and stopnetic.setup.json. Files use the
project's language; src/app projects place the guard/Proxy under src as appropriate.
Inspect actual output and imports rather than assuming every app generates .js.

Keep /api/stopnetic/verify reachable and excluded from interception. An application
/verify page is not required; it is separate from the SDK verification endpoint.
The installer refuses conflicting files. Merge existing middleware/Proxy instead
of deleting or overwriting it; preserve rewrites, locale and application auth.
Use one Next.js Proxy entry, not two competing generated interceptors.

## 4. Update an EXISTING installation safely

Upgrade @stopnetic/next using the existing package manager. SDK behavior lives
in the dependency, so a normal update can change only package.json and its lock.
Keep working guard/Proxy/verifier files. Do not rerun init over customized code.

For an unchanged generated installation that needs whole-site coverage:

```sh
npm exec --no -- stopnetic-next update-coverage --site --dry-run
npm exec --no -- stopnetic-next update-coverage --site
```

Custom files need manual review/merging. `check` validates generated-file integrity
and settings. `check-config --production` validates settings separately for custom
integrations; neither proves live route coverage or domain/key/plan health.

## 5. Protect the intended pages AND their data

Whole-site mode lets the owner manage paths in **Policies** after one deployment.
Unmatched paths are public. Installation alone does not mark content private.
Do not add broad blocks or protect every page without the owner's intent.

Example rules only; replace them with the actual approved paths:

| Path | Type | Action |
| --- | --- | --- |
| /members | Page | Automatic browser flow |
| /api/members/* | API | Require verified session (no challenge) |

First matching rule wins. Exact paths and trailing /* prefixes differ; put
specific exceptions first. Browser page verification can establish the same-origin
cookie sent with protected fetch calls. APIs cannot complete HTML verification.
Other API domains need their own guard or a guarded same-origin server proxy.

Check protected Route Handlers and Server Functions before accessing, mutating
or returning data. Follow the installed SDK README/types for the actual request
object. The core check in a Request-based handler is:

```js
// Import stopnetic from this project's generated guard using its actual path.
const denied = await stopnetic().check(request);
if (denied) return denied;
// Continue existing application login/data authorization and handler only now.
```

Do not expose private data in public bundles, prerendered files or shared caches.
Use private/no-store for protected output as appropriate. Check framework data,
prefetch and server-action paths. A server-side fetch does not automatically
inherit browser cookies. Keep the application's login/role/data permissions.

Passwords, interactive verification, country controls and budgets are optional.
Enable only requested features, following the installed SDK and product Docs.
Preview passwords require compatible passwordProtection support; budgets require
their documented trusted ingress and cost callback setup. Do not enable policies
before the server supports them.

## 6. Deploy and verify actual coverage

Run relevant app tests and build. Follow the owner's deployment instructions;
report hosting settings/deployment work still needed. For a local HTTP website
AND loopback service only, use --local-http on setup/check commands. Production
uses HTTPS and secure cookies.

From an environment using the deployed website's actual server settings:

```sh
npm exec --no -- stopnetic-next test-connection --production
```

This contacts Stopnetic and validates a signed response. It does not start a trial
or prove deployment/protection. Its coverage snapshot describes files on the
machine running it; custom files may report coverage unknown. The first actual
protected decision can start the owner's 72-hour trial.

Test real deployed routing with a fresh cookie-free browser and raw requests:

1. Public pages retain normal UI/rendering.
2. A protected page verifies before sending content. An eligible first challenge
   can use 404, followed by the permitted page after successful verification.
3. Unverified direct protected API requests withhold private data (normally 404).
4. Block rules withhold content even with a verified session.
5. Valid-session API requests still enforce application permissions.
6. JS/CSS/images, rewrites, navigation and framework data aliases work.
7. Static/CDN/cache/origin aliases cannot bypass protection.
8. Service/configuration failure withholds content (503). Do not fail open to
   pass tests. Recent SDKs show retry pages on eligible browser 503s; API/mutation
   requests are not automatically replayed.

Report changed files, installed versions, checks/results, intended coverage and
anything unverified. Never print secrets/private response bodies. Distinguish
installed, built, deployed and live-tested. Browser verification is not proof of
a human or a guarantee against every AI agent. Later policy changes need no npm
update/redeployment after compatible whole-site integration is in place.

Product documentation: https://www.stopnetic.com/docs
