Resolving bundled code

When you bundle your frontend code for production (using Webpack, Vite, Gulp, Babel…), it will get minified and transformed and ultimately won't look like the original code any more. This causes the code snippets attached to error reports to be malformed as well. The solution to this problem is uploading a sourcemap.

Using one of our plugins, you can automatically upload the sourcemaps produced by your bundler. We'll then use them to format your error reports to show a clean stacktrace that resembles your original code.

The following options are available:

• Vite
• Webpack
• Laravel Mix (using Webpack plugin)
• Manually uploading sourcemaps

Vite

When using Vite to build your front-end code, you can use Flare's Vite plugin (link to npm).

To get started, run one of the following commands to install the plugin:

yarn add @flareapp/vite
# or
npm install @flareapp/vite

Next, add the plugin to your vite.config.js file and fill in your Flare project's public key:

import {defineConfig} from 'vite';
import flareSourcemapUploader from '@flareapp/vite';

export default defineConfig({
    plugins: [
        flareSourcemapUploader({
            key: 'YOUR PROJECT PUBLIC KEY HERE'
        }),
    ],
});

Finally, run the vite build command to confirm that sourcemaps are generated. You should see the following lines in the output:

@flareapp/flare-vite-plugin-sourcemaps: Uploading 12 sourcemap files to Flare.
@flareapp/flare-vite-plugin-sourcemaps: Successfully uploaded sourcemaps to Flare.

Integration notes

• The plugin also passes your project's API token to the JavaScript client by setting a global variable. This way, when initializing the Flare JS client, you can just run flare.light() without having to pass in your API key.
• By default, the plugin will not upload your sourcemaps to Flare when compiling in Vite's development mode (). You can override this behaviour using the runInDevelopment option.

Vite plugin options

• key: string (required): your Flare project's public API key
• base: string: the base path of built output (defaults to Vite's base path)
• runInDevelopment: boolean: whether to upload sourcemaps when NODE_ENV=development or when running the dev server (defaults to false)
• version: string: the sourcemap version (defaults to a fresh uuid per build)
• removeSourcemaps: boolean: whether to remove the sourcemaps after uploading them (defaults to false). Comes in handy when you want to upload sourcemaps to Flare but don't want them published in your build.

Webpack or Laravel Mix

If you're using Laravel Mix or Webpack (v3, v4 or v5), you can use our Webpack plugin (link to npm).

To get started, run one of the following commands to install the plugin:

yarn add @flareapp/flare-webpack-plugin-sourcemap --dev
# or
npm install @flareapp/flare-webpack-plugin-sourcemap --dev

Next, modify your webpack.config.js or webpack.mix.js file to enable sourcemaps and the plugin. You can find example configurations for Laravel Mix and Webpack below. The configuration must only be added to one of these configuration files, otherwise it may lead to unexpected behaviour.

The only required parameter for the plugin is a configuration object with a key property. Enter your Flare project's public key here.

The plugin also passes your project's API token to the JavaScript client by setting a global variable. This way, when initializing the Flare JS client, you can just run flare.light() without passing in your API key.

By default, the plugin will not upload your sourcemaps to Flare when compiling in Webpack's development or watch modes. You can override this behaviour using the runInDevelopment option.

Laravel Mix

In a Laravel Mix build, you can also use the aforementioned Webpack plugin. Follow the steps above to install it. Then, add the following to your webpack.mix.js file:

const FlareWebpackPluginSourcemap = require("@flareapp/flare-webpack-plugin-sourcemap");

mix
    // ...
    .webpackConfig({
        plugins: [ new FlareWebpackPluginSourcemap({ key: "your-project-key" }) ],
    })
    .sourceMaps(true, 'hidden-source-map');

The configuration is the same as for the Webpack plugin.

Webpack

webpack.config.js

const FlareWebpackPluginSourcemap = require("@flareapp/flare-webpack-plugin-sourcemap");

module.exports = {
    // ...
    plugins: [ new FlareWebpackPluginSourcemap({ key: "your-project-key" }) ],
    devtool: "hidden-source-map",
};

Webpack plugin options

You can pass some options to the plugin, in the same object as the key:

Option	Default	Description
key	empty	(required) This is your project's public token. The plugin will automatically pass it to the Flare client through a global variable.
runInDevelopment	false	Setting this value to true will cause the plugin to upload your sourcemaps even when compiling in webpack's dev mode. This will still prevent the plugin from uploading sourcemaps when compiling in watch mode.
versionId	empty	The plugin generates a random ID for each build, so that Flare knows which incoming reports are linked to which sourcemaps. Using this config option, you can set an ID you decide for yourself e.g. when deploying your code on multiple servers. Make sure it's different for each build.
removeSourcemaps	false	If you'd rather not deploy your sourcemaps to your production environment, you can add removeSourcemaps: true to remove them before the build completes.
debug	false	If your bundler is running into issues while uploading the sourcemaps to Flare, set debug: true to get more verbose output.

Manually uploading sourcemaps

We don't have any UI in the Flare dashboard for uploading your sourcemaps. You can, however, upload the sourcemap manually or with a custom script that runs after building your assets.

Send a POST request to https://flareapp.io/api/sourcemaps with the following JSON payload:

{
    "key": "your-project-key",
    "version_id": "versionId",
    "relative_filename": "/js/app.js",
    "sourcemap": "base64 string of gzipped sourcemap (this sounds more complicated than it is)"
}

key

The public API key of your project in Flare.

version_id

This has to be a project-unique string that is also included in your bundled code as a global environment variable FLARE_SOURCEMAP_VERSION. Alternatively, you can set the sourcemapVersion property of the Flare client instance.

In the webpack plugin, we use the uuid4 spec to generate a unique string for each build.

relative_filename

The relative path to the file this sourcemap belongs to, starting from the root of your domain.

sourcemap

A base64 string of your gzipped sourcemap. Here's how you could generate it using the built-in Zlib library for Node.js, but the commandline gzip tool should work just as well:

const zlib = require('zlib');

const base64GzipSourcemap = zlib.deflateRawSync(sourcemap.content).toString('base64');