# Resolving bundled code


This page is for users who have already installed Flare in a JavaScript, React, or Vue app and now need readable stack traces for bundled production assets. For the basic installation flow, start on the dedicated setup page for your app:

- [Vanilla JavaScript](/docs/javascript/general/vanilla-javascript)
- [React](/docs/javascript/general/react)
- [Vue](/docs/javascript/general/vue)

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. Sourcemaps solve that by letting Flare turn those minified stack traces and code snippets back into readable source. The sections below cover plugin-based sourcemap uploads, bundler-specific options, and manual upload handling.

The following sourcemap upload options are available:

- [Vite](#vite)
- [Webpack](#webpack-or-laravel-mix)
- [Laravel Mix (using Webpack plugin)](#webpack-or-laravel-mix)
- [Manually uploading sourcemaps](#manually-uploading-sourcemaps)

## Vite

When using Vite to build your front-end code, you can use [Flare's Vite plugin (link to npm)](https://www.npmjs.com/package/@flareapp/vite).

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

```bash
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:

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

export default defineConfig({
    plugins: [
        flareSourcemapUploader({
            key: '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/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](#webpack-plugin-options).

### Vite plugin options

| Option             | Default              | Description                                                                                                                          |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `key`              | empty                | _(required)_ Your Flare project's public API key.                                                                                    |
| `base`             | Vite's base path     | The base path of built output.                                                                                                       |
| `runInDevelopment`  | `false`              | Whether to upload sourcemaps when `NODE_ENV=development` or when running the dev server.                                             |
| `version`          | fresh `uuid` per build | 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. |

## 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)](https://www.npmjs.com/package/@flareapp/flare-webpack-plugin-sourcemap).

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

```bash
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](#laravel-mix) and [Webpack](#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](#webpack-plugin-options).

### 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:**

```javascript
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`

```javascript
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:

```json
{
    "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](<https://en.wikipedia.org/wiki/Path_(computing)#Absolute_and_relative_paths>) 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](https://nodejs.org/api/zlib.html) library for Node.js, but the commandline `gzip` tool should work just as well:

```javascript
const zlib = require('zlib');

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