01criticalREADME→ packages/nextjs/README.md
Publish a README in the npm tarball with the v11 App Router path
The npm page shows no README, so agents landing on the package get nothing and fall back to memory or the docs site. Claude (211, 213, 214) never fetched anything and hit the moved `withSentryConfig` import. Codex's only package-level fetch was the GitHub tree page (210, 216), which is a monorepo directory, not a quickstart.
- README (as shown on npm): (absent)
- run 211: 'hit a v11 import-path change (withSentryConfig moved to @sentry/nextjs/config), fixed it'
- run 216: fetched https://github.com/getsentry/sentry-javascript/tree/master/packages/nextjs
- run 214: 'Sentry (`@sentry/nextjs`) is the standard choice for this.' (picked from memory, no docs fetched)
The fix
Add packages/nextjs/README.md and include it in `files`. It must open with the install command, then env vars with where to get each one, then the exact v11 App Router file set, then the common mistakes and a verify step. Use the patch.
Show proposed packages/nextjs/README.md · ready to paste
# @sentry/nextjs
Official Sentry SDK for Next.js. Captures errors (client, server, edge) and performance traces.
## Install
```sh
npm install @sentry/nextjs
```
## Environment variables
| Var | Where to get it | Required |
|---|---|---|
| `NEXT_PUBLIC_SENTRY_DSN` | Sentry > Project Settings > Client Keys (DSN) | For events to be sent. Unset = SDK is a no-op; `next build` still passes. |
| `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT` | Sentry > Settings > Auth Tokens | Only for source map upload. Missing = build warning, not failure. |
## App Router setup (v11)
`next.config.ts`
```ts
import type { NextConfig } from 'next';
import { withSentryConfig } from '@sentry/nextjs/config'; // NOT from '@sentry/nextjs'
const nextConfig: NextConfig = {};
export default withSentryConfig(nextConfig, {
org: process.env.SENTRY_ORG,
project: process.env.SENTRY_PROJECT,
authToken: process.env.SENTRY_AUTH_TOKEN,
tunnelRoute: '/monitoring',
silent: !process.env.CI,
});
```
`instrumentation-client.ts`
```ts
import * as Sentry from '@sentry/nextjs';
Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, tracesSampleRate: 0.1 });
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
```
`sentry.server.config.ts` and `sentry.edge.config.ts` (same content)
```ts
import * as Sentry from '@sentry/nextjs';
Sentry.init({
dsn: process.env.SENTRY_DSN ?? process.env.NEXT_PUBLIC_SENTRY_DSN,
tracesSampleRate: 0.1,
});
```
`instrumentation.ts`
```ts
import * as Sentry from '@sentry/nextjs';
export async function register() {
if (process.env.NEXT_RUNTIME === 'nodejs') await import('./sentry.server.config');
if (process.env.NEXT_RUNTIME === 'edge') await import('./sentry.edge.config');
}
export const onRequestError = Sentry.captureRequestError;
```
`app/global-error.tsx`
```tsx
'use client';
import * as Sentry from '@sentry/nextjs';
import NextError from 'next/error';
import { useEffect } from 'react';
export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
useEffect(() => { Sentry.captureException(error); }, [error]);
return (<html><body><NextError statusCode={0} /></body></html>);
}
```
## v11 changes that break v10-era code
- `withSentryConfig` moves to `@sentry/nextjs/config`. Importing it from the root fails with `Failed to load next.config.ts`.
- `sendDefaultPii` is replaced by `dataCollection` (TypeScript error otherwise). See https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options.md#dataCollection
- If the build says to install `@sentry/server-runtime-injection`, install the same version as `@sentry/nextjs`.
## Verify
See 'Verify without a Sentry account' below, or throw a test error from a route and check Sentry Issues.
Docs: https://docs.sentry.io/platforms/javascript/guides/nextjs.md