@sentry/esbuild-plugin

Sentry Esbuild Plugin (WIP)

WARNING: This package is work in progress! Use with caution and do not yet use it in production. We're happy to receive your feedback!

A esbuild plugin that provides release management features for Sentry:

• Sourcemap upload
• Release creation
• Automatic release name discovery (based on CI environment - Vercel, AWS, Heroku, CircleCI, or current Git SHA)
• Automatically association of errors with releases (Release injection)

Installation

Using npm:

$ npm install @sentry/esbuild-plugin --save-dev

Using yarn:

$ yarn add @sentry/esbuild-plugin --dev

Usage

// esbuild.config.js
const sentryEsbuildPlugin = require("@sentry/esbuild-plugin");

require("esbuild").build({
  plugins: [
    sentryEsbuildPlugin({
      include: ".",
      ignore: ["node_modules", "esbuild.config.js"],
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

As an alternative to passing options explicitly, you can also use a .sentryclirc file or environment variables as described in https://docs.sentry.io/product/cli/configuration/.

Configuration

The Sentry Esbuild Plugin takes an options argument with the following properties:

Option	Type	Required	Description
include	string/array/object	required	One or more paths that the plugin should scan recursively for sources. It will upload all .map files and match associated .js files. Other file types can be uploaded by using the ext option. Each path can be given as a string or an object with path-specific options. See table below for details.
org	string	optional	The slug of the Sentry organization associated with the app. Can also be specified via the SENTRY_ORG environment variable.
project	string	optional	The slug of the Sentry project associated with the app. Can also be specified via the SENTRY_PROJECT environment variable.
authToken	string	optional	The authentication token to use for all communication with Sentry. Can be obtained from https://sentry.io/settings/account/api/auth-tokens/. Required scopes: project:releases (and org:read if setCommits option is used). Can also be specified via the SENTRY_AUTH_TOKEN env variable.
url	string	optional	The base URL of your Sentry instance. Use this if you are using a self-hosted or Sentry instance other than sentry.io. This value can also be set via the SENTRY_URL environment variable. Defaults to https://sentry.io/, which is the correct value for SaaS customers.
customHeader	string	optional	A header added to every outgoing network request. The format should be header-key: header-value. This value can also be specified via the CUSTOM_HEADER environment variable.
vcsRemote	string	optional	Version control system remote name. This value can also be specified via the SENTRY_VSC_REMOTE environment variable. Defaults to 'origin'.
release	string	optional	Unique identifier for the release. This value can also be specified via the SENTRY_RELEASE environment variable. Defaults to the output of the sentry-cli releases propose-version command, which automatically detects 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).
dist	string	optional	Unique identifier for the distribution, used to further segment your release. Usually your build number.
entries	array/RegExp/(string | RegExp)[]/function(filePath: string): bool	optional	Filter for bundle entry points that should contain the provided release. This option takes a string, a regular expression, or an array containing strings, regular expressions, or both. It's also possible to provide a filter function that takes the absolute path of a processed entrypoint and should return true if the release should be injected into the entrypoint and false otherwise. String values of this option require a full match with the absolute path of the bundle. By default, the release will be injected into all entry points.
ignoreFile	string	optional	Path to a file containing list of files/directories to ignore. Can point to .gitignore or anything with the same format.
ignore	string/array	optional	One or more paths to ignore during upload. Overrides entries in ignoreFile file. Defaults to ['node_modules'] if neither ignoreFile nor ignore is set.
configFile	string	optional	Path to Sentry CLI config properties, as described in https://docs.sentry.io/product/cli/configuration/#configuration-file. By default, the config file is looked for upwards from the current path, and defaults from ~/.sentryclirc are always loaded.
ext	array	optional	Array of file extensions of files to be collected for the file upload. By default the following file extensions are processed: js, map, jsbundle and bundle.
urlPrefix	string	optional	URL prefix to add to the beginning of all filenames. Defaults to '~/' but you might want to set this to the full URL. This is also useful if your files are stored in a sub folder. eg: url-prefix '~/static/js'.
urlSuffix	string	optional	URL suffix to add to the end of all filenames. Useful for appending query parameters.
validate	boolean	optional	When true, attempts source map validation before upload if rewriting is not enabled. It will spot a variety of issues with source maps and cancel the upload if any are found. Defaults to false as this can cause false positives.
stripPrefix	array	optional	When paired with the rewrite option, this will remove a prefix from filename references inside of sourcemaps. For instance you can use this to remove a path that is build machine specific. Note that this will NOT change the names of uploaded files.
stripCommonPrefix	boolean	optional	When paired with the rewrite option, this will add ~ to the stripPrefix array.
sourceMapReference	boolean	optional	Determines whether sentry-cli should attempt to link minified files with their corresponding maps. By default, it will match files and maps based on name, and add a Sourcemap header to each minified file for which it finds a map. Can be disabled if all minified files contain a sourceMappingURL. Defaults to true.
rewrite	boolean	optional	Enables rewriting of matching source maps so that indexed maps are flattened and missing sources are inlined if possible. Defaults to true
finalize	boolean	optional	Determines if the Sentry release record should be automatically finalized (meaning a date_released timestamp is added) after artifact upload. Defaults to true.
dryRun	boolean	optional	Attempts a dry run (useful for dev environments), making release creation a no-op. Defaults to false.
debug	boolean	optional	Print useful debug information. Defaults to false.
silent	boolean	optional	Suppresses all logs. Defaults to false.
cleanArtifacts	boolean	optional	Remove all the artifacts in the release before the upload. Defaults to false.
errorHandler	function(err: Error): void	optional	When an error occurs during rlease creation or sourcemaps upload, the plugin will call this function. By 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.
setCommits	Object	optional	Associates the release with its commits in Sentry. See table below for details.
deploy	Object	optional	Adds deployment information to the release in Sentry. See table below for details.
injectReleasesMap	boolean	optional	If set to true, the plugin will inject an additional SENTRY_RELEASES variable that maps from {org}@{project} to the release value. This might be helpful for webpack module federation or micro frontend setups. Defaults to false.
telemetry	boolean	optional	If set to true, internal plugin errors and performance data will be sent to Sentry. At 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. Defaults to true.

options.include:

Option	Type	Required	Description
paths	string[]	required	One or more paths to scan for files to upload.
ignoreFile	string	optional	See above.
ignore	string/string[]	optional	See above.
ext	array	optional	See above.
urlPrefix	string	optional	See above.
urlSuffix	string	optional	See above.
stripPrefix	array	optional	See above.
stripCommonPrefix	boolean	optional	See above.
sourceMapReference	boolean	optional	See above.
rewrite	boolean	optional	See above.

Example:

// esbuild.config.js
const sentryEsbuildPlugin = require("@sentry/esbuild-plugin");

require("esbuild").build({
  plugins: [
    sentryEsbuildPlugin({
      // ...
      include: [
        {
          paths: ["./packages"],
          urlPrefix: "~/path/to/packages",
        },
        {
          paths: ["./client"],
          urlPrefix: "~/path/to/client",
        },
      ],
    }),
  ],
});

options.setCommits:

Option	Type	Required	Description
repo	string	see notes	The full git repo name as defined in Sentry. Required if the auto option is not true, otherwise optional.
commit	string	see notes	The current (most recent) commit in the release. Required if the auto option is not true, otherwise optional.
previousCommit	string	optional	The commit before the beginning of this release (in other words, the last commit of the previous release). Defaults to the last commit of the previous release in Sentry. If there was no previous release, the last 10 commits will be used.
auto	boolean	optional	Automatically sets commit and previousCommit. Sets commit to HEAD and previousCommit as described in the option's documentation. If 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.
ignoreMissing	boolean	optional	If 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. Defaults to false.

options.deploy:

Option	Type	Required	Description
env	string	required	Environment value for the release, for example production or staging.
started	number	optional	Deployment start time in Unix timestamp (in seconds) or ISO 8601 format.
finished	number	optional	Deployment finish time in Unix timestamp (in seconds) or ISO 8601 format.
time	number	optional	Deployment duration in seconds. Can be used instead of started and finished.
name	string	optional	Human-readable name for this deployment.
url	string	optional	URL that points to the deployment.

You can find more information about these options in our official docs: https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps.

More information

• Sentry Documentation
• Troubleshooting Sourcemaps
• Sentry CLI
• Sentry Discord
• Sentry Stackoverflow