Skip to content

docs(astro,cloudflare): Update the guide to Astro on Cloudflare Workers #16545

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

Merged
JPeer264 merged 1 commit into from
Mar 10, 2026
Merged

docs(astro,cloudflare): Update the guide to Astro on Cloudflare Workers #16545

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
2 changes: 1 addition & 1 deletion docs/platforms/javascript/guides/astro/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ You need:

<Alert level="warning" title="What runtime do you use?">
This SDK currently only works on Node runtimes, such as Node adapter or Vercel
with Lambda functions. If you use Cloudflare Pages, refer to our [Astro on
with Lambda functions. If you use Cloudflare Workers or Cloudflare Pages, refer to our [Astro on
Cloudflare guide](/platforms/javascript/guides/cloudflare/frameworks/astro/).
Other non-Node runtimes, like Vercel's Edge runtime, are currently **not
supported**.
Expand Down
66 changes: 60 additions & 6 deletions docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Astro on Cloudflare
description: "Learn how to instrument your Astro app on Cloudflare Pages and capture your first errors."
description: "Learn how to instrument your Astro app on Cloudflare Workers and capture your first errors."
---

## Prerequisites
Expand All @@ -10,6 +10,63 @@ 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
- `@sentry/astro` 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.
Copy link
Member

@andreiborza andreiborza Feb 26, 2026

Choose a reason for hiding this comment

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

q: Shouldn't this paragraph be outside of the Expandable?


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

For Cloudflare Pages, you need to manually set up the `@sentry/cloudflare` SDK using the Pages middleware.

1. Install both SDKs:

```bash {tabTitle:npm}
npm install @sentry/astro @sentry/cloudflare
```

```bash {tabTitle:yarn}
yarn add @sentry/astro @sentry/cloudflare
```

```bash {tabTitle:pnpm}
pnpm add @sentry/astro @sentry/cloudflare
```

2. Add the Sentry Astro integration to your `astro.config.mjs`:

```javascript {filename:astro.config.mjs}
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import sentry from "@sentry/astro";

export default defineConfig({
adapter: cloudflare(),
integrations: [sentry()],
});
```

3. <Include name="cloudflare-pages-middleware-intro.mdx" />

```javascript {filename:functions/_middleware.js}
import * as Sentry from "@sentry/cloudflare";

export const onRequest = [
// Make sure Sentry is the first middleware
Sentry.sentryPagesPlugin((context) => ({
dsn: "___PUBLIC_DSN___",
sendDefaultPii: true,
tracesSampleRate: 1.0,
})),
// Add more middlewares here
];
```

4. Make sure to [configure Cloudflare for Sentry](/platforms/javascript/guides/cloudflare/#wrangler-configuration).

</Expandable>

## Step 1: Install

Expand All @@ -23,9 +80,6 @@ You need:
]}
/>

<PlatformContent includePath="getting-started-features-expandable" />
<PlatformContent includePath="getting-started-features-expandable" platform="javascript.astro" />

<PlatformContent
includePath="getting-started-complete"
platform="javascript.astro"
/>
<PlatformContent includePath="getting-started-complete" platform="javascript.astro" />
89 changes: 53 additions & 36 deletions platform-includes/getting-started-complete/javascript.astro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
<PlatformSection notSupported={["javascript.cloudflare"]}>

### Install the Sentry SDK

Install and add the Sentry integration using the `astro` CLI:
Expand All @@ -14,8 +16,6 @@ yarn astro add @sentry/astro
pnpm astro add @sentry/astro
```

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

<OnboardingOption optionId="profiling">

Next, install the Profiling package using your preferred package manager:
Expand All @@ -38,21 +38,35 @@ pnpm add @sentry/profiling-node

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

Next, install Sentry's Cloudflare SDK using your favorite package manager:
### Install the Sentry SDKs

Install both `@sentry/astro` and `@sentry/cloudflare`:

```bash {tabTitle:npm}
npm install @sentry/astro @sentry/cloudflare
```

```bash {tabTitle:yarn}
yarn add @sentry/astro @sentry/cloudflare
```

<PlatformContent includePath="getting-started-install" />
```bash {tabTitle:pnpm}
pnpm add @sentry/astro @sentry/cloudflare
```

</PlatformSection>

## Step 2: Configure

### Apply Instrumentation to Your App
<PlatformSection supported={["javascript.cloudflare"]}>

Register the Sentry integration in your `astro.config.mjs` file:
### Wrangler Configuration

<PlatformSection supported={["javascript.cloudflare"]}>
<PlatformContent includePath="getting-started-config" />

Start by following [Astro's Cloudflare deployment guide](https://docs.astro.build/en/guides/deploy/cloudflare/). Add the Sentry integration to your config, alongside the Cloudflare adapter.
### Register the Sentry Integration

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:

```javascript {filename:astro.config.mjs}
import { defineConfig } from "astro/config";
Expand All @@ -65,10 +79,16 @@ export default defineConfig({
});
```

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.

</PlatformSection>

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

### Apply Instrumentation to Your App

Register the Sentry integration in your `astro.config.mjs` file:

```javascript {filename:astro.config.mjs}
import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";
Expand Down Expand Up @@ -209,41 +229,38 @@ For Astro versions below `3.5.2`, you need to manually add server instrumentatio

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

<Include name="cloudflare-pages-middleware-intro.mdx" />
Create a `sentry.server.config.(ts|js)` file in the root of your project. In this file, import and initialize Sentry for the server:

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

export const onRequest = [
// Make sure Sentry is the first middleware
Sentry.sentryPagesPlugin((context) => ({
dsn: "___PUBLIC_DSN___",
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
// 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

// Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
// Learn more at
// https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ 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

// Optionally capture action formData attributes with errors.
// This requires `sendDefaultPii` set to true as well.
captureActionFormDataKeys: {
key_x: true,
key_y: true,
},
})),
// Add more middlewares here
];
// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
});
```

### Configure Cloudflare for Sentry
<Alert level="warning" title="Production Configuration via Environment Variables">

<PlatformContent includePath="getting-started-config" />
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>

</PlatformSection>

Expand Down Expand Up @@ -405,7 +422,7 @@ Our next recommended steps for you are:

- Continue to <PlatformLink to="/configuration">customize your configuration</PlatformLink>
- Learn how to <PlatformLink to="/usage">manually capture errors</PlatformLink>
- Learn more about [deploying Astro apps to Cloudflare Pages](/platforms/javascript/guides/cloudflare/frameworks/astro/)
- Learn more about [deploying Astro apps to Cloudflare](/platforms/javascript/guides/cloudflare/frameworks/astro/)
- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts

</PlatformSection>
Expand Down
Loading