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
• Next.js
• Webpack
• Laravel Mix (legacy Webpack plugin)
• Manually uploading sourcemaps

Vite

When using Vite (v5, v6, v7, or v8) to build your front-end code, you can use Flare's Vite plugin.

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

npm install @flareapp/vite
# or
yarn add @flareapp/vite
# or
pnpm add @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 flareSourcemaps from '@flareapp/vite';

export default defineConfig({
    plugins: [
        flareSourcemaps({
            apiKey: 'YOUR PROJECT KEY HERE',
        }),
    ],
});

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

@flareapp/vite: Uploading 12 sourcemap files to Flare.
@flareapp/vite: 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.
• The plugin automatically enables hidden sourcemaps in your Vite build configuration when uploading is active. You don't need to set build.sourcemap yourself — it's handled for you. If you've already set a custom sourcemap option, the plugin will respect it.
• 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.
• You can skip sourcemap uploads entirely by setting the SKIP_SOURCEMAPS=true environment variable.

Vite plugin options

Next.js

When using Next.js (v13+), you can use Flare's Next.js plugin to upload client-side sourcemaps after each production build.

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

npm install @flareapp/nextjs
# or
yarn add @flareapp/nextjs
# or
pnpm add @flareapp/nextjs

Next, wrap your Next.js config with withFlareSourcemaps in next.config.mjs:

import { withFlareSourcemaps } from '@flareapp/nextjs';

export default withFlareSourcemaps({
    // your normal Next.js config
}, {
    apiKey: 'YOUR PROJECT KEY HERE',
});

Finally, run next build to confirm that sourcemaps are uploaded. You should see the following lines in the output:

@flareapp/webpack: Uploading 4 sourcemap(s) to Flare.
@flareapp/webpack: Successfully uploaded all sourcemaps to Flare.

Integration notes

• The plugin automatically enables productionBrowserSourceMaps in your Next.js config (unless you explicitly set it to false).
• Sourcemaps are uploaded for client-side bundles only. Server-side bundles are skipped.
• The plugin removes .map files from the build output by default, so sourcemaps are not served publicly. You can override this with removeSourcemaps: false.
• The plugin passes your project's API token and a sourcemap version identifier to the JavaScript client via webpack's DefinePlugin. This way, flare.light() works without having to pass in your API key.

Next.js plugin options

Webpack

If you're using Webpack 5, you can use Flare's Webpack plugin.

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

npm install @flareapp/webpack
# or
yarn add @flareapp/webpack
# or
pnpm add @flareapp/webpack

Next, add the plugin to your webpack.config.js file and enable sourcemaps:

const { FlareWebpackPlugin } = require('@flareapp/webpack');

module.exports = {
    // ...
    devtool: 'hidden-source-map',
    plugins: [
        new FlareWebpackPlugin({
            apiKey: 'YOUR PROJECT KEY HERE',
        }),
    ],
};

Integration notes

• The plugin passes your project's API token to the JavaScript client by setting a global variable via webpack's DefinePlugin. This way, flare.light() works without having to pass 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 with the runInDevelopment option.

Webpack plugin options

Laravel Mix (legacy)

If you're using Laravel Mix, you can use the legacy Webpack plugin.

npm install @flareapp/flare-webpack-plugin-sourcemap --dev

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');

Note: If you are migrating from Laravel Mix to a modern webpack 5 setup, consider switching to the new @flareapp/webpack plugin instead.

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)"
}

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');