Add documentation

README.md

@@ -16,6 +16,18 @@ npm install --save-dev vite-plugin-bugsnag
 
 ## Usage
 
+### Build reporter plugin
+
+Reports your build to BugSnag. This plugin hooks into the `buildEnd` event once all output files have been generated by the Vite compiler. If anything causes the compilation to fail before this step, the build report will not be sent.
+
+Please see our [documentation](https://docs.bugsnag.com/build-integrations/vite/#reporting-builds) for further details.
+
+### Sourcemap uploader plugin
+
+Upload your application's sourcemap(s) to BugSnag. When Vite is done producing output, this plugin detects sourcemaps for any output chunks and uploads them to BugSnag.
+
+Please see our [documentation](https://docs.bugsnag.com/build-integrations/vite/#uploading-source-maps) for further details.
+
 ## Support
 
 - [Search open and closed issues](https://github.com/bugsnag/vite-plugin-bugsnag/issues?q=is%3Aissue) issues for similar problems

src/build-reporter-plugin.ts

@@ -1,10 +1,13 @@
 import Bugsnag from '@bugsnag/cli'
 import type { Plugin } from 'vite'
+import type { BuildReporterConfig } from './config'
+import getLogLevel from './get-log-level'
 
 const LOG_PREFIX = '[BugsnagBuildReporterPlugin]'
 
-export function BugsnagBuildReporterPlugin (configOptions: BugsnagBuildReporterPluginOptions): Plugin {
+export function BugsnagBuildReporterPlugin (configOptions: BuildReporterConfig): Plugin {
   const buildOptions = getBuildOptions(configOptions)
+  const target = configOptions.path || process.cwd()
 
   return {
     name: 'vite-plugin-bugsnag-build-reporter',
@@ -18,7 +21,7 @@ export function BugsnagBuildReporterPlugin (configOptions: BugsnagBuildReporterP
 
       logger.info(`${LOG_PREFIX} creating build for version "${buildOptions.versionName}" using the bugsnag-cli`)
 
-      Bugsnag.CreateBuild(buildOptions, process.cwd())
+      Bugsnag.CreateBuild(buildOptions, target)
         .then((output) => {
           output.split('\n').forEach((line) => {
             logger.info(`${LOG_PREFIX} ${line}`)
@@ -33,10 +36,10 @@ export function BugsnagBuildReporterPlugin (configOptions: BugsnagBuildReporterP
   }
 }
 
-function getBuildOptions (configOptions: BugsnagBuildReporterPluginOptions) {
+function getBuildOptions (configOptions: BuildReporterConfig) {
   const buildOptions = {
     apiKey: configOptions.apiKey,
-    versionName: configOptions.appVersion,
+    versionName: configOptions.appVersion || process.env.npm_package_version,
     autoAssignRelease: configOptions.autoAssignRelease,
     builderName: configOptions.builderName,
     metadata: configOptions.metadata,
@@ -45,7 +48,7 @@ function getBuildOptions (configOptions: BugsnagBuildReporterPluginOptions) {
     repository: configOptions.sourceControl?.repository,
     revision: configOptions.sourceControl?.revision,
     buildApiRootUrl: configOptions.endpoint,
-    logLevel: configOptions.logLevel
+    logLevel: getLogLevel(configOptions.logLevel)
   }
 
   for (const [key, value] of Object.entries(buildOptions)) {
@@ -56,25 +59,3 @@ function getBuildOptions (configOptions: BugsnagBuildReporterPluginOptions) {
 
   return buildOptions
 }
-
-export interface BugsnagBuildReporterPluginOptions {
-  apiKey: string
-  appVersion: string // versionName
-  endpoint?: string // buildApiRootUrl
-  autoAssignRelease?: boolean
-  builderName?: string
-  metadata?: object
-  releaseStage?: string
-  sourceControl?: {
-    provider?: string
-    repository?: string
-    revision?: string
-  }
-  logLevel?: string
-  logger?: {
-    debug: (message: string) => void
-    info: (message: string) => void
-    warn: (message: string) => void
-    error: (message: string) => void
-  }
-}

src/config.ts

@@ -0,0 +1,34 @@
+interface Logger {
+  debug: (message: string) => void
+  info: (message: string) => void
+  warn: (message: string) => void
+  error: (message: string) => void
+}
+
+export interface BaseConfig {
+  apiKey: string
+  appVersion?: string
+  path?: string
+  endpoint?: string
+  logLevel?: 'debug' | 'info' | 'warn' | 'error'
+  logger?: Logger
+}
+
+export interface BuildReporterConfig extends BaseConfig {
+  autoAssignRelease?: boolean
+  builderName?: string
+  metadata?: object
+  releaseStage?: string
+  sourceControl?: {
+    provider?: string
+    repository?: string
+    revision?: string
+  }
+}
+
+export interface SourceMapUploaderConfig extends BaseConfig {
+  base?: string // baseURL
+  codeBundleId?: string
+  projectRoot?: string
+  overwrite?: boolean
+}

src/get-log-level.ts

@@ -0,0 +1,9 @@
+// re-map the log level option to match the bugsnag-cli log level
+const getLogLevel = (logLevel: string | undefined) => {
+  if (logLevel === 'error') {
+    return 'fatal'
+  }
+  return logLevel
+}
+
+export default getLogLevel

src/source-map-uploader-plugin.ts

@@ -1,82 +1,62 @@
 import Bugsnag from '@bugsnag/cli'
 import { join, resolve } from 'path'
+import getLogLevel from './get-log-level'
 import isValidUrl from './is-valid-url'
 
 import type { Plugin } from 'vite'
+import type { SourceMapUploaderConfig } from './config'
 
 const LOG_PREFIX = '[BugsnagSourceMapUploaderPlugin]'
 
-interface Logger {
-  debug: (message: string) => void
-  info: (message: string) => void
-  warn: (message: string) => void
-  error: (message: string) => void
-}
-
-export interface ConfigOptions {
-  apiKey: string
-  appVersion: string
-  base?: string
-  endpoint?: string
-  codeBundleId?: string
-  logger?: Logger
-  mode?: string
-  projectRoot?: string
-  overwrite?: boolean
-  logLevel?: 'info' | 'warn' | 'fatal' | 'debug'
-}
-
-export function BugsnagSourceMapUploaderPlugin (configOptions: ConfigOptions): Plugin {
+export function BugsnagSourceMapUploaderPlugin (configOptions: SourceMapUploaderConfig): Plugin {
   if (typeof configOptions.apiKey !== 'string' || configOptions.apiKey.length < 1) {
     throw new Error(`${LOG_PREFIX} "apiKey" is required`)
   }
 
-  const enableSourcemapUploads = configOptions.mode === 'production' || process.env.NODE_ENV === 'production'
-
   return {
     name: 'vite-plugin-bugsnag-source-map-uploader',
     async writeBundle (options, bundle) {
       const logger = configOptions.logger || this.environment.logger
       const projectRoot = configOptions.projectRoot || this.environment.config.root
       const outputDir = options.dir || projectRoot
       const baseUrl = configOptions.base || this.environment.config.base
+      const versionName = configOptions.appVersion || process.env.npm_package_version || 'unknown'
       const validBaseUrl = isValidUrl(baseUrl)
+      const target = configOptions.path || outputDir
 
-      if (enableSourcemapUploads) {
-        const uploads = []
-        for (const [, value] of Object.entries(bundle)) {
-          if (value.type === 'chunk' && !!value.sourcemapFileName) {
-            const bundle = resolve(outputDir, value.fileName)
-            const bundleUrl = validBaseUrl ? new URL(value.fileName, baseUrl).toString() : join(baseUrl, value.fileName)
-            const sourceMap = value.sourcemapFileName ? join(outputDir, value.sourcemapFileName) : undefined
-            const uploadOptions = getUploadOptions(bundle, bundleUrl, sourceMap, projectRoot, configOptions)
-            uploads.push(uploadOptions)
-          }
+      const uploads = []
+      for (const [, value] of Object.entries(bundle)) {
+        if (value.type === 'chunk' && !!value.sourcemapFileName) {
+          const bundle = resolve(outputDir, value.fileName)
+          const bundleUrl = validBaseUrl ? new URL(value.fileName, baseUrl).toString() : join(baseUrl, value.fileName)
+          const sourceMap = value.sourcemapFileName ? join(outputDir, value.sourcemapFileName) : undefined
+          const uploadOptions = getUploadOptions(bundle, bundleUrl, sourceMap, projectRoot, versionName, configOptions)
+          uploads.push(uploadOptions)
         }
+      }
 
-        logger.info(`${LOG_PREFIX} uploading sourcemaps using the bugsnag-cli`)
+      logger.info(`${LOG_PREFIX} uploading sourcemaps using the bugsnag-cli`)
 
-        const tasks = uploads.map((uploadOptions) => {
-          return Bugsnag.Upload.Js(uploadOptions, outputDir)
-            .then((output) => {
-              output.split('\n').forEach((line) => {
-                logger.info(`${LOG_PREFIX} ${line}`)
-              })
+      const tasks = uploads.map((uploadOptions) => {
+        return Bugsnag.Upload.Js(uploadOptions, target)
+          .then((output) => {
+            output.split('\n').forEach((line) => {
+              logger.info(`${LOG_PREFIX} ${line}`)
             })
-            .catch((err) => {
-              err.toString().split('\n').forEach((line: string) => {
-                logger.error(`${LOG_PREFIX} ${line}`)
-              })
+          })
+          .catch((err) => {
+            err.toString().split('\n').forEach((line: string) => {
+              logger.error(`${LOG_PREFIX} ${line}`)
             })
-        })
+          })
+      })
 
-        await Promise.all(tasks)
-      }
+      await Promise.all(tasks)
     }
   }
 }
 
-function getUploadOptions (bundle: string, bundleUrl: string, sourceMap: string | undefined, projectRoot: string, configOptions: ConfigOptions) {
+function getUploadOptions (bundle: string, bundleUrl: string, sourceMap: string | undefined, projectRoot: string, versionName: string, configOptions: SourceMapUploaderConfig) {
   const uploadOptions = {
     apiKey: configOptions.apiKey, // The BugSnag API key for the application.
     bundle, // Path to the minified JavaScript file that the source map relates to.
@@ -85,9 +65,9 @@ function getUploadOptions (bundle: string, bundleUrl: string, sourceMap: string
     projectRoot, // The path to strip from the beginning of source file names referenced in stacktraces on the BugSnag dashboard.
     sourceMap, // Path to the source map file. This usually has the .min.js extension.
     uploadApiRootUrl: configOptions.endpoint, // The upload server hostname, optionally containing port number.
-    versionName: configOptions.appVersion, // The version of the app that the source map applies to.
+    versionName, // The version of the app that the source map applies to.
     overwrite: configOptions.overwrite, // Whether to ignore and overwrite existing uploads with same identifier, rather than failing if a matching file exists.
-    logLevel: configOptions.logLevel // Sets the level of logging to debug, info, warn or fatal.
+    logLevel: getLogLevel(configOptions.logLevel) // Sets the level of logging to debug, info, warn or fatal.
   }
 
   for (const [key, value] of Object.entries(uploadOptions)) {

test/source-map-uploader-plugin.test.ts

@@ -5,6 +5,8 @@ import { describe, expect, test, vi } from 'vitest'
 import { BugsnagSourceMapUploaderPlugin } from '../src/source-map-uploader-plugin'
 import cleanBuildDir from './lib/clean-build-dir'
 
+import { version } from '../package.json'
+
 vi.mock('@bugsnag/cli', () => ({
     default: {
         Upload: {
@@ -44,8 +46,7 @@ describe('BugsnagSourceMapUploaderPlugin', () => {
         const plugin = BugsnagSourceMapUploaderPlugin({
             logger: mockLogger,
             apiKey: 'test-api',
-            appVersion: '1.0.0',
-            mode: 'production'
+            appVersion: '1.0.0'
         })
 
         const fixturesPath = resolve(__dirname, 'fixtures/basic')
@@ -81,7 +82,7 @@ describe('BugsnagSourceMapUploaderPlugin', () => {
         sourcemapUpload.mockClear()
     })
 
-    test('should use the relative filepath for bundleUrl is base is not provided in config', async () => {
+    test('should use the relative filepath for bundleUrl if base is not provided in config', async () => {
         const mockLogger = {
             info: vi.fn(),
             error: vi.fn(),
@@ -91,9 +92,7 @@ describe('BugsnagSourceMapUploaderPlugin', () => {
 
         const plugin = BugsnagSourceMapUploaderPlugin({
             logger: mockLogger,
-            apiKey: 'test-api',
-            appVersion: '1.0.0',
-            mode: 'production'
+            apiKey: 'test-api'
         })
 
         const fixturePath = resolve(__dirname, 'fixtures/basic')
@@ -120,7 +119,7 @@ describe('BugsnagSourceMapUploaderPlugin', () => {
                 bundle: bundlePath,
                 projectRoot: fixturePath,
                 sourceMap: sourceMapPath,
-                versionName: '1.0.0'
+                versionName: version
             },
             outputDir
         )
@@ -139,8 +138,7 @@ describe('BugsnagSourceMapUploaderPlugin', () => {
         const plugin = BugsnagSourceMapUploaderPlugin({
             logger: mockLogger,
             apiKey: 'test-api',
-            appVersion: '1.0.0',
-            mode: 'production'
+            appVersion: '1.0.0'
         })
 
         const fixturePath = resolve(__dirname, 'fixtures/basic')