\n\n# Sentry Esbuild Plugin\n\n[](https://www.npmjs.com/package/@sentry/esbuild-plugin)\n[](https://www.npmjs.com/package/@sentry/esbuild-plugin)\n[](https://www.npmjs.com/package/@sentry/esbuild-plugin)\n\n> An esbuild plugin that provides source map and release management support for Sentry.\n\n## Installation\n\nUsing npm:\n\n```bash\nnpm install @sentry/esbuild-plugin --save-dev\n```\n\nUsing yarn:\n\n```bash\nyarn add @sentry/esbuild-plugin --dev\n```\n\nUsing pnpm:\n\n```bash\npnpm add @sentry/esbuild-plugin --save-dev\n```\n\n## Example\n\n```js\n// esbuild.config.js\nconst { sentryEsbuildPlugin } = require(\"@sentry/esbuild-plugin\");\n\nrequire(\"esbuild\").build({\n sourcemap: true, // Source map generation must be turned on\n plugins: [\n // Put the Sentry esbuild plugin after all other plugins\n sentryEsbuildPlugin({\n org: process.env.SENTRY_ORG,\n project: process.env.SENTRY_PROJECT,\n\n // Auth tokens can be obtained from https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/\n authToken: process.env.SENTRY_AUTH_TOKEN,\n }),\n ],\n});\n```\n\n### Multi-Project Configuration\n\nIf you want to upload the same source maps to multiple Sentry projects:\n\n```js\n// esbuild.config.js\nconst { sentryEsbuildPlugin } = require(\"@sentry/esbuild-plugin\");\n\nrequire(\"esbuild\").build({\n sourcemap: true,\n plugins: [\n sentryEsbuildPlugin({\n org: process.env.SENTRY_ORG,\n project: [\"frontend-team-a\", \"frontend-team-b\", \"frontend-team-c\"],\n authToken: process.env.SENTRY_AUTH_TOKEN,\n }),\n ],\n});\n```\n\nOr via environment variable:\n\n```bash\nSENTRY_PROJECT=frontend-team-a,frontend-team-b,frontend-team-c\n```\n\n## Options\n\n- [`org`](#org)\n- [`project`](#project)\n- [`authToken`](#authtoken)\n- [`url`](#url)\n- [`headers`](#headers)\n- [`debug`](#debug)\n- [`silent`](#silent)\n- [`errorHandler`](#errorhandler)\n- [`telemetry`](#telemetry)\n- [`disable`](#disable)\n- [`sourcemaps`](#sourcemaps)\n - [`assets`](#sourcemapsassets)\n - [`ignore`](#sourcemapsignore)\n - [`rewriteSources`](#sourcemapsrewritesources)\n - [`resolveSourceMap`](#sourcemapsresolvesourcemap)\n - [`filesToDeleteAfterUpload`](#sourcemapsfilestodeleteafterupload)\n - [`disable`](#sourcemapsdisable)\n- [`release`](#release)\n - [`name`](#releasename)\n - [`inject`](#releaseinject)\n - [`create`](#releasecreate)\n - [`finalize`](#releasefinalize)\n - [`dist`](#releasedist)\n - [`vcsRemote`](#releasevcsremote)\n - [`setCommits`](#releasesetcommits)\n - [`deploy`](#releasedeploy)\n - [`cleanArtifacts`](#releasecleanartifacts)\n - [`uploadLegacySourcemaps`](#releaseuploadlegacysourcemaps)\n- [`bundleSizeOptimizations`](#bundlesizeoptimizations)\n - [`excludeDebugStatements`](#bundlesizeoptimizationsexcludedebugstatements)\n - [`excludeTracing`](#bundlesizeoptimizationsexcludetracing)\n - [`excludeReplayShadowDom`](#bundlesizeoptimizationsexcludereplayshadowdom)\n - [`excludeReplayIframe`](#bundlesizeoptimizationsexcludereplayiframe)\n - [`excludeReplayWorker`](#bundlesizeoptimizationsexcludereplayworker)\n\n- [`moduleMetadata`](#modulemetadata)\n- [`applicationKey`](#applicationkey)\n- [`_experiments`](#_experiments)\n - [`injectBuildInformation`](#_experimentsinjectbuildinformation)\n\n### `org`\n\nType: `string`\n\nThe slug of the Sentry organization associated with the app.\n\nThis value can also be specified via the `SENTRY_ORG` environment variable.\n\n### `project`\n\nType: `string | string[]`\n\nThe slug of the Sentry project associated with the app. You can also provide an array of project slugs to upload source maps to multiple projects with the same release.\n\nThis value can also be specified via the `SENTRY_PROJECT` environment variable. To specify multiple projects via the environment variable, separate them with commas: `SENTRY_PROJECT=project1,project2,project3`.\n\n### `authToken`\n\nType: `string`\n\nThe authentication token to use for all communication with Sentry.\nCan be obtained from https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/.\n\nThis value can also be specified via the `SENTRY_AUTH_TOKEN` environment variable.\n\nCheck out the docs on organization tokens: https://docs.sentry.io/product/accounts/auth-tokens/#organization-auth-tokens\n\n### `url`\n\nType: `string`\n\nThe base URL of your Sentry instance. Use this if you are using a self-hosted or Sentry instance other than sentry.io.\n\nThis value can also be set via the SENTRY_URL environment variable.\n\nDefaults to https://sentry.io/, which is the correct value for SaaS customers.\n\n### `headers`\n\nType: `Record`\n\nAdditional headers to send with every outgoing request to Sentry.\n\n### `debug`\n\nType: `boolean`\n\nEnable debug information logs during build-time. Enabling this will give you, for example, logs about source maps. This option also propagates the debug flag to the Sentry CLI by setting the `SENTRY_LOG_LEVEL` environment variable to `\"debug\"` if it's not already set. If you have explicitly set `SENTRY_LOG_LEVEL`, this option will be ignored. Defaults to `false`.\n\n### `silent`\n\nType: `boolean`\n\nSuppresses all build logs (all log levels, including errors). Defaults to `false`.\n\n### `errorHandler`\n\nType: `(err: Error) => void`\n\nWhen an error occurs during release creation or sourcemaps upload, the plugin will call this function.\n\nBy default, the plugin will simply throw an error, thereby stopping the bundling process. If an `errorHandler` callback is provided, compilation will continue, unless an error is thrown in the provided callback.\n\nTo allow compilation to continue but still emit a warning, set this option to the following:\n\n```\nerrorHandler: (err) => {\n console.warn(err);\n}\n```\n\n\n### `telemetry`\n\nType: `boolean`\n\nIf this flag is `true`, internal plugin errors and performance data will be sent to Sentry. It will not collect any sensitive or user-specific data.\n\nAt Sentry, we like to use Sentry ourselves to deliver faster and more stable products. We're very careful of what we're sending. We won't collect anything other than error and high-level performance data. We will never collect your code or any details of the projects in which you're using this plugin.\n\nDefaults to `true`.\n\n### `disable`\n\nType: `boolean`\n\nCompletely disables all functionality of the plugin. Defaults to `false`.\n\n### `sourcemaps`\n\n\n\nOptions related to source maps upload and processing.\n### `sourcemaps.assets`\n\nType: `string | string[]`\n\nA glob or an array of globs that specify the build artifacts and source maps that will be uploaded to Sentry.\n\nThe globbing patterns must follow the implementation of the `glob` package: https://www.npmjs.com/package/glob#glob-primer\n\nIf this option is not specified, the plugin will try to upload all JavaScript files and source map files that are created during build.\n\nUse the `debug` option to print information about which files end up being uploaded.\n\n### `sourcemaps.ignore`\n\nType: `string | string[]`\n\nA glob or an array of globs that specifies which build artifacts should not be uploaded to Sentry.\n\nThe globbing patterns must follow the implementation of the `glob` package: https://www.npmjs.com/package/glob#glob-primer\n\nUse the `debug` option to print information about which files end up being uploaded.\n\nDefault: `[]`\n\n### `sourcemaps.rewriteSources`\n\nType: `(source: string, map: any, context?: { mapDir: string }) => string`\n\nHook to rewrite the `sources` field inside the source map before being uploaded to Sentry. Does not modify the actual source map. Effectively, this modifies how files inside the stacktrace will show up in Sentry.\n\nThe `context.mapDir` parameter provides the directory path of the source map file, which is useful for resolving relative source paths (e.g. `path.resolve(context.mapDir, source)`).\n\nDefaults to making all sources relative to `process.cwd()` while building.\n\n### `sourcemaps.resolveSourceMap`\n\nType: `(artifactPath: string, sourceMappingUrl: string | undefined) => string | undefined | Promise`\n\nHook to customize source map file resolution.\n\nThe hook is called with the absolute path of the build artifact and the value of the `//# sourceMappingURL=`\ncomment, if present. The hook should then return an absolute path (or a promise that resolves to one) indicating\nwhere to find the artifact's corresponding source map file. If no path is returned or the returned path doesn't\nexist, the standard source map resolution process will be used.\n\nThe standard process first tries to resolve based on the `//# sourceMappingURL=` value (it supports `file://`\nurls and absolute/relative paths). If that path doesn't exist, it then looks for a file named\n`${artifactName}.map` in the same directory as the artifact.\n\nNote: This is mostly helpful for complex builds with custom source map generation. For example, if you put source\nmaps into a separate directory and rewrite the `//# sourceMappingURL=` comment to something other than a relative\ndirectory, sentry will be unable to locate the source maps for a given build artifact. This hook allows you to\nimplement the resolution process yourself.\n\nUse the `debug` option to print information about source map resolution.\n\n\n### `sourcemaps.filesToDeleteAfterUpload`\n\nType: `string | string[] | Promise`\n\nA glob, an array of globs or a promise resolving a glob or array of globs that specifies the build artifacts that should be deleted after the artifact upload to Sentry has been completed.\n\nNote: If you pass in a Promise that resolves to a string or array, the plugin will await the Promise and use the resolved value globs. This is useful if you need to dynamically determine the files to delete. Some higher-level Sentry SDKs or options use this feature (e.g., SvelteKit).\n\nThe globbing patterns must follow the implementation of the `glob` package: https://www.npmjs.com/package/glob#glob-primer\n\nUse the `debug` option to print information about which files end up being deleted.\n\n### `sourcemaps.disable`\n\nType: `boolean`\n\nIf this flag is `true`, any functionality related to source maps will be disabled.\n\nDefaults to `false`.\n\n### `release`\n\n\n\nOptions related to managing the Sentry releases for a build.\n\nMore info: https://docs.sentry.io/product/releases/\n### `release.name`\n\nType: `string`\n\nUnique identifier for the release you want to create.\n\nThis value can also be specified via the `SENTRY_RELEASE` environment variable.\n\nDefaults to automatically detecting a value for your environment. This includes values for Cordova, Heroku, AWS CodeBuild, CircleCI, Xcode, and Gradle, and otherwise uses the git `HEAD`'s commit SHA (the latter requires access to git CLI and for the root directory to be a valid repository).\n\nIf no `name` is provided and the plugin can't automatically detect one, no release will be created.\n\n### `release.inject`\n\nType: `boolean`\n\nWhether the plugin should inject release information into the build for the SDK to pick it up when sending events. (recommended)\n\nDefaults to `true`.\n\n### `release.create`\n\nType: `boolean`\n\nWhether the plugin should create a release on Sentry during the build.\n\nNote that a release may still appear in Sentry even if this is value is `false` because any Sentry event that has a release value attached will automatically create a release. (for example via the `inject` option)\n\nDefaults to `true`.\n\n### `release.finalize`\n\nType: `boolean`\n\nWhether to automatically finalize the release. The release is finalized by adding an end timestamp after the build ends.\n\nDefaults to `true`.\n\n### `release.dist`\n\nType: `string`\n\nUnique distribution identifier for the release. Used to further segment the release.\n\nUsually your build number.\n\n### `release.vcsRemote`\n\nType: `string`\n\nVersion control system (VCS) remote name.\n\nThis value can also be specified via the `SENTRY_VSC_REMOTE` environment variable.\n\nDefaults to 'origin'.\n\n### `release.setCommits`\n\n\n\nConfiguration for associating the release with its commits in Sentry.\n\nSet to `false` to disable commit association.\n\nDefaults to `{ auto: true }`.\n### `release.setCommits.previousCommit`\n\nType: `string`\n\nThe commit before the beginning of this release (in other words, the last commit of the previous release).\n\nDefaults to the last commit of the previous release in Sentry.\n\nIf there was no previous release, the last 10 commits will be used.\n\n### `release.setCommits.ignoreMissing`\n\nType: `boolean`\n\nIf the flag is to `true` and the previous release commit was not found in the repository, the plugin creates a release with the default commits count instead of failing the command.\n\nDefaults to `false`.\n\n### `release.setCommits.ignoreEmpty`\n\nType: `boolean`\n\nIf this flag is set, the setCommits step will not fail and just exit silently if no new commits for a given release have been found.\n\nDefaults to `false`.\n\n### `release.setCommits.auto`\n\nType: `boolean`\n\nAutomatically sets `commit` and `previousCommit`. Sets `commit` to `HEAD` and `previousCommit` as described in the option's documentation.\n\nIf you set this to `true`, manually specified `commit` and `previousCommit` options will be overridden. It is best to not specify them at all if you set this option to `true`.\n\n### `release.setCommits.repo`\n\nType: `string`\n\nThe full repo name as defined in Sentry.\n\nRequired if the `auto` option is not set to `true`.\n\n### `release.setCommits.commit`\n\nType: `string`\n\nThe current (last) commit in the release.\n\nRequired if the `auto` option is not set to `true`.\n\n### `release.deploy`\n\nType: `DeployOptions | false`\n\nConfiguration for adding deployment information to the release in Sentry.\n\nSet to `false` to disable automatic deployment detection and creation (e.g., when deploying on Vercel).\n### `release.deploy.env`\n\nType: `string`\n\nEnvironment for this release. Values that make sense here would be `production` or `staging`.\n\n### `release.deploy.started`\n\nType: `number | string`\n\nDeployment start time in Unix timestamp (in seconds) or ISO 8601 format.\n\n### `release.deploy.finished`\n\nType: `number | string`\n\nDeployment finish time in Unix timestamp (in seconds) or ISO 8601 format.\n\n### `release.deploy.time`\n\nType: `number`\n\nDeployment duration (in seconds). Can be used instead of started and finished.\n\n### `release.deploy.name`\n\nType: `string`\n\nHuman readable name for the deployment.\n\n### `release.deploy.url`\n\nType: `string`\n\nURL that points to the deployment.\n\n### `release.cleanArtifacts`\n\nType: `boolean`\n\nRemove all previously uploaded artifacts for this release on Sentry before the upload.\n\nDefaults to `false`.\n\n**Deprecation Notice:** `cleanArtifacts` is deprecated and will does currently not do anything. Historically it was needed since uploading the same artifacts twice was not allowed. Nowadays, when uploading artifacts with the same name more than once to the same release on Sentry, Sentry will prefer the most recent artifact for source mapping.\n\n### `release.uploadLegacySourcemaps`\n\nType: `string | IncludeEntry | Array`\n\nLegacy method of uploading source maps. (not recommended unless necessary)\nOne or more paths that should be scanned recursively for sources.\n\nEach path can be given as a string or an object with more specific options.\n\nThe modern version of doing source maps upload is more robust and way easier to get working but has to inject a very small snippet of JavaScript into your output bundles.\nIn situations where this leads to problems (e.g subresource integrity) you can use this option as a fallback.\n\nPlease note that this option will not interact with any settings provided in the `sourcemaps` option. Using `uploadLegacySourcemaps` is a completely separate upload mechanism we provide for backwards-compatibility.\n\nThe `IncludeEntry` type looks as follows:\n\n```ts\ntype IncludeEntry = {\n /**\n * One or more paths to scan for files to upload.\n */\n paths: string[];\n\n /**\n * One or more paths to ignore during upload.\n * Overrides entries in ignoreFile file.\n *\n * Defaults to `['node_modules']` if neither `ignoreFile` nor `ignore` is set.\n */\n ignore?: string | string[];\n\n /**\n * Path to a file containing list of files/directories to ignore.\n *\n * Can point to `.gitignore` or anything with the same format.\n */\n ignoreFile?: string;\n\n /**\n * Array of file extensions of files to be collected for the file upload.\n *\n * By default the following file extensions are processed: js, map, jsbundle and bundle.\n */\n ext?: string[];\n\n /**\n * URL prefix to add to the beginning of all filenames.\n * Defaults to '~/' but you might want to set this to the full URL.\n *\n * This is also useful if your files are stored in a sub folder. eg: url-prefix '~/static/js'.\n */\n urlPrefix?: string;\n\n /**\n * URL suffix to add to the end of all filenames.\n * Useful for appending query parameters.\n */\n urlSuffix?: string;\n\n /**\n * When paired with the `rewrite` option, this will remove a prefix from filename references inside of\n * sourcemaps. For instance you can use this to remove a path that is build machine specific.\n * Note that this will NOT change the names of uploaded files.\n */\n stripPrefix?: string[];\n\n /**\n * When paired with the `rewrite` option, this will add `~` to the `stripPrefix` array.\n *\n * Defaults to `false`.\n */\n stripCommonPrefix?: boolean;\n\n /**\n * Determines whether sentry-cli should attempt to link minified files with their corresponding maps.\n * By default, it will match files and maps based on name, and add a Sourcemap header to each minified file\n * for which it finds a map. Can be disabled if all minified files contain sourceMappingURL.\n *\n * Defaults to true.\n */\n sourceMapReference?: boolean;\n\n /**\n * Enables rewriting of matching source maps so that indexed maps are flattened and missing sources\n * are inlined if possible.\n *\n * Defaults to true\n */\n rewrite?: boolean;\n\n /**\n * When `true`, attempts source map validation before upload if rewriting is not enabled.\n * It will spot a variety of issues with source maps and cancel the upload if any are found.\n *\n * Defaults to `false` as this can cause false positives.\n */\n validate?: boolean;\n};\n```\n\n\n\n### `bundleSizeOptimizations`\n\n\n\nOptions for bundle size optimizations by excluding certain features.\n### `bundleSizeOptimizations.excludeDebugStatements`\n\nType: `boolean`\n\nExclude debug statements from the bundle, thus disabling features like the SDK's `debug` option.\n\nIf set to `true`, the plugin will attempt to tree-shake (remove) any debugging code within the Sentry SDK during the build.\nNote that the success of this depends on tree-shaking being enabled in your build tooling.\n\nDefaults to `false`.\n\n### `bundleSizeOptimizations.excludeTracing`\n\nType: `boolean`\n\nExclude tracing functionality from the bundle, thus disabling features like performance monitoring.\n\nIf set to `true`, the plugin will attempt to tree-shake (remove) code within the Sentry SDK that is related to tracing and performance monitoring.\nNote that the success of this depends on tree-shaking being enabled in your build tooling.\n\n**Notice:** Do not enable this when you're using any performance monitoring-related SDK features (e.g. `Sentry.startTransaction()`).\n\nDefaults to `false`.\n\n### `bundleSizeOptimizations.excludeReplayShadowDom`\n\nType: `boolean`\n\nExclude Replay Shadow DOM functionality from the bundle.\n\nIf set to `true`, the plugin will attempt to tree-shake (remove) code related to the Sentry SDK's Session Replay Shadow DOM recording functionality.\nNote that the success of this depends on tree-shaking being enabled in your build tooling.\n\nThis option is safe to be used when you do not want to capture any Shadow DOM activity via Sentry Session Replay.\n\nDefaults to `false`.\n\n### `bundleSizeOptimizations.excludeReplayIframe`\n\nType: `boolean`\n\nExclude Replay iFrame functionality from the bundle.\n\nIf set to `true`, the plugin will attempt to tree-shake (remove) code related to the Sentry SDK's Session Replay `iframe` recording functionality.\nNote that the success of this depends on tree-shaking being enabled in your build tooling.\n\nYou can safely do this when you do not want to capture any `iframe` activity via Sentry Session Replay.\n\nDefaults to `false`.\n\n### `bundleSizeOptimizations.excludeReplayWorker`\n\nType: `boolean`\n\nExclude Replay worker functionality from the bundle.\n\nIf set to `true`, the plugin will attempt to tree-shake (remove) code related to the Sentry SDK's Session Replay's Compression Web Worker.\nNote that the success of this depends on tree-shaking being enabled in your build tooling.\n\n**Notice:** You should only use this option if you manually host a compression worker and configure it in your Sentry Session Replay integration config via the `workerUrl` option.\n\nDefaults to `false`.\n\n\n### `moduleMetadata`\n\nType: `Record | (args: { org?: string; project?: string; release?: string; }) => Record`\n\nMetadata that should be associated with the built application.\n\nThe metadata is serialized and can be looked up at runtime from within the SDK (for example in the `beforeSend`, event processors, or the transport), allowing for custom event filtering logic or routing of events.\n\nMetadata can either be passed directly or alternatively a callback can be provided that will be called with the following parameters:\n\n- `org`: The organization slug.\n- `project`: The project slug.\n- `release`: The release name.\n\n### `applicationKey`\n\nType: `string`\n\nA key which will embedded in all the bundled files. The SDK will be able to use the key to apply filtering rules, for example using the `thirdPartyErrorFilterIntegration`.\n\n### `_experiments`\n\nType: `string`\n\nOptions that are considered experimental and subject to change. This option does not follow semantic versioning and may change in any release.\n### `_experiments.injectBuildInformation`\n\nType: `boolean`\n\nIf set to true, the plugin will inject an additional `SENTRY_BUILD_INFO` variable. This contains information about the build, e.g. dependencies, node version and other useful data.\n\nDefaults to `false`.\n\n\n\n### Configuration File\n\nAs an additional configuration method, the Sentry esbuild plugin will pick up environment variables configured inside a `.env.sentry-build-plugin` file located in the current working directory when building your app.\n\n## More information\n\n- [Sentry Documentation](https://docs.sentry.io/quickstart/)\n- [Sentry Discord](https://discord.gg/Ww9hbqr)\n- [Sentry Stackoverflow](http://stackoverflow.com/questions/tagged/sentry)\n","readmeFilename":"README.md"}
![\"Sentry\"](\"https://sentry-brand.storage.googleapis.com/sentry-wordmark-dark-280x84.png\")
\n \n