Skip to content

docs(js): Quick Start guides: Auth tokens in env files #14159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs(js): Quick Start guides: Auth tokens in env files #14159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
46a164d
js quick start guides content update: auth tokens should be stored in…
inventarSarah Jun 26, 2025
139752a
fix typo
inventarSarah Jun 26, 2025
3affccc
Merge branch 'master' of github.com:getsentry/sentry-docs into smi/qu…
inventarSarah Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions docs/platforms/javascript/guides/nextjs/manual-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,13 @@ description: "Learn how to manually set up Sentry in your Next.js app and captur
Choose the features you want to configure, and this guide will show you how:

<OnboardingOptionButtons
options={["error-monitoring", "performance", "session-replay", "user-feedback", "logs"]}
options={[
"error-monitoring",
"performance",
"session-replay",
"user-feedback",
"logs",
]}
/>

<PlatformContent includePath="getting-started-features-expandable" />
Expand Down Expand Up @@ -90,6 +96,7 @@ export default withSentryConfig(nextConfig, {
### Initialize Sentry Client-Side and Server-Side SDKs

Create three files in your application's root directory:

- `sentry.server.config.(js|ts)`
- `sentry.edge.config.(js|ts)`
- `instrumentation-client.(js|ts)`
Expand Down Expand Up @@ -220,7 +227,8 @@ Sentry.init({
```

<Alert title="Tip">
Include your DSN directly in these files, or use a _public_ environment variable like `NEXT_PUBLIC_SENTRY_DSN`.
Include your DSN directly in these files, or use a _public_ environment
variable like `NEXT_PUBLIC_SENTRY_DSN`.
</Alert>

### Register Sentry Server-Side SDK Initialization
Expand Down Expand Up @@ -433,7 +441,7 @@ module.exports = withSentryConfig(nextConfig, {
});
```

Alternatively, set the `SENTRY_AUTH_TOKEN` environment variable in your `.env` file:
Set the `SENTRY_AUTH_TOKEN` environment variable in your `.env` file:

```sh {filename:.env}
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
Expand Down
23 changes: 19 additions & 4 deletions docs/platforms/javascript/guides/nuxt/manual-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,13 @@ Add the following overrides:
Choose the features you want to configure, and this guide will show you how:

<OnboardingOptionButtons
options={["error-monitoring", "performance", "session-replay", "user-feedback", "logs"]}
options={[
"error-monitoring",
"performance",
"session-replay",
"user-feedback",
"logs",
]}
/>

<PlatformContent includePath="getting-started-features-expandable" />
Expand Down Expand Up @@ -218,20 +224,29 @@ Check out the <PlatformLink to="/install/cli-import">`--import` CLI flag</Platfo

To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slugs in the `sentry.sourceMapsUploadOptions` inside your configuration file:

```javascript {filename:nuxt.config.ts} {3-9}
<Alert>These `sentry` options only affect the **build time** of the SDK.</Alert>

```javascript {filename:nuxt.config.ts} {3-10}
export default defineNuxtConfig({
modules: ["@sentry/nuxt/module"],
sentry: {
sourceMapsUploadOptions: {
org: "___ORG_SLUG___",
project: "___PROJECT_SLUG___",
authToken: "___ORG_AUTH_TOKEN___",
// store your auth token in an environment variable
authToken: process.env.SENTRY_AUTH_TOKEN,
},
},
});
```

<Alert>These `sentry` options only affect the **build time** of the SDK.</Alert>
To keep your auth token secure, always store it in an environment variable instead of directly in your files:

<OrgAuthTokenNote />

```bash {filename:.env}
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
```

While Nuxt generates source maps on the server side by default, you need to explicitly enable client-side source maps in your Nuxt configuration:

Expand Down
111 changes: 59 additions & 52 deletions docs/platforms/javascript/guides/react-router/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ categories:

<Alert title='SDK Limitations' level='warning'>

This SDK is considered **experimental and in an alpha state**. It may experience breaking changes. Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issues/) if you have any feedback or concerns.
This SDK is considered **experimental and in an alpha state**. It may experience breaking changes. Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issues/) if you have any feedback or concerns.

</Alert>

<Alert title='Looking for library mode?' level='info'>

If you are using React Router in library mode, you can follow the instructions in the [React guide here](/platforms/javascript/guides/react/features/react-router/v7).
If you are using React Router in library mode, you can follow the instructions in the [React guide here](/platforms/javascript/guides/react/features/react-router/v7).

</Alert>

Expand All @@ -35,25 +35,25 @@ Sentry captures data by using an SDK within your application's runtime.
"user-feedback",
"logs",
{
id: 'profiling',
checked: false
}
id: "profiling",
checked: false,
},
]}
/>

<OnboardingOption optionId="profiling">

```bash {tabTitle:npm}
npm install @sentry/react-router @sentry/profiling-node
```
```bash {tabTitle:npm}
npm install @sentry/react-router @sentry/profiling-node
```

```bash {tabTitle:yarn}
yarn add @sentry/react-router @sentry/profiling-node
```
```bash {tabTitle:yarn}
yarn add @sentry/react-router @sentry/profiling-node
```

```bash {tabTitle:pnpm}
pnpm add @sentry/react-router @sentry/profiling-node
```
```bash {tabTitle:pnpm}
pnpm add @sentry/react-router @sentry/profiling-node
```

</OnboardingOption>

Expand All @@ -62,18 +62,20 @@ Sentry captures data by using an SDK within your application's runtime.
npm install @sentry/react-router
```

```bash {tabTitle:yarn}
yarn add @sentry/react-router
```
```bash {tabTitle:yarn}
yarn add @sentry/react-router
```

```bash {tabTitle:pnpm}
pnpm add @sentry/react-router
```

```bash {tabTitle:pnpm}
pnpm add @sentry/react-router
```
</OnboardingOption>

## Configure

### Expose Hooks

React Router exposes two hooks in your `app` folder (`entry.client.tsx` and `entry.server.tsx`).
If you do not see these two files, expose them with the following command:

Expand All @@ -93,11 +95,11 @@ Initialize the Sentry React SDK in your `entry.client.tsx` file:

+Sentry.init({
+ dsn: "___PUBLIC_DSN___",
+
+
+ // Adds request headers and IP for users, for more info visit:
+ // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#sendDefaultPii
+ sendDefaultPii: true,
+
+
+ integrations: [
+ // ___PRODUCT_OPTION_START___ performance
+ Sentry.reactRouterTracingIntegration(),
Expand Down Expand Up @@ -189,10 +191,10 @@ export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
Automatic server-side instrumentation is currently only supported on:
- **Node 20:** Version \<20.19
- **Node 22:** Version \<22.12


If you are on a different version please make use of our manual server wrappers.

For server loaders use `wrapServerLoader`:
```ts
import * as Sentry from '@sentry/react-router';
Expand Down Expand Up @@ -228,12 +230,12 @@ Create an `instrument.server.mjs` file in the root of your app:
```js {filename: instrument.server.mjs}
import * as Sentry from "@sentry/react-router";
// ___PRODUCT_OPTION_START___ profiling
import { nodeProfilingIntegration } from '@sentry/profiling-node';
import { nodeProfilingIntegration } from "@sentry/profiling-node";
// ___PRODUCT_OPTION_END___ profiling

Sentry.init({
dsn: "___PUBLIC_DSN___",

// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#sendDefaultPii
sendDefaultPii: true,
Expand All @@ -243,7 +245,7 @@ Sentry.init({
_experiments: { enableLogs: true },
// ___PRODUCT_OPTION_END___ logs
// ___PRODUCT_OPTION_START___ profiling

integrations: [nodeProfilingIntegration()],
// ___PRODUCT_OPTION_END___ profiling
// ___PRODUCT_OPTION_START___ performance
Expand Down Expand Up @@ -287,11 +289,11 @@ export const handleError: HandleErrorFunction = (error, { request }) => {

<Expandable title="Do you need to customize your handleRequest function?">
If you need to update the logic of your `handleRequest` function you'll need to include the provided Sentry helper functions (`getMetaTagTransformer` and `wrapSentryHandleRequest`) manually:

```tsx {1-4, 44-45, 69-70}
import { getMetaTagTransformer, wrapSentryHandleRequest } from '@sentry/react-router';
// ... other imports

const handleRequest = function handleRequest(
request: Request,
responseStatusCode: number,
Expand Down Expand Up @@ -350,13 +352,16 @@ export const handleError: HandleErrorFunction = (error, { request }) => {
// Abort the rendering stream after the `streamTimeout`
setTimeout(abort, streamTimeout);
});
};

// wrap the default export
export default wrapSentryHandleRequest(handleRequest);

// ... rest of your entry.server.ts file
```
};

// wrap the default export
export default wrapSentryHandleRequest(handleRequest);

// ... rest of your entry.server.ts file

```

</Expandable>

### Update Scripts
Expand All @@ -368,8 +373,8 @@ Update the `start` and `dev` script to include the instrumentation file:

```json {filename: package.json}
"scripts": {
"dev": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router dev",
"start": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router-serve ./build/server/index.js",
"dev": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router dev",
"start": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router-serve ./build/server/index.js",
}
```

Expand All @@ -387,16 +392,14 @@ If you're deploying to platforms like **Vercel** or **Netlify** where setting th

<Alert title="Incomplete Auto-instrumentation" level="warning">

When importing the instrumentation file directly in `entry.server.tsx` instead of using the `--import` flag, automatic instrumentation will be incomplete and you'll miss automatically captured spans and traces for some of your application's server-side operations. This approach should only be used when the `NODE_OPTIONS` approach is not available on your hosting platform.
When importing the instrumentation file directly in `entry.server.tsx` instead of using the `--import` flag, automatic instrumentation will be incomplete and you'll miss automatically captured spans and traces for some of your application's server-side operations. This approach should only be used when the `NODE_OPTIONS` approach is not available on your hosting platform.

</Alert>

## Source Maps Upload

Update `vite.config.ts` to include the `sentryReactRouter` plugin, making sure to pass both the Vite and Sentry configurations to it:

<OrgAuthTokenNote />

```typescript {filename: vite.config.ts} {diff}
import { reactRouter } from '@react-router/dev/vite';
import { sentryReactRouter, type SentryReactRouterBuildOptions } from '@sentry/react-router';
Expand All @@ -406,8 +409,9 @@ const sentryConfig: SentryReactRouterBuildOptions = {
org: "___ORG_SLUG___",
project: "___PROJECT_SLUG___",

// An auth token is required for uploading source maps.
authToken: "___ORG_AUTH_TOKEN___"
// An auth token is required for uploading source maps;
// store it in an environment variable to keep it secure.
authToken: import.meta.env.VITE_SENTRY_AUTH_TOKEN,
// ...
};

Expand All @@ -418,18 +422,26 @@ export default defineConfig(config => {
});
```

To keep your auth token secure, always store it in an environment variable instead of directly in your files:

<OrgAuthTokenNote />

```bash {filename:.env}
VITE_SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
```

Include the `sentryOnBuildEnd` hook in `react-router.config.ts`:

```typescript {filename: react-router.config.ts} {diff}
import type { Config } from '@react-router/dev/config';
import { sentryOnBuildEnd } from '@sentry/react-router';
import type { Config } from "@react-router/dev/config";
import { sentryOnBuildEnd } from "@sentry/react-router";

export default {
ssr: true,
buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => {
// ...
// Call this at the end of the hook
+ await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest });
+(await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest }));
},
} satisfies Config;
```
Expand All @@ -449,13 +461,8 @@ export async function loader() {
}

export default function ExamplePage() {
return (
<div>
Loading this page will throw an error
</div>
);
return <div>Loading this page will throw an error</div>;
}

```

<Alert>
Expand Down
Loading