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.
| Option | Type | Default (webpack / nextjs) | Description |
|---|---|---|---|
apiKey |
string |
(required) | Your Flare API key |
apiEndpoint |
string |
Flare production endpoint | Override the upload endpoint |
version |
string |
random UUID | Sourcemap version identifier |
removeSourcemaps |
boolean |
false / true |
Delete .map files after upload |
runInDevelopment |
boolean |
false |
Upload in development mode |
publicPath |
string |
from webpack config | Override the public path prepended to filenames |
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.
Continue reading
Svelte support for Flare is here!
Flare now supports Svelte 5! After our major upgrade to the JavaScript clients, we have now added support for another big frontend framework.
Dries
Copy-pasteable SQL in your Laravel query exceptions
Today we're shipping a small but lovely upgrade to Flare: every query exception now comes with a SQL statement you can actually copy and run.
Ruben
Subscribe to Backtrace, our quarterly Flare newsletter
No spam, just news & product updates