From 8b782535d144c26bcf6e16aa90a6bbd3621524ea Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Tue, 24 Feb 2026 11:28:42 +0100 Subject: [PATCH] docs(astro,cloudflare): Update the guide to Astro on Cloudflare Workers --- .../javascript/guides/astro/index.mdx | 2 +- .../guides/cloudflare/frameworks/astro.mdx | 66 ++++++++++++-- .../javascript.astro.mdx | 89 +++++++++++-------- 3 files changed, 114 insertions(+), 43 deletions(-) diff --git a/docs/platforms/javascript/guides/astro/index.mdx b/docs/platforms/javascript/guides/astro/index.mdx index 699f4ee5174f9f..40ba29240c5dc8 100644 --- a/docs/platforms/javascript/guides/astro/index.mdx +++ b/docs/platforms/javascript/guides/astro/index.mdx @@ -20,7 +20,7 @@ You need: 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**. diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx index 7311348cc7c2d2..638681c2dc85af 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx @@ -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 @@ -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. + + + +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. + +```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). + + ## Step 1: Install @@ -23,9 +80,6 @@ You need: ]} /> - + - + diff --git a/platform-includes/getting-started-complete/javascript.astro.mdx b/platform-includes/getting-started-complete/javascript.astro.mdx index dc08647b6af711..babeaba842af94 100644 --- a/platform-includes/getting-started-complete/javascript.astro.mdx +++ b/platform-includes/getting-started-complete/javascript.astro.mdx @@ -1,3 +1,5 @@ + + ### Install the Sentry SDK Install and add the Sentry integration using the `astro` CLI: @@ -14,8 +16,6 @@ yarn astro add @sentry/astro pnpm astro add @sentry/astro ``` - - Next, install the Profiling package using your preferred package manager: @@ -38,21 +38,35 @@ pnpm add @sentry/profiling-node -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 +``` - +```bash {tabTitle:pnpm} +pnpm add @sentry/astro @sentry/cloudflare +``` ## Step 2: Configure -### Apply Instrumentation to Your App + -Register the Sentry integration in your `astro.config.mjs` file: +### Wrangler Configuration - + -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"; @@ -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. + +### 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"; @@ -209,41 +229,38 @@ For Astro versions below `3.5.2`, you need to manually add server instrumentatio - +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 + - +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. + + @@ -405,7 +422,7 @@ Our next recommended steps for you are: - Continue to customize your configuration - Learn how to manually capture errors -- 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