kricsleo/unplugin-sentry

README

unplugin-sentry

All-in-one plugin for Sentry, supports webpack, vite, rollup, nuxt .ect.

It's used to upload sourcemap and release your project to Sentry ([What's Sentry?](https://sentry.io/welcome/)).

Features

🪜 Supports multiple bundlers and frameworks - including webpack, vite, rollup, nuxt and so on.
✨ Auto-detect configs depending on current environment - config as less as you need
🧹 Auto clean local soucemap files after upload (For security) - both *.js.map and *.css.map.
🍬 Optional runtime provided - easy to init Sentry at runtime.

Install

npm i unplugin-sentry -D

Vite

// vite.config.ts
import unpluginSentry from 'unplugin-sentry/vite'

export default defineConfig({
  plugins: [
    unpluginSentry({ /* options */ }),
  ],
})

Example: playground/vite

Rollup

// rollup.config.js
import unpluginSentry from 'unplugin-sentry/rollup'

export default {
  plugins: [
    unpluginSentry({ /* options */ }),
  ],
}

Example: playground/rollup

Webpack

// webpack.config.js
module.exports = {
  /* ... */
  plugins: [
    require('unplugin-sentry/webpack')({ /* options */ })
  ]
}

Example: playground/webpack

This module works for Webpack >= 3

Nuxt

// nuxt.config.js
export default {
  buildModules: [
    ['unplugin-sentry/nuxt', { /* options */ }],
  ],
}

Example: playground/nuxt

This module works for both Nuxt 2 and Nuxt Vite

Vue CLI

// vue.config.js
module.exports = {
  configureWebpack: {
    plugins: [
      require('unplugin-sentry/webpack')({ /* options */ }),
    ],
  },
}

esbuild

I don't use esbuild for now, so it haven't been tested in esbuild yet. (You can have a try and tell me if it works 👂. )

Runtime Support

Besides uploading sourcemap to Sentry and other publishing works, this plugin also injects a virtual module named virtual-unplugin-sentry-runtime into your project.

It provides some useful meta info when initing Sentry at runtime. For example, when you call Sentry.init({/** options **/}), the environment and release options must match the one you use when uploading sourcemap. So that when debugging the issue in Sentry, the sourcemap can be correctly mapped.

import * as sentryMeta from 'virtual-unplugin-sentry-runtime'

console.log(sentryMeta)
// {
//   ORG: string
//   PROJECT: string
//   ENV: string
//   RELEASE: string
//   DIST: string
//   PUBLISH: boolean
// }

Need TS support for this runtime module? Just add the following config to your tsconfig.json.

{
  "compilerOptions": {
    "types": ["unplugin-sentry/runtime"]
  }
}

Options

Extends from @sentry/cli - SentryCliOptions.

Prop	Type	Required	Default	Description
url	`string`	❌	`https://sentry.io/`	The URL of the Sentry instance you are connecting to. This value will update `SENTRY_URL env variable.
org	`string`	❌	-	Organization slug. This value will update `SENTRY_ORG` env variable.
project	`string`	❌	-	Project Project slug. This value will update `SENTRY_PROJECT` env variable.
authToken	`string`	❌	-	Authentication token for API, interchangeable with apiKey. This value will update `SENTRY_AUTH_TOKEN` env variable.
publish	`boolean`	❌	`false`	If publish project to Sentry. Means to upload soucemap files and release the version to Sentry server. You might want to turn it on only when deploying projects other than locally developing.
release	`string`	❌	-	Release version. Automatically generated from commit hash value if not provided.
shortRelease	`boolean`	❌	`true`	If use short commit hash for automatically generated release version.
cleanLocal	`boolean`	❌	`true`	If remove local sourcemap files (`.js.map` & `.css.map`) after the publish.
cleanArtifacts	`boolean`	❌	`false`	If remove previous artifacts in the same release.
sourcemap	`SourcemapOptions`	❌	-	Sourcemap options.
deploy	`DeployOptions`	❌	-	Deploy options.
commits	`CommitsOptions`	❌	-	Commits options.
finalize	`boolean`	❌	`true`	If finalize a release after the publish.
silent	`boolean`	❌	`false`	If true, all logs are suppressed.
dryRun	`boolean`	❌	`false`	If attempts a dry run. Usually used for debugging which mocks publishing.
configFile	`string`	❌	-	Path of Sentry config file.

SourcemapOptions

Extends from @sentry/cli - SentryCliUploadSourceMapsOptions.

Prop	Type	Required	Default	Description
include	`Array<string \| SourceMapsPathDescriptor>`	❌	- Auto-detectd from current bundler(webpack, vite, rollup and so on).	One or more paths that Sentry CLI should scan recursively for sources. It will upload all .map files and match associated .js files. `type SourceMapsPathDescriptor = Omit<SourcemapOptions, 'include'> & { paths: string[] }`
urlPrefix	`string`	❌	- Auto-detectd from current bundler(webpack, vite, rollup and so on).	This sets an URL prefix at the beginning of all files. This is also useful if your files are stored in a sub folder. BUT REMEMBER TO START WITH `~/`. eg: url-prefix `~/static/js`.
urlSuffix	`string`	❌	-	This sets an URL suffix at the end of all files. Useful for appending query parameters.
ignore	`string[]`	❌	-	One or more paths to ignore during upload. Overrides entries in ignoreFile file.
ignoreFile	`string` \| `null`	❌	-	Path to a file containing list of files/directories to ignore. Can point to .gitignore or anything with same format.
dist	`string`	❌	-	Unique identifier for the distribution, used to further segment your release. Usually your build number.
rewrite	`boolean`	❌	`true`	Enables rewriting of matching sourcemaps so that indexed maps are flattened and missing sources are inlined if possible.
sourceMapReference	`boolean`	❌	-	This prevents the automatic detection of sourcemap references.
stripPrefix	`string[]`	❌	-	When paired with the rewrite option this will remove a prefix from uploaded files. For instance you can use this to remove a path that is build machine specific.
stripCommonPrefix	`boolean`	❌	-	When paired with the rewrite option this will add ~ to the stripPrefix array.
validate	`boolean`	❌	-	This attempts sourcemap validation before upload when rewriting is not enabled. It will spot a variety of issues with source maps and cancel the upload if any are found. This is not enabled by default as this can cause false positives.
ext	`string[]`	❌	-	This sets the file extensions to be considered. By default the following file extensions are processed: js, map, jsbundle and bundle.

DeployOptions

Extends from @sentry/cli - SentryCliNewDeployOptions.

Prop	Type	Required	Default	Description
env	`string`	❌	- Auto-detectd from current bundler(webpack, vite, rollup and so on) and use "process.env.NODE_ENV" as fallback.	Environment for this release. Values that make sense here would be `production` or `staging`.
started	`number` \| `string`	❌	-	Deployment start time in Unix timestamp (in seconds) or ISO 8601 format.
finished	`number` \| `string`	❌	-	Deployment finish time in Unix timestamp (in seconds) or ISO 8601 format.
time	`number`	❌	-	Deployment duration (in seconds). Can be used instead of started and finished.
name	`string`	❌	-	Human readable name for the deployment.
url	`string`	❌	-	URL that points to the deployment.

CommitsOptions

Extends from @sentry/cli - SentryCliCommitsOptions.

Prop	Type	Required	Default	Description
auto	`boolean`	❌	-	Automatically choose the associated commit (uses the current commit). Overrides other setCommit options.
repo	`string`	❌	-	The full repo name as defined in Sentry. Required if auto option is not true.
commit	`string`	❌	-	The current (last) commit in the release. Required if auto option is not true.
previousCommit	`string`	❌	-	The commit before the beginning of this release. If omitted, this will default to the last commit of the previous release in Sentry. If there was no previous release, the last 10 commits will be used.
ignoreMissing	`boolean`	❌	-	When the flag is set and the previous release commit was not found in the repository, will create a release. with the default commits count(or the one specified with `--initial-depth`) instead of failing the command.
ignoreEmpty	`boolean`	❌	-	When the flag is set, command will not fail and just exit silently if no new commits for a given release are found.

License