vite-plugin-appsignal

Plugin to integrate Vite ⚡️ with Appsignal Sourcemap API

Vite plugin acts as interface to Appsignal Sourcemap API

It's a port of the vite-plugin-sentry for Vite and therefore heavily inspired by it.

Install

NPM

npm i -D vite-plugin-appsignal

Yarn

yarn add -D vite-plugin-appsignal

PNPM

pnpm add -D vite-plugin-appsignal

Configuration

If you using Typescript - you can use ViteAppsignalPluginOptions type for better configuration experience with autocomplete.

Example config:

// vite.config.ts
// other declarations
import type { ViteAppsignalPluginOptions } from 'vite-plugin-appsignal'
import Appsignal from 'vite-plugin-appsignal'

/*
  Configure appsignal plugin
*/
const appsignalConfig: ViteAppsignalPluginOptions = {
  pushApiKey: '<ORGANIZATION_WIDE_APPSIGNAL_PUSH_API_KEY>',
  appName: 'my_app_backend',
  appId: '<APPSIGNAL_APP_ID>',
  apiKey: '<APPSIGNAL_API_KEY_FOR_APP_AND_ENV>', // injected as apiKey into import.meta.env.VITE_PLUGIN_APPSIGNAL_CONFIG
  personalApiToken: '<PERSONAL_APPSIGNAL_API_TOKEN>',
  revision: '1.0',
  env: 'production',
  urlPrefix: 'https://my-app.com/assets', // Or `urlPrefixes: [...]` for multiple source files under different domains/prefixes
  sourceMaps: {
    include: ['./dist/assets'],
    ignore: ['node_modules'],
  },
}

export default defineConfig({
  // other options
  plugins: [Appsignal(appsignalConfig)],
  build: {
    // required: tells vite to create source maps
    sourcemap: true,
  }
})

Share config with Appsignal client library

To correctly work with Appsignal, you need to add a revision to your project.

You can expose the revision used by vite-plugin-appsignal into your application using thge Vite feature of "virtual modules".

To do so, you need to add some lines of code:

// import virtual module
// i would recommend doing it at entry point script (e.g. main.js)
import 'virtual:vite-plugin-appsignal/appsignal-config'
import Appsignal from '@appsignal/javascript'

// now you can use this variable like so
const { revision, apiKey: key } = import.meta.env.VITE_PLUGIN_APPSIGNAL_CONFIG;

// use it in appsignal init
new Appsignal({
  // other appsignal options
  revision,
  key,
})

// also, these settings exposed to globalThis object
// so you can get them from window object:
const revision = window.VITE_PLUGIN_APPSIGNAL_CONFIG.revision

TypeScript

To get type information for the virtual module or import meta env, you can add vite-plugin-appsignal/client to your types array in tsconfig.json.

{
  "types": [
    "vite-plugin-appsignal/client"
  ]
}

Also you can use reference in your typescript code like below:

///<reference types="vite-plugin-appsignal/client"/>

FAQ

Delete generated source maps after upload

There are no built-in options to clean sourcemaps.

While i recommend to use CI, you can also use tools like rimraf in your npm scripts to drop any unnecessary files after build was complete:

// package.json
{
  "scripts": {
    // delete all js map files when built
    "build": "vite build && rimraf dist/**/*.js.map"
  }
}

List of available options

Here are the list of all plugin options:

Legend:

❌ - NOT required

⚠️ - NOT required in plugin config, but MUST be set (for example, using .appsignalclirc file)

✅ - Required

Option	Type	Required	Default value	Description
pushApiKey	string	⚠️		The organization-wide authentication token to use for all communication with Appsignal.
appName	string	⚠️		The slug of the Appsignal project associated with the app.
appId	string	⚠️		The app ID for this specific app and environment in Appsignal. Visible in the Appsignal Dashboard URL (directly after /sites/)
personalApiToken	string	⚠️		Personal Appsignal API token. Can be retrieved here
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
apiKey	string	❌		The API key token for this specific app and environment. Will be injected as import.meta.env.VITE_PLUGIN_APPSIGNAL_CONFIG.apiKey
revision	string	❌		Unique name for revision. Defaults to short commit SHA from git (requires access to GIT and root directory to be repo)
env	string	❌	'production'	Environment value for build
urlPrefix	string	(✅)		URL prefix to add to the beginning of all filenames. 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 'https://my-app.com/static/js'. Can be overriden by setting urlPrefixes
urlPrefixes	string[]	(✅)		URL prefixes to add to the beginning of all filenames. 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 'https://my-app.com/static/js'. Overrides setting urlPrefix
sourceMaps	AppsignalCliUploadSourceMapsOptions	✅		Sourcemaps settings, see details below

sourceMaps settings

With sourceMaps you can configure how sourcemaps will be processed

Option	Type	Required	Description
include	string | string[]	✅	One or more paths that Appsignal CLI should scan recursively for sources. It will upload all .map files and match associated .js files.
ignore	string[]	❌	Paths to ignore during upload. Overrides entries in ignoreFile file. If neither ignoreFile nor ignore is present, defaults to ['node_modules'].

Testing

This repo uses jest for unit-testing. Run yarn test to run all tests.

Contributors

Joe Pantazidis 💻

Christian Breidler 💻