Skip to content

Commit 3fabbf6

Browse files
sebastienhenausebastienhenau
authored
Merge pull request #29 from spatie/docs/readme.md
Docs/readme.md
2 parents 87a96bb + d653627 commit 3fabbf6

6 files changed

Lines changed: 306 additions & 66 deletions

File tree

‎README.md‎

Lines changed: 139 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,149 @@
1-
# The JavaScript client for Flare to catch frontend errors
1+
# Flare JavaScript Client
22

3-
Read the JavaScript error tracking section in [the Flare documentation](https://flareapp.io/docs/javascript-error-tracking/installation) for more information.
3+
The official JavaScript/TypeScript client for [Flare](https://flareapp.io) error tracking
4+
by [Spatie](https://spatie.be). Captures frontend errors, collects browser context (cookies, request data, query
5+
params), and reports them to the Flare backend. Includes framework integrations for React and Vue, and a Vite plugin for
6+
sourcemap uploads.
47

5-
## Maintenance
8+
Read the JavaScript error tracking section
9+
in [the Flare documentation](https://flareapp.io/docs/javascript-error-tracking/installation) for more information.
610

7-
There are a few commands that can be run from the root of this repository to execute on all packages at once.
11+
## Packages
812

9-
| Command | Description |
10-
|--------------|-------------------------------------------------------|
11-
| `build` | Build all packages to their respective `dist` folders |
12-
| `test` | Run tests for all packages that have them |
13-
| `typescript` | Check types for all packages that have them |
14-
| `format` | Run Prettier across all packages |
13+
This is a npm workspaces monorepo containing the following packages:
1514

16-
## Publishing
15+
| Package | npm | Description |
16+
|------------------------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------------|
17+
| [`packages/js`](packages/js) | [`@flareapp/js`](https://www.npmjs.com/package/@flareapp/js) | Core client for error capture, stack traces, context collection, and API reporting |
18+
| [`packages/react`](packages/react) | [`@flareapp/react`](https://www.npmjs.com/package/@flareapp/react) | React error boundary component and React 19 error handler |
19+
| [`packages/vue`](packages/vue) | [`@flareapp/vue`](https://www.npmjs.com/package/@flareapp/vue) | Vue error handler plugin |
20+
| [`packages/vite`](packages/vite) | [`@flareapp/vite`](https://www.npmjs.com/package/@flareapp/vite) | Vite build plugin for sourcemap uploads |
21+
| [`playground`](playground) | (private) | Local dev/test app for all integrations |
1722

18-
To publish a new package version:
23+
## Local development
1924

20-
- Update the version number in the package's `package.json` `version` field
21-
- Run `npm publish` from the package directory
25+
### Prerequisites
26+
27+
- Node.js >= 18 (see `.node-version` for the exact version used in development)
28+
- npm (comes with Node.js)
29+
30+
### Setup
31+
32+
```bash
33+
# Clone the repo
34+
git clone https://github.com/spatie/flare-client-js.git
35+
cd flare-client-js
36+
37+
# Install all dependencies (root + all workspaces)
38+
npm install
39+
40+
# Build all packages
41+
npm run build
42+
```
43+
44+
### Commands
45+
46+
All commands are run from the repository root:
47+
48+
| Command | Description |
49+
|----------------------|-------------------------------------------------------|
50+
| `npm run build` | Build all packages to their respective `dist` folders |
51+
| `npm run test` | Run tests for all packages that have them |
52+
| `npm run typescript` | Type-check all packages |
53+
| `npm run format` | Run Prettier across all files |
54+
| `npm run playground` | Build packages, then start the playground dev server |
55+
56+
### Playground
57+
58+
The playground is a local Vite dev app for manually testing all integrations. Each page has
59+
buttons that trigger different error types.
60+
61+
```bash
62+
# Copy the env file and add your Flare API keys
63+
cp playground/.env.example playground/.env.local
64+
65+
# Start the playground
66+
npm run playground
67+
```
68+
69+
See the [playground README](playground/README.md) for more details.
70+
71+
### Code style
72+
73+
Formatting is handled by Prettier. A pre-commit hook (Husky + lint-staged) automatically formats staged files on commit.
74+
75+
To manually format all files:
76+
77+
```bash
78+
npm run format
79+
```
80+
81+
See `.prettierrc` for the full configuration.
82+
83+
### CI
84+
85+
GitHub Actions runs on every push:
86+
87+
- **Test**: installs dependencies, builds all packages, runs all tests
88+
- **TypeScript**: installs dependencies, builds all packages, type-checks all packages
89+
90+
## Versioning and releasing
91+
92+
Each package is versioned and published independently.
93+
94+
### Bumping a version
95+
96+
1. Update the `version` field in the package's `package.json`
97+
2. Commit the version bump
98+
3. Tag the commit using the format `<package-name>@<version>` (e.g. `@flareapp/js@1.2.0`)
99+
4. Push the commit and tag
100+
101+
```bash
102+
# Example: releasing @flareapp/js v1.2.0
103+
cd packages/js
104+
# Update version in package.json to 1.2.0, then:
105+
cd ../..
106+
git add packages/js/package.json
107+
git commit -m "Release @flareapp/js v1.2.0"
108+
git tag @flareapp/js@1.2.0
109+
git push origin main --tags
110+
```
111+
112+
### Publishing to npm
113+
114+
Run `npm publish` from the individual package directory. The `prepublishOnly` script in each package automatically runs
115+
a build before publishing.
116+
117+
```bash
118+
cd packages/js
119+
npm publish
120+
```
121+
122+
All packages have `"publishConfig": { "access": "public" }` so they are published as public scoped packages.
123+
124+
### Publishing multiple packages
125+
126+
When releasing changes that span multiple packages, publish them in dependency order:
127+
128+
1. `@flareapp/js` (core, no internal dependencies)
129+
2. `@flareapp/vite` (no internal dependencies)
130+
3. `@flareapp/react` (depends on `@flareapp/js`)
131+
4. `@flareapp/vue` (depends on `@flareapp/js`)
132+
133+
## Project structure
134+
135+
```
136+
flare-client-js/
137+
├── packages/
138+
│ ├── js/ # Core client
139+
│ ├── react/ # React integration
140+
│ ├── vue/ # Vue integration
141+
│ └── vite/ # Vite sourcemap plugin
142+
├── playground/ # Local dev/test app
143+
├── .github/ # GitHub Actions workflows
144+
├── .husky/ # Git hooks (pre-commit formatting)
145+
└── package.json # Root workspace config
146+
```
22147

23148
## License
24149

‎packages/js/README.md‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,30 @@
1-
# The JavaScript client for Flare to catch frontend errors
1+
# @flareapp/js
22

3-
Read the JavaScript error tracking section in [the Flare documentation](https://flareapp.io/docs/javascript-error-tracking/installation) for more information.
3+
The core JavaScript/TypeScript client for [Flare](https://flareapp.io) error tracking. Captures frontend errors, parses
4+
stack traces, collects browser context, and reports everything to the Flare backend.
45

5-
React plugin: https://www.npmjs.com/package/@flareapp/react
6+
## Installation
67

7-
Vue plugin: https://www.npmjs.com/package/@flareapp/vue
8+
```bash
9+
npm install @flareapp/js
10+
```
811

9-
Webpack plugin: https://www.npmjs.com/package/@flareapp/flare-webpack-plugin-sourcemap
12+
## Quick start
13+
14+
```js
15+
import { flare } from '@flareapp/js';
16+
17+
flare.light('YOUR_FLARE_API_KEY');
18+
```
19+
20+
That is all you need. The client automatically listens for uncaught exceptions and unhandled promise rejections,
21+
collects browser context, and sends error reports to Flare.
22+
23+
## Documentation
24+
25+
Full documentation on configuration, hooks, context, breadcrumbs, solution providers, and more is available
26+
at [flareapp.io/docs/javascript/general/installation](https://flareapp.io/docs/javascript/general/installation).
27+
28+
## License
29+
30+
The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

‎packages/react/README.md‎

Lines changed: 41 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,43 @@
1-
# The JavaScript client for Flare to catch frontend errors
1+
# @flareapp/react
22

3-
Read the JavaScript error tracking section in [the Flare documentation](https://flareapp.io/docs/javascript-error-tracking/installation) for more information.
3+
React integration for [Flare](https://flareapp.io) error tracking. Provides an error boundary component and a React 19+
4+
error handler for catching and reporting React component errors to Flare.
45

5-
Flare client: https://www.npmjs.com/package/@flareapp/js
6+
## Installation
7+
8+
```bash
9+
npm install @flareapp/react @flareapp/js
10+
```
11+
12+
## Quick start
13+
14+
Initialize the Flare client and wrap your component tree with the error boundary:
15+
16+
```tsx
17+
import { flare } from '@flareapp/js';
18+
import { FlareErrorBoundary } from '@flareapp/react';
19+
20+
flare.light('YOUR_FLARE_API_KEY');
21+
22+
function App() {
23+
return (
24+
<FlareErrorBoundary fallback={<p>Something went wrong.</p>}>
25+
<MyComponent />
26+
</FlareErrorBoundary>
27+
);
28+
}
29+
```
30+
31+
## Documentation
32+
33+
Full documentation on the error boundary, the React 19+ error handler, lifecycle callbacks, and more is available
34+
at [flareapp.io/docs/react/general/installation](https://flareapp.io/docs/react/general/installation).
35+
36+
## Compatibility
37+
38+
- React 16, 17, 18, 19
39+
- `flareReactErrorHandler` requires React 19+
40+
41+
## License
42+
43+
The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

‎packages/vite/README.md‎

Lines changed: 13 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,36 @@
1-
# Vite plugin for sending sourcemaps to Flare
1+
# @flareapp/vite
22

3-
The Flare Vite plugin helps you send sourcemaps of your compiled JavaScript code to Flare. This way, reports sent using the `@flareapp/js` will be formatted correctly.
3+
Vite build plugin for [Flare](https://flareapp.io) that uploads sourcemaps after each build. With sourcemaps, error reports sent by `@flareapp/js` will show the original source code instead of minified output.
44

5-
Additionally, it automatically passes the Flare API key to `@flareapp/js`. This way, `flare.light()` works without any additional configuration.
6-
7-
Check the JavaScript error tracking section in [the Flare documentation](https://flareapp.io/docs/javascript-error-tracking/installation) for more information.
5+
The plugin also injects the Flare API key and a sourcemap version identifier into your build, so `flare.light()` works without any additional configuration.
86

97
## Installation
108

11-
Install the plugin using NPM or Yarn:
12-
139
```bash
14-
yarn add @flareapp/vite
15-
# or
1610
npm install @flareapp/vite
1711
```
18-
Next, add the plugin to your `vite.config.js` file:
1912

20-
```js
13+
## Quick start
14+
15+
Add the plugin to your `vite.config.ts`:
16+
17+
```ts
2118
import { defineConfig } from 'vite';
2219
import flareSourcemapUploader from '@flareapp/vite';
2320

2421
export default defineConfig({
2522
plugins: [
2623
flareSourcemapUploader({
27-
key: 'YOUR API KEY HERE'
24+
key: 'YOUR_FLARE_API_KEY',
2825
}),
2926
],
3027
});
3128
```
3229

33-
Run the `vite build` command to make sure the sourcemaps are generated. You should see the following lines in the output:
34-
35-
```bash
36-
@flareapp/flare-vite-plugin-sourcemaps: Uploading 12 sourcemap files to Flare.
37-
@flareapp/flare-vite-plugin-sourcemaps: Successfully uploaded sourcemaps to Flare.
38-
```
39-
40-
## Configuration
41-
42-
- `key: string` **(required)**: the Flare API key
43-
- `base: string`: the base path of built output (defaults to Vite's base path)
44-
- `runInDevelopment: boolean`: whether to upload sourcemaps when `NODE_ENV=development` or when running the dev server (defaults to `false`)
45-
- `version: string`: the sourcemap version (defaults to a fresh `uuid` per build)
46-
- `removeSourcemaps: boolean`: whether to remove the sourcemaps after uploading them (defaults to `false`). Comes in handy when you want to upload sourcemaps to Flare but don't want them published in your build.
47-
48-
## development
49-
50-
Publish a new release:
51-
52-
```bash
53-
npm version patch
54-
npm publish
55-
```
30+
## Documentation
5631

57-
Tag the release:
32+
Full documentation on configuration options, sourcemap resolution, and more is available at [flareapp.io/docs/javascript/general/resolving-bundled-code](https://flareapp.io/docs/javascript/general/resolving-bundled-code).
5833

59-
<pre>
60-
git tag <var>VERSION</var>
61-
git push origin <var>VERSION</var>
62-
</pre>
34+
## License
6335

64-
Replace <var>VERSION</var> with `v` + the version from `package.json` — for example, `v1.0.2`
36+
The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

‎packages/vue/README.md‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,41 @@
1-
# The JavaScript client for Flare to catch frontend errors
1+
# @flareapp/vue
22

3-
Read the JavaScript error tracking section in [the Flare documentation](https://flareapp.io/docs/javascript-error-tracking/installation) for more information.
3+
Vue integration for [Flare](https://flareapp.io) error tracking. Installs a Vue error handler that catches component errors and reports them to Flare with Vue-specific context (component name, lifecycle info).
44

5-
Flare client: https://www.npmjs.com/package/@flareapp/js
5+
## Installation
6+
7+
```bash
8+
npm install @flareapp/vue @flareapp/js
9+
```
10+
11+
## Quick start
12+
13+
Initialize the Flare client and register the Vue error handler:
14+
15+
```js
16+
import { createApp } from 'vue';
17+
import { flare } from '@flareapp/js';
18+
import { flareVue } from '@flareapp/vue';
19+
20+
import App from './App.vue';
21+
22+
flare.light('YOUR_FLARE_API_KEY');
23+
24+
const app = createApp(App);
25+
26+
flareVue(app);
27+
28+
app.mount('#app');
29+
```
30+
31+
## Documentation
32+
33+
Full documentation on the Vue error handler and its options is available at [flareapp.io/docs/vue/general/installation](https://flareapp.io/docs/vue/general/installation).
34+
35+
## Compatibility
36+
37+
- Vue 2 and Vue 3
38+
39+
## License
40+
41+
The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

0 commit comments

Comments
 (0)