# toucan-js > Cloudflare Workers client for Sentry Latest version **4.1.1** (published 2025-02-28) · MIT license · 0 weekly downloads ## Install ```sh npm install toucan-js pnpm add toucan-js yarn add toucan-js bun add toucan-js ``` ## Health **Score 50/100 (C)** — status: stable. Positive: has types; esm support; no vulnerabilities; high quality score. Warnings: low downloads. Negative: stale. ## Facts | | | |---|---| | Version | 4.1.1 | | Published | 2025-02-28 | | First published | 2020-04-08 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 3 | | Unpacked size | 90.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 457 | | Author | robertcepa@icloud.com | | Maintainers | robertcepa | | Keywords | debugging, errors, exceptions, logging, sentry, toucan, toucan-js, cloudflare, workers, serverless | ## Links - npm: https://www.npmjs.com/package/toucan-js - Repository: https://github.com/robertcepa/toucan-js - Homepage: https://github.com/robertcepa/toucan-js#readme - Issues: https://github.com/robertcepa/toucan-js/issues - npm.io page: https://npm.io/package/toucan-js ## Dependencies (3) - [@sentry/core](https://npm.io/package/@sentry/core.md) 8.9.2 - [@sentry/types](https://npm.io/package/@sentry/types.md) 8.9.2 - [@sentry/utils](https://npm.io/package/@sentry/utils.md) 8.9.2 ## Alternatives - [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads - [log](https://npm.io/package/log.md) — 1.3M weekly downloads - [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads - [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads - [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads ## Recent versions - 4.1.1 (latest) — 2025-02-28 - 4.1.0 — 2025-01-19 - 4.0.0 — 2024-07-02 - 3.4.0 — 2024-04-27 - 3.3.1 — 2023-10-29 - 3.3.0 — 2023-09-23 - 3.2.3 — 2023-08-28 - 3.2.2 — 2023-08-17 - 3.2.1 — 2023-08-03 - 3.2.0 — 2023-07-26 - 3.1.0 — 2022-12-25 - 3.0.0 — 2022-12-06 - 2.7.0 — 2022-09-27 - 2.6.1 — 2022-06-12 - 2.6.0 — 2022-04-17 - … 25 more at https://npm.io/package/toucan-js/versions ## README

Logo

[![npm version](https://img.shields.io/npm/v/toucan-js)](https://www.npmjs.com/package/toucan-js) [![npm version](https://img.shields.io/npm/dw/toucan-js)](https://www.npmjs.com/package/toucan-js) [![npm version](https://img.shields.io/npm/types/toucan-js)](https://www.npmjs.com/package/toucan-js) # toucan-js **Toucan** is a [Sentry](https://docs.sentry.io/) client for [Cloudflare Workers](https://developers.cloudflare.com/workers/) written in TypeScript. - **Reliable**: In Cloudflare Workers isolate model, it is inadvisable to [set or mutate global state within the event handler](https://developers.cloudflare.com/workers/about/how-it-works). Toucan was created with Workers' concurrent model in mind. No race-conditions, no undelivered logs, no nonsense metadata in Sentry. - **Flexible:** Supports `fetch` and `scheduled` Workers, their `.mjs` equivalents, and `Durable Objects`. - **Familiar API:** Follows [Sentry unified API guidelines](https://develop.sentry.dev/sdk/unified-api/). ## Features This SDK provides all options and methods of [ScopeClass](https://github.com/getsentry/sentry-javascript/blob/master/packages/core/src/scope.ts) and additionally: ### Additional constructor options | Option | Type | Description | | ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | context | Context | This can be any object that contains [waitUntil](https://developers.cloudflare.com/workers/about/tips/fetch-event-lifecycle/). It can be [FetchEvent](https://developers.cloudflare.com/workers/runtime-apis/fetch-event), [ScheduledEvent](https://developers.cloudflare.com/workers/runtime-apis/scheduled-event), [DurableObjectState](https://developers.cloudflare.com/workers/runtime-apis/durable-objects), or [.mjs context](https://community.cloudflare.com/t/2021-4-15-workers-runtime-release-notes/261917). | | request | Request | If set, the SDK will send information about incoming requests to Sentry. By default, only the request method and request origin + pathname are sent. If you want to include more data, you need to use `requestDataOptions` option. | | requestDataOptions | RequestDataOptions | Object containing allowlist for specific parts of request. Refer to sensitive data section below. | ### Constructor options overrides #### Transport options On top of base `transportOptions` you can pass additional configuration: | Option | Type | Description | | ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | headers | Record | Custom headers passed to fetch. | | fetcher | typeof fetch | Custom fetch function. This can be useful for tests or when the global `fetch` used by `toucan-js` doesn't satisfy your use-cases. Note that custom fetcher must conform to `fetch` interface. | ### Additional methods - `Toucan.setEnabled(enabled: boolean): void`: Can be used to disable and again enable the SDK later in your code. - `Toucan.setRequestBody(body: unknown): void`: Attaches request body to future events. `body` can be anything serializable. ## Integrations You can use custom integrations to enhance `toucan-js` as you would any other Sentry SDK. Some integrations are provided in various [Sentry packages](https://github.com/getsentry/sentry-javascript/tree/develop/packages), and you can also write your own! To ensure an integration will work properly in `toucan-js`, it must: - not enhance or wrap global runtime methods (such as `console.log`). - not use runtime APIs that aren't available in Cloudflare Workers (NodeJS runtime functions, `window` object, etc...). Supported integrations from [@sentry/core](https://github.com/getsentry/sentry-javascript/tree/develop/packages/core) are re-exported from `toucan-js`: - [dedupeIntegration](https://github.com/getsentry/sentry-javascript/blob/master/packages/integrations/src/dedupe.ts) - [extraErrorDataIntegration](https://github.com/getsentry/sentry-javascript/blob/master/packages/integrations/src/extraerrordata.ts) - [rewriteFramesIntegration](https://github.com/getsentry/sentry-javascript/blob/master/packages/integrations/src/rewriteframes.ts) - [sessionTimingIntegration](https://github.com/getsentry/sentry-javascript/blob/master/packages/integrations/src/sessiontiming.ts) `toucan-js` also provides 2 integrations that are enabled by default, but are provided if you need to reconfigure them: - [linkedErrorsIntegration](src/integrations/linkedErrors.ts) - [requestDataIntegration](src/integrations/requestData.ts) - [zodErrorsIntegration](src/integrations/zod/zoderrors.ts) ### Custom integration example: ```ts import { Toucan, rewriteFramesIntegration } from 'toucan-js'; type Env = { SENTRY_DSN: string; }; export default { async fetch(request, env, context): Promise { const sentry = new Toucan({ dsn: env.SENTRY_DSN, context, request, integrations: [rewriteFramesIntegration({ root: '/' })], }); ... }, } as ExportedHandler; ``` ## Sensitive data By default, Toucan does not send any request data that might contain [PII (Personally Identifiable Information)](https://docs.sentry.io/data-management/sensitive-data/) to Sentry. This includes: - request headers - request cookies - request search params - request body - user's IP address (read from `CF-Connecting-Ip` header) You will need to explicitly allow these data using: - `allowedHeaders` option (array of headers or Regex or boolean) - `allowedCookies` option (array of cookies or Regex or boolean) - `allowedSearchParams` option (array of search params or Regex or boolean) - `allowedIps` option (array of search params or Regex or boolean) These options are available on [RequestData](src/integrations/requestData.ts) integration or `requestDataOptions` option (which is passed down to [RequestData](src/integrations/requestData.ts) automatically). --- _Source: https://npm.io/package/toucan-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._