Skip to content

docs(astro): Document Astro 6 support on Cloudflare #17749

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
JPeer264 wants to merge 1 commit into
base: master
Choose a base branch
from
+77 −47
Open

docs(astro): Document Astro 6 support on Cloudflare #17749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
21 changes: 19 additions & 2 deletions docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,31 @@ You need:

- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
- Your application up and running
- Astro `3.0.0` or above
- `@astrojs/cloudflare` v12
- Astro `6.0.0` or above
- `@astrojs/cloudflare` v13 or above
- `@sentry/astro` v10.40.0 or above
- `@sentry/cloudflare` v10.40.0 or above

If you're using Cloudflare Pages (not Workers), see the section below for
setup instructions. We recommend migrating to Cloudflare Workers for better
Sentry integration and full feature support.

<Expandable level="info" title="Using Astro 3-5 with @astrojs/cloudflare v12?">

For Astro 3-5 with `@astrojs/cloudflare` v12, the `@sentry/astro` integration automatically detects the Cloudflare adapter and wraps your Worker with the `@sentry/cloudflare` SDK for proper request isolation and async context.

Follow the standard [Astro on Cloudflare setup](/platforms/javascript/guides/astro/#install) without the custom entry point configuration described below. The SDK handles server-side initialization automatically.
Copy link
Copy Markdown
Member

@s1gr1d s1gr1d May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this the "Astro on Cloudflare" or just the "Astro" setup?


<Alert level="warning" title="Server-side configuration via environment variables only">

With Astro 3-5 on Cloudflare, server-side SDK configuration only works via [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/). The `sentry.server.config.(ts|js)` file is not supported.

The SDK reads standard Sentry environment variables including `SENTRY_DSN`, `SENTRY_TRACES_SAMPLE_RATE`, `SENTRY_RELEASE`, `SENTRY_ENVIRONMENT`, and others. See the [SDK configuration spec](https://develop.sentry.dev/sdk/foundations/client/configuration/#environment-variables) for the full list.

</Alert>

</Expandable>

<Expandable level="info" title="Using Astro on Cloudflare Pages?">

<SplitLayout>
Expand Down
103 changes: 58 additions & 45 deletions platform-includes/getting-started-complete/javascript.astro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,63 @@ pnpm add @sentry/astro @sentry/cloudflare
platform="javascript.cloudflare"
/>

### Configure Custom Entry Point

<SplitLayout>
<SplitSection>
<SplitSectionText>

Astro 6 with `@astrojs/cloudflare` v13+ supports custom entry points directly from `wrangler.jsonc`. Update your wrangler configuration to point to a custom Sentry entry point:

</SplitSectionText>
<SplitSectionCode>

```jsonc {filename:wrangler.jsonc}
{
"main": "./sentry.server.config.ts",
// ... other configuration
}
```

</SplitSectionCode>
</SplitSection>

<SplitSection>
<SplitSectionText>

Create a `sentry.server.config.ts` file in the root of your project that wraps the Astro Cloudflare handler with Sentry:

</SplitSectionText>
<SplitSectionCode>

```typescript {filename:sentry.server.config.ts}
import * as Sentry from "@sentry/cloudflare";
import handler from "@astrojs/cloudflare/entrypoints/server";

export default Sentry.withSentry(
(env) => ({
dsn: env.SENTRY_DSN,
// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/javascript/guides/astro/configuration/options/#sendDefaultPii
sendDefaultPii: true,
// ___PRODUCT_OPTION_START___ performance
// Define how likely traces are sampled. Adjust this value in production,
// or use tracesSampler for greater control.
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs
// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
}),
handler
);
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>

### Register the Sentry Integration

<SplitLayout>
Expand All @@ -103,8 +160,6 @@ pnpm add @sentry/astro @sentry/cloudflare

Follow [Astro's Cloudflare deployment guide](https://docs.astro.build/en/guides/deploy/cloudflare/) if you haven't already. Then add the Sentry integration to your `astro.config.mjs` alongside the Cloudflare adapter.

The `@sentry/astro` integration automatically detects the Cloudflare adapter and wraps your Worker with the `@sentry/cloudflare` SDK for proper request isolation and async context.

</SplitSectionText>
<SplitSectionCode>

Expand Down Expand Up @@ -311,49 +366,7 @@ Sentry.init({

<PlatformSection supported={["javascript.cloudflare"]}>

<SplitLayout>
<SplitSection>
<SplitSectionText>

Create a `sentry.server.config.(ts|js)` file in the root of your project. In this file, import and initialize Sentry for the server:

<Alert level="warning" title="Production configuration via environment variables">

The `sentry.server.config.(ts|js)` file only works during local development. In production on Cloudflare Workers, you must use [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/) to configure Sentry.

The SDK reads standard Sentry environment variables including `SENTRY_DSN`, `SENTRY_TRACES_SAMPLE_RATE`, `SENTRY_RELEASE`, `SENTRY_ENVIRONMENT`, and others. See the [SDK configuration spec](https://develop.sentry.dev/sdk/foundations/client/configuration/#environment-variables) for the full list.

</Alert>

</SplitSectionText>
<SplitSectionCode>

```javascript {filename:sentry.server.config.(ts|js)}
import * as Sentry from "@sentry/astro";

Sentry.init({
dsn: "___PUBLIC_DSN___",

// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/javascript/guides/astro/configuration/options/#sendDefaultPii
sendDefaultPii: true,
// ___PRODUCT_OPTION_START___ performance

// Define how likely traces are sampled. Adjust this value in production,
// or use tracesSampler for greater control.
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs

// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
});
```

</SplitSectionCode>
</SplitSection>
</SplitLayout>
Server-side Sentry is already configured in your custom entry point file (`sentry.server.config.ts`) created in the previous step.

</PlatformSection>

Expand Down
Loading