|
| 1 | +--- |
| 2 | +title: Hono on Cloudflare |
| 3 | +sidebar_title: Quick Start - Cloudflare |
| 4 | +sidebar_order: 0.5 |
| 5 | +description: "Learn how to set up Sentry in your Hono app on Cloudflare Workers and capture your first errors." |
| 6 | +--- |
| 7 | + |
| 8 | +The `@sentry/hono` SDK works as Hono middleware, so you can drop it into your existing Cloudflare Workers app. For Node.js, Bun, and Deno, see the [Hono quick start](/platforms/javascript/guides/hono/). |
| 9 | + |
| 10 | +<PlatformContent includePath="getting-started-prerequisites" /> |
| 11 | + |
| 12 | +<StepConnector selector="h2" showNumbers={true}> |
| 13 | + |
| 14 | +## Install |
| 15 | + |
| 16 | +Choose the features you want to configure, and this guide will show you how: |
| 17 | + |
| 18 | +<OnboardingOptionButtons options={["error-monitoring", "performance"]} /> |
| 19 | + |
| 20 | +<Include name="quick-start-features-expandable" /> |
| 21 | + |
| 22 | +### Install the Sentry SDK |
| 23 | + |
| 24 | +Install `@sentry/hono` together with `@sentry/cloudflare`. The runtime package is a peer dependency that you never import directly, but it must be present and its version must match `@sentry/hono`. |
| 25 | + |
| 26 | +```bash {tabTitle:npm} |
| 27 | +npm install @sentry/hono @sentry/cloudflare |
| 28 | +``` |
| 29 | + |
| 30 | +```bash {tabTitle:yarn} |
| 31 | +yarn add @sentry/hono @sentry/cloudflare |
| 32 | +``` |
| 33 | + |
| 34 | +```bash {tabTitle:pnpm} |
| 35 | +pnpm add @sentry/hono @sentry/cloudflare |
| 36 | +``` |
| 37 | + |
| 38 | +## Configure |
| 39 | + |
| 40 | +### Configure Wrangler |
| 41 | + |
| 42 | +The SDK needs `AsyncLocalStorage`, so set the `nodejs_compat` compatibility flag and a `compatibility_date` of `2024-09-23` or later in your Wrangler configuration: |
| 43 | + |
| 44 | +```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} |
| 45 | +{ |
| 46 | + // Set this to today's date |
| 47 | + "compatibility_date": "{{@inject new Date().toISOString().slice(0, 10) }}", |
| 48 | + "compatibility_flags": ["nodejs_compat"], |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +```toml {tabTitle:Toml} {filename:wrangler.toml} |
| 53 | +# Set this to today's date |
| 54 | +compatibility_date = "{{@inject new Date().toISOString().slice(0, 10) }}" |
| 55 | +compatibility_flags = ["nodejs_compat"] |
| 56 | +``` |
| 57 | + |
| 58 | +### Add the Sentry Middleware |
| 59 | + |
| 60 | +Add the `sentry()` middleware as early as possible in your Hono app, before any route that you want covered: |
| 61 | + |
| 62 | +```typescript {filename:index.ts} |
| 63 | +import { Hono } from "hono"; |
| 64 | +import { sentry } from "@sentry/hono/cloudflare"; |
| 65 | + |
| 66 | +const app = new Hono(); |
| 67 | + |
| 68 | +app.use( |
| 69 | + sentry(app, { |
| 70 | + dsn: "___PUBLIC_DSN___", |
| 71 | + |
| 72 | + // ___PRODUCT_OPTION_START___ performance |
| 73 | + |
| 74 | + // Set tracesSampleRate to 1.0 to capture 100% |
| 75 | + // of spans for tracing. |
| 76 | + tracesSampleRate: 1.0, |
| 77 | + // ___PRODUCT_OPTION_END___ performance |
| 78 | + }) |
| 79 | +); |
| 80 | + |
| 81 | +// Your routes here |
| 82 | + |
| 83 | +export default app; |
| 84 | +``` |
| 85 | + |
| 86 | +To read the DSN from a Worker binding, for example a secret, pass a callback instead of a plain options object. The callback receives the Worker `env`: |
| 87 | + |
| 88 | +```typescript {filename:index.ts} |
| 89 | +import { Hono } from "hono"; |
| 90 | +import { sentry } from "@sentry/hono/cloudflare"; |
| 91 | + |
| 92 | +type Bindings = { SENTRY_DSN: string }; |
| 93 | + |
| 94 | +const app = new Hono<{ Bindings: Bindings }>(); |
| 95 | + |
| 96 | +app.use(sentry(app, (env) => ({ dsn: env.SENTRY_DSN }))); |
| 97 | + |
| 98 | +export default app; |
| 99 | +``` |
| 100 | + |
| 101 | +### Report Unhandled Exceptions |
| 102 | + |
| 103 | +By default, Sentry captures exceptions from Hono's `onError` handler, excluding errors with 3xx or 4xx status codes. No additional configuration is needed for this. |
| 104 | + |
| 105 | +To control which errors are captured, use the <PlatformLink to="/features/error-handler/">`shouldHandleError`</PlatformLink> option. |
| 106 | + |
| 107 | +### Add Readable Stack Traces With Source Maps (Optional) |
| 108 | + |
| 109 | +<PlatformContent |
| 110 | + includePath="getting-started-sourcemaps-short-version" |
| 111 | + platform="javascript.cloudflare" |
| 112 | +/> |
| 113 | + |
| 114 | +### Control the Data You Send to Sentry (Optional) |
| 115 | + |
| 116 | +<PlatformContent includePath="getting-started-data-collection" /> |
| 117 | + |
| 118 | +## Verify Your Setup |
| 119 | + |
| 120 | +<PlatformContent includePath="getting-started-verify" /> |
| 121 | + |
| 122 | +### View Captured Data in Sentry |
| 123 | + |
| 124 | +Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). |
| 125 | + |
| 126 | +<Include name="quick-start-locate-data-expandable" /> |
| 127 | + |
| 128 | +## Next Steps |
| 129 | + |
| 130 | +At this point, you should have Sentry integrated into your Hono application on Cloudflare Workers and already be sending data to your Sentry project. |
| 131 | + |
| 132 | +Now's a good time to customize your setup and look into more advanced topics: |
| 133 | + |
| 134 | +- Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup |
| 135 | +- Learn how to <PlatformLink to="/usage/">manually capture errors</PlatformLink> |
| 136 | +- Explore <PlatformLink to="/features/">Hono-specific features</PlatformLink> like custom error filtering |
| 137 | +- Continue to <PlatformLink to="/configuration/">customize your configuration</PlatformLink> |
| 138 | +- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts |
| 139 | + |
| 140 | +<Expandable permalink={false} title="Are you having problems setting up the SDK?"> |
| 141 | + |
| 142 | +- Find various topics in [Cloudflare troubleshooting](/platforms/javascript/guides/cloudflare/troubleshooting/) |
| 143 | +- [Get support](https://www.sentry.help/en/) |
| 144 | + |
| 145 | +</Expandable> |
| 146 | + |
| 147 | +</StepConnector> |
0 commit comments