The official JavaScript/TypeScript client for Flare error tracking by Spatie. Captures frontend errors, collects browser context (cookies, request data, query params), and reports them to the Flare backend. Includes framework integrations for React, Vue, Svelte, SvelteKit, and build plugins for Vite, webpack, and Next.js for sourcemap uploads.
Read the JavaScript error tracking section in the Flare documentation for more information.
The v1 source lives on the 1.x branch.
This is an npm workspaces monorepo containing the following packages:
| Package | npm | Description |
|---|---|---|
packages/js |
@flareapp/js |
Core client for error capture, stack traces, context collection, and API reporting |
packages/react |
@flareapp/react |
React error boundary component and React 19 error handler |
packages/vue |
@flareapp/vue |
Vue error handler plugin |
packages/svelte |
@flareapp/svelte |
Svelte 5 error boundary component and boundary handler factory |
packages/sveltekit |
@flareapp/sveltekit |
SvelteKit client/server error hooks and route context |
packages/vite |
@flareapp/vite |
Vite build plugin for sourcemap uploads |
packages/webpack |
@flareapp/webpack |
Webpack 5 plugin for sourcemap uploads |
packages/nextjs |
@flareapp/nextjs |
Next.js wrapper for sourcemap uploads via webpack |
packages/flare-api |
(private) | Shared API client for sourcemap uploads (internal) |
playgrounds/shared |
(private) | Shared fixtures: product data, error scenarios, test IDs, Tailwind tokens |
playgrounds/js |
(private) | Vanilla TS + Vite playground (port 5180) |
playgrounds/react |
(private) | React 19 + TanStack Router playground (port 5181) |
playgrounds/vue |
(private) | Vue 3 + vue-router playground (port 5182) |
playgrounds/svelte |
(private) | SvelteKit (adapter-node) playground (port 5183) |
playgrounds/nextjs |
(private) | Next.js 15 App Router playground (port 5184) |
- Node.js >= 18 (see
.node-versionfor the exact version used in development) - npm (comes with Node.js)
# Clone the repo
git clone https://github.com/spatie/flare-client-js.git
cd flare-client-js
# Install all dependencies (root + all workspaces)
npm install
# Build all packages
npm run buildAll commands are run from the repository root:
| Command | Description |
|---|---|
npm run build |
Build all packages to their respective dist folders |
npm run test |
Run tests for all packages that have them |
npm run typescript |
Type-check all packages |
npm run format |
Run oxfmt across all files |
npm run lint |
Run oxlint across all packages |
npm run test:e2e |
Run the Playwright suite across all four framework playgrounds |
npm run playgrounds:js |
Build packages, then start the vanilla JS playground (port 5180) |
npm run playgrounds:react |
Build packages, then start the React playground (port 5181) |
npm run playgrounds:vue |
Build packages, then start the Vue playground (port 5182) |
npm run playgrounds:svelte |
Build packages, then start the SvelteKit playground (port 5183) |
npm run playgrounds:nextjs |
Build packages, then start the Next.js playground (port 5184) |
There are five parallel playgrounds under playgrounds/, one per framework. Each implements the same webshop sample
app (product grid, product detail, cart, checkout, confirmation) plus a /broken page that triggers a deterministic
list of error scenarios. They share fixtures from @flareapp/playgrounds-shared so the surface stays identical across
frameworks.
# Pick the framework you want to explore
npm run playgrounds:js # http://localhost:5180
npm run playgrounds:react # http://localhost:5181
npm run playgrounds:vue # http://localhost:5182
npm run playgrounds:svelte # http://localhost:5183
npm run playgrounds:nextjs # http://localhost:5184To send reports to a real Flare project (instead of letting them fail), set VITE_FLARE_URL and VITE_FLARE_KEY for
the relevant playground - e.g. playgrounds/js/.env.local. Without them the playground still boots; reports just have
nowhere to land.
End-to-end tests live in e2e/ and run all four playgrounds against a local fake Flare server (e2e/fake-flare-server/)
that records report POSTs and exposes inspection endpoints for the tests. Playwright spawns each playground's Vite dev
server automatically.
# One-time browser install
npx playwright install chromium --with-deps
# Run the suite (~25s, 44 tests across js/react/vue/svelte)
npm run test:e2e
# One project, one scenario
npx playwright test --project=svelte -g "render-error"The fake server listens on FAKE_FLARE_PORT (default 7765; avoid 4318, OrbStack squats on the OTLP port).
Formatting is handled by oxfmt and linting by oxlint. A pre-commit hook (Husky + lint-staged) automatically formats and lints staged files on commit.
To manually format and lint all files:
npm run format
npm run lintSee .oxfmtrc.json and .oxlintrc.json for configuration.
GitHub Actions runs on every push:
- Test: installs dependencies, builds all packages, runs all tests (Vitest)
- TypeScript: installs dependencies, builds all packages, type-checks all packages
- E2E: installs dependencies, caches Playwright browsers by
@playwright/testversion, builds all packages, and runs the Playwright suite across all four framework playgrounds (Chromium). HTML reports are uploaded as artifacts on every run; traces and screenshots are uploaded only on failure.
Each package is versioned and published independently using release-it.
From the package directory you want to release, run:
cd packages/js
npm run releaseThis will:
- Verify your working directory is clean and you are on the
mainbranch. - Prompt you for the next version (patch, minor, major, or custom).
- Bump the
versionin the package'spackage.json. - Run the package's tests (if it has a
testscript). - Commit the bump with message
chore: release @flareapp/<pkg>@<version>. - Tag the commit as
@flareapp/<pkg>@<version>. - Push the commit and tag to
origin. - Build the package (via
prepublishOnly) and publish it to npm.
You must be authenticated to npm before running this. Run npm login once, or set the NPM_TOKEN environment variable. If 2FA is enabled, release-it will prompt for the OTP.
To preview without making any changes, add --dry-run:
npm run release -- --dry-runNote:
release-itv20 requires Node.js 20+. If you are on Node 18 (the repo's minimum), upgrade your local Node before running a release.
When releasing changes that span multiple packages, publish them in dependency order:
@flareapp/js(core, no internal dependencies)@flareapp/vite(no internal dependencies)@flareapp/webpack(no internal dependencies)@flareapp/nextjs(depends on@flareapp/webpack)@flareapp/react(depends on@flareapp/js)@flareapp/vue(depends on@flareapp/js)@flareapp/svelte(depends on@flareapp/js)@flareapp/sveltekit(depends on@flareapp/jsand@flareapp/svelte)
flare-client-js/
├── packages/
│ ├── js/ # Core client
│ ├── react/ # React integration
│ ├── vue/ # Vue integration
│ ├── svelte/ # Svelte integration
│ ├── sveltekit/ # SvelteKit integration
│ ├── vite/ # Vite sourcemap plugin
│ ├── webpack/ # Webpack sourcemap plugin
│ ├── nextjs/ # Next.js sourcemap plugin
│ └── flare-api/ # Shared API client (private)
├── playgrounds/
│ ├── shared/ # Shared fixtures (products, scenarios, test IDs, Tailwind tokens)
│ ├── js/ # Vanilla TS + Vite playground
│ ├── react/ # React + TanStack Router playground
│ ├── vue/ # Vue + vue-router playground
│ ├── svelte/ # SvelteKit playground
│ └── nextjs/ # Next.js playground
├── e2e/ # Playwright specs + fake-flare-server fixture
├── .github/ # GitHub Actions workflows
├── .husky/ # Git hooks (pre-commit formatting)
└── package.json # Root workspace config
The MIT License (MIT). Please see License File for more information.