New Webpack and Next.js plugins for Flare

We just shipped @flareapp/webpack and @flareapp/nextjs, two build plugins that upload sourcemaps to Flare after each production build. The Vite plugin has been around for a while. These two bring that same setup to webpack and Next.js.

Before this, the old @flareapp/flare-webpack-plugin-sourcemap handled uploads for webpack 4. You could also use it with Laravel Mix, which was webpack-based. If you were on Next.js, you could wire it in manually since Next.js uses webpack under the hood, but there was no dedicated wrapper for it. Both new plugins replace that old package: @flareapp/webpack targets webpack 5, and @flareapp/nextjs takes care of the Next.js-specific config like enabling productionBrowserSourceMaps.

Webpack: one plugin in your config

Add FlareWebpackPlugin to your webpack config:

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

module.exports = {
    devtool: 'source-map',
    plugins: [
        new FlareWebpackPlugin({
            apiKey: 'YOUR_FLARE_API_KEY',
        }),
    ],
};

After each production build, the plugin finds every .js.map file in the output, compresses them, and uploads them to Flare. Development and watch mode builds are skipped by default.

It also injects your API key and a sourcemap version identifier into the build via webpack's DefinePlugin, so flare.light() picks up both values without any extra config.

Next.js: wrap your config

Next.js uses webpack under the hood but doesn't expose it directly. @flareapp/nextjs wraps your existing config and adds the webpack plugin for you:

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

export default withFlareSourcemaps(
    {
        // your normal Next.js config
    },
    {
        apiKey: process.env.FLARE_KEY,
    },
);

This turns on productionBrowserSourceMaps (Next.js doesn't emit .map files by default), adds the Flare plugin to client builds only, and removes .map files from the output after upload. Server bundles are skipped since they never run in the browser and aren't relevant to the stack traces Flare processes.

If you've explicitly set productionBrowserSourceMaps: false, the wrapper leaves it alone.

Removing sourcemaps after upload

Once sourcemaps are on Flare's side, you probably don't want them sitting in your deployment. The Next.js wrapper removes them by default. The plain webpack plugin doesn't, since webpack setups vary more and we'd rather not delete files you might need.

Flip it either way with removeSourcemaps:

new FlareWebpackPlugin({
    apiKey: 'YOUR_FLARE_API_KEY',
    removeSourcemaps: true,
});

Only successfully uploaded sourcemaps get deleted. If an upload fails, the file stays on disk.

Retries and partial failures

Sourcemap uploads happen at the end of a build, when the network might be flaky or Flare's API might be busy. Both plugins retry with exponential backoff: first attempt, then 1 second wait, then 2 seconds, then give up. Rate limits (429) and server errors (502, 503, 504) get retried. Client errors like a 401 fail immediately since retrying a bad API key won't help.

Uploads run in parallel with Promise.allSettled, so one failure doesn't block the rest. Failed uploads show up as webpack warnings instead of breaking your build.

Public path

For Flare to match a sourcemap to a browser stack frame, the uploaded filename has to match what the browser sees. If your JS is served from https://content.spatie.be/assets/main.js, the sourcemap needs to be registered under that path, not just main.js.

The plugin reads your output.publicPath and prepends it automatically. If you're behind a CDN or have an unusual setup, override it:

new FlareWebpackPlugin({
    apiKey: 'YOUR_FLARE_API_KEY',
    publicPath: 'https://cdn.example.comhttps://content.spatie.be/assets/',
});

All options

Both plugins take the same options. The only difference is the default for removeSourcemaps.

Getting started

For webpack:

npm install @flareapp/webpack

Requires webpack 5. Make sure devtool is set to something that generates .map files, like 'source-map'.

For Next.js:

npm install @flareapp/nextjs

Requires Next.js 13 or newer. Pair it with @flareapp/react to catch and report React errors from your components.

Full setup for both is in the sourcemap docs.