unplugin-sentry

v1.1.2

Published

2 months ago

Sentry plugin for webpack, vite, rollup, nuxt .etc.

Downloads

0High
0Medium
0Low

kricsleo

unplugin plugin vite webpack rollup nuxt sentry sourcemap

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.config.ts
import unpluginSentry from 'unplugin-sentry/vite'

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

Example: playground/vite

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

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

Example: playground/rollup

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

Example: playground/webpack

This module works for Webpack >= 3

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

Example: playground/nuxt

This module works for both Nuxt 2 and Nuxt Vite

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

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 updateSENTRY_ORGenv variable. | | project |string | ❌ | - | Project Project slug. This value will updateSENTRY_PROJECTenv variable. | | authToken |string | ❌ | - | Authentication token for API, interchangeable with apiKey. This value will updateSENTRY_AUTH_TOKENenv 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](#sourcemapoptions) | ❌ | - | Sourcemap options. | | deploy | [DeployOptions](#deployoptions) | ❌ | - | Deploy options. | | commits | [CommitsOptions](#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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme