From 16255e941ccff8257b714df0be3e8212d9ffbea2 Mon Sep 17 00:00:00 2001 From: ikenfin Date: Fri, 7 Apr 2023 00:15:22 +0400 Subject: [PATCH] add legacyErrorHandlingMode docs --- README.md | 118 ++++++++++++++++++++++++++---------------------------- 1 file changed, 57 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 607e7e8..14df1c1 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,12 @@ It's a port of official [Sentry webpack plugin](https://github.com/getsentry/sen It's fully written on Typescript and there is some differences in configuration, described below, but we mostly follow [@sentry/cli](https://github.com/getsentry/sentry-cli) types. - - ## Install ```sh yarn add -D vite-plugin-sentry ``` - - ## Configuration If you using Typescript - you can use **ViteSentryPluginOptions** type for better configuration experience with autocomplete. @@ -39,6 +35,7 @@ const sentryConfig: ViteSentryPluginOptions = { org: 'my_org', project: 'my_project', release: '1.0', + // legacyErrorHandlingMode: true, <- warn about sentry errors instead of fail deploy: { env: 'production' }, @@ -62,11 +59,16 @@ export default defineConfig({ }) ``` +#### Possible breaking change! + +From version `1.2.0` we have changed default error handling. Now if Sentry report error while uploading sourcemaps - we crash whole build process instead of just print warning. This was done to prevent calling next to `&&` operator on uploading error. + +You can enable legacy mode using `legacyErrorHandlingMode: true` in plugin config. + ## Wiki Check project [wiki on github](https://github.com/ikenfin/vite-plugin-sentry/wiki) to get more information. - ## Share config with Sentry client library To correctly work with Sentry, you need to add a **release** to your project. Same about **dist** option: your uploaded sourcemaps and client sentry initialization must have same release/dist to make sentry correct recognize and bind sourcemaps to logged errors. @@ -98,6 +100,7 @@ const release = window.VITE_PLUGIN_SENTRY_CONFIG.release ``` ## TypeScript + To get type information for the virtual module or import meta env, you can add `vite-plugin-sentry/client` to your `types` array in tsconfig.json. ```javascript @@ -114,8 +117,6 @@ Also you can use `reference` in your typescript code like below: /// ``` - - ## Common how to: #### Delete generated source maps after upload (#1) @@ -134,14 +135,10 @@ While i recommend to use CI, you can also use tools like rimraf in your npm scri } ``` - - #### Cannot install on Windows This plugin relies on @sentry/cli tool, which requires VCRedist to be installed. Please check [#8](https://github.com/ikenfin/vite-plugin-sentry/issues/8) for details. - - ## List of available options Here are the list of all plugin options: @@ -154,70 +151,69 @@ Here are the list of all plugin options: ✅ - Required - - -| Option | Type | Required | Default value | Description | -| -------------------- | -------------------------------- | -------- | -------------------- | ------------------------------------------------------------ | -| debug | boolean | ❌ | false | Show debug messages during run | -| skipEnvironmentCheck | boolean | ❌ | false | By default plugin will be enabled only for production builds. Set this option to `true` to skip environment checks | -| dryRun | boolean | ❌ | false | Run sentry in dry mode - will only prints all steps | -| url | string | ❌ | 'https://sentry.io/' | The base URL of your Sentry instance. | -| authToken | string | ⚠️ | '' | 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). | -| org | string | ⚠️ | '' | The slug of the Sentry organization associated with the app. | -| project | string | ⚠️ | '' | The slug of the Sentry project associated with the app. | -| vcsRemote | string | ❌ | 'origin' | The name of the remote in the version control system. | -| configFile | string | ❌ | '' | Path to sentry cli config file, 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 | -| release | string | ❌ | | Unique name for release. Defaults to sentry-cli releases propose version (requires access to GIT and root directory to be repo) | -| finalize | boolean | ❌ | false | Determines whether processed release should be automatically finalized after artifacts upload | -| silent | boolean | ❌ | false | If true, all sentry-cli logs are suppressed | -| deploy | SentryCliNewDeployOptions | ❌ | | Sentry release deployment settings, see details below | -| sourceMaps | SentryCliUploadSourceMapsOptions | ✅ | | Sourcemaps settings, see details below | -| setCommits | SentryCliCommitsOptions | ❌ | | Adds commits to sentry, see details below | +| Option | Type | Required | Default value | Description | +| ----------------------- | -------------------------------- | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| legacyErrorHandlingMode | boolean | ❌ | false | When `true` - all sentry uploading errors will be printed as warnings, build process will not be failed, vite will return exit code 0 | +| debug | boolean | ❌ | false | Show debug messages during run | +| skipEnvironmentCheck | boolean | ❌ | false | By default plugin will be enabled only for production builds. Set this option to `true` to skip environment checks | +| dryRun | boolean | ❌ | false | Run sentry in dry mode - will only prints all steps | +| url | string | ❌ | 'https://sentry.io/' | The base URL of your Sentry instance. | +| authToken | string | ⚠️ | '' | 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). | +| org | string | ⚠️ | '' | The slug of the Sentry organization associated with the app. | +| project | string | ⚠️ | '' | The slug of the Sentry project associated with the app. | +| vcsRemote | string | ❌ | 'origin' | The name of the remote in the version control system. | +| configFile | string | ❌ | '' | Path to sentry cli config file, 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 | +| release | string | ❌ | | Unique name for release. Defaults to sentry-cli releases propose version (requires access to GIT and root directory to be repo) | +| finalize | boolean | ❌ | false | Determines whether processed release should be automatically finalized after artifacts upload | +| silent | boolean | ❌ | false | If true, all sentry-cli logs are suppressed | +| deploy | SentryCliNewDeployOptions | ❌ | | Sentry release deployment settings, see details below | +| sourceMaps | SentryCliUploadSourceMapsOptions | ✅ | | Sourcemaps settings, see details below | +| setCommits | SentryCliCommitsOptions | ❌ | | Adds commits to sentry, see details below | #### deploy settings With `deploy` you can configure sentry cli to send deployment info. Here is a table of settings: -| Option | Type | Required | Description | -| -------- | ------ | -------- | ------------------------------------------------------------ | -| env | string | ✅ | Environment value for release. For example `production` | -| started | number | ❌ | UNIX timestamp for deployment start | -| finished | number | ❌ | UNIX timestamp for deployment finish | -| time | number | ❌ | Deployment duration in seconds. Can be used instead of `started` and `finished`. | -| name | string | ❌ | Human-readable name for this deployment | -| url | string | ❌ | URL that points to the deployment | +| Option | Type | Required | Description | +| -------- | ------ | -------- | ------------------------------------------------------------------------------------ | +| env | string | ✅ | Environment value for release. For example `production` | +| started | number | ❌ | UNIX timestamp for deployment start | +| finished | number | ❌ | UNIX timestamp for deployment finish | +| time | number | ❌ | Deployment duration in seconds. Can be used instead of `started` and `finished`. | +| name | string | ❌ | Human-readable name for this deployment | +| url | string | ❌ | URL that points to the deployment | #### sourceMaps settings With `sourceMaps` you can configure how sourcemaps will be processed -| Option | Type | Required | Description | -| ------------------ | ------------------ | -------- | ------------------------------------------------------------ | -| include | string \| string[] | ✅ | One or more paths that Sentry CLI should scan recursively for sources. It will upload all `.map` files and match associated `.js` files. | -| dist | string | ❌ | Unique identifier for the distribution, used to further segment your release. Usually your build number | -| ignore | string[] | ❌ | Paths to ignore during upload. Overrides entries in `ignoreFile` file. If neither `ignoreFile` nor `ignore` is present, defaults to `['node_modules']`. | -| ignoreFile | string | ❌ | Path to a file containing list of files/directories to ignore. Can point to `.gitignore` or anything with the same format. | -| rewrite | boolean | ❌ | Enables rewriting of matching source maps so that indexed maps are flattened and missing sources are inlined if possible. Defaults to `true` | -| sourceMapReference | boolean | ❌ | Prevents the automatic detection of sourcemap references. Defaults to `false`. | -| stripPrefix | string[] | ❌ | When paired with `rewrite`, will remove a prefix from uploaded filenames. Useful for removing a path that is build-machine-specific. | -| stripCommonPrefix | boolean | ❌ | When paired with `rewrite`, will add `~` to the `stripPrefix` array. Defaults to `false` | -| validate | boolean | ❌ | 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` to prevent false positives canceling upload. | -| urlPrefix | string | ❌ | 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 | ❌ | URL suffix to add to the end of all filenames. Useful for appending query parameters. | -| ext | string[] | ❌ | The file extensions to be considered. By default the following file extensions are processed: `js`, `map`, `jsbundle`, and `bundle`. | +| Option | Type | Required | Description | +| ------------------ | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| include | string\| string[] | ✅ | One or more paths that Sentry CLI should scan recursively for sources. It will upload all `.map` files and match associated `.js` files. | +| dist | string | ❌ | Unique identifier for the distribution, used to further segment your release. Usually your build number | +| ignore | string[] | ❌ | Paths to ignore during upload. Overrides entries in `ignoreFile` file. If neither `ignoreFile` nor `ignore` is present, defaults to `['node_modules']`. | +| ignoreFile | string | ❌ | Path to a file containing list of files/directories to ignore. Can point to `.gitignore` or anything with the same format. | +| rewrite | boolean | ❌ | Enables rewriting of matching source maps so that indexed maps are flattened and missing sources are inlined if possible. Defaults to `true` | +| sourceMapReference | boolean | ❌ | Prevents the automatic detection of sourcemap references. Defaults to `false`. | +| stripPrefix | string[] | ❌ | When paired with `rewrite`, will remove a prefix from uploaded filenames. Useful for removing a path that is build-machine-specific. | +| stripCommonPrefix | boolean | ❌ | When paired with `rewrite`, will add `~` to the `stripPrefix` array. Defaults to `false` | +| validate | boolean | ❌ | 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` to prevent false positives canceling upload. | +| urlPrefix | string | ❌ | 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 | ❌ | URL suffix to add to the end of all filenames. Useful for appending query parameters. | +| ext | string[] | ❌ | The file extensions to be considered. By default the following file extensions are processed:`js`, `map`, `jsbundle`, and `bundle`. | #### setCommits settings With `setCommits` you can configure -| Option | Type | Required | Description | -| -------------- | ------- | -------------------- | ------------------------------------------------------------ | -| repo | string | ✅`if auto === false` | The full git repo name as defined in Sentry. Required if `auto` option is not `true`, otherwise optional. | -| commit | string | ✅`if auto === false` | The current (most recent) commit in the release. Required if `auto` option is not `true`, otherwise optional. | -| previousCommit | string | ❌ | The last commit of the previous release. Defaults to the most recent commit of the previous release in Sentry, or if no previous release is found, 10 commits back from `commit`. | -| auto | boolean | ❌ | Automatically set `commit` and `previousCommit`. Defaults `commit` to `HEAD` and `previousCommit` as described above. Overrides other options | -| 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 have been found. | +| Option | Type | Required | Description | +| -------------- | ------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| repo | string | ✅`if auto === false` | The full git repo name as defined in Sentry. Required if `auto` option is not `true`, otherwise optional. | +| commit | string | ✅`if auto === false` | The current (most recent) commit in the release. Required if `auto` option is not `true`, otherwise optional. | +| previousCommit | string | ❌ | The last commit of the previous release. Defaults to the most recent commit of the previous release in Sentry, or if no previous release is found, 10 commits back from `commit`. | +| auto | boolean | ❌ | Automatically set `commit` and `previousCommit`. Defaults `commit` to `HEAD` and `previousCommit` as described above. Overrides other options | +| 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 have been found. | ## Tests @@ -240,6 +236,6 @@ Thank you to all contributors and users of this plugin. Knowing that so many peo Give a ⭐️ if this project helped you! +--- -*** _This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)_