@flareapp/electron 0.1.0 → 2.5.0

package/README.md

@@ -1,18 +1,16 @@
 # @flareapp/electron
 
-> ⚠️ **Experimental (`0.1.0`).** This package is new and its API may change in a minor release. Feedback and bug reports are very welcome at https://github.com/spatie/flare-client-js/issues.
-
 Electron SDK for [Flare](https://flareapp.io) error tracking. It captures JavaScript errors in **both** Electron processes and routes every report through the main process, so your API key lives in exactly one place.
 
 ## What it captures
 
 - **Main process:** uncaught exceptions and unhandled promise rejections.
 - **Renderer process:** `window.onerror` and `unhandledrejection`, plus anything you report manually.
-- **Process crashes:** `render-process-gone` and `child-process-gone` (renderer/GPU/utility), reported as structured errors with the crash `reason` and `exitCode`.
+- **Process crashes:** `render-process-gone` and `child-process-gone`, reported with the crash `reason` and `exitCode`.
 
 It does **not** capture native crashes (C++/Crashpad minidumps). Only JavaScript-level errors are sent to Flare.
 
-## Install
+## Installation
 
 ```bash
 npm install @flareapp/electron
@@ -20,154 +18,43 @@ npm install @flareapp/electron
 
 `electron` is a peer dependency; this package expects your app to provide it.
 
-## Setup
-
-Flare needs wiring in all three Electron contexts. The API key, `stage`, `version`, and sourcemap settings are configured **once, in the main process** — the renderer needs none of them.
+## Quick start
 
-### 1. Main process
+Flare needs wiring in all three Electron contexts. The API key is configured **once, in the main process**.
 
 ```ts
 // main.ts
-import { app } from 'electron';
 import { flare } from '@flareapp/electron/main';
 
-flare.light('your-flare-api-key');
-
-// Optional: these are set ONCE here and applied to renderer reports too.
-flare.configure({ stage: 'production', version: app.getVersion() });
-
-// Optional: fatal-handler behavior and IPC trust policy.
-flare.configureElectron({
-    uncaughtExceptionMode: 'report-and-exit', // 'report' | 'report-and-exit' | 'off'
-    unhandledRejectionMode: 'report-and-exit',
-    captureRenderProcessGone: true,
-});
+flare.light('YOUR_FLARE_API_KEY');
 ```
 
-In `report-and-exit` mode, after a fatal error Flare reports it, flushes pending reports (up to `shutdownTimeoutMs`), then calls `app.exit(1)`.
-
-### 2. Preload script
-
-Because `contextIsolation` is on (the Electron default and the recommended setting), the renderer cannot reach `ipcRenderer` directly. The preload helper bridges reports over `contextBridge`. This step is **required** — without it, renderer reports are dropped.
-
 ```ts
-// preload.ts
+// preload.ts — required so renderer reports reach main over contextBridge
 import { exposeFlare } from '@flareapp/electron/preload';
 
 exposeFlare();
 ```
 
-Make sure your `BrowserWindow` points at this preload script:
-
-```ts
-new BrowserWindow({
-    webPreferences: {
-        preload: path.join(__dirname, 'preload.js'),
-        contextIsolation: true,
-    },
-});
-```
-
-### 3. Renderer
-
-Import the renderer entry once, as early as possible, to install the global error listeners:
-
 ```ts
-// renderer entry, e.g. main.tsx / index.ts
+// renderer entry, e.g. main.tsx / index.ts — installs the global listeners
 import '@flareapp/electron/renderer';
 ```
 
-For manual reporting, use the exported instance:
-
-```ts
-import { flare } from '@flareapp/electron/renderer';
-
-try {
-    doRiskyThing();
-} catch (error) {
-    flare.report(error as Error);
-}
-```
-
-The renderer builds the full report (stack trace + source snippets + browser context) in its own context, then forwards it to the main process. No API key lives in the renderer.
+Point your `BrowserWindow` at the preload script with `contextIsolation: true` (the default).
 
-## How reports flow
+## Using a UI framework
 
-```
-renderer error
-  → RendererFlare builds Report (stack + snippets + browser context)
-  → renderer beforeSubmit → serialize → size-check
-  → window.__flare.report(jsonString)    [contextBridge]
-  → ipcRenderer.invoke('flare:report')   [IPC]
-  → main: trust sender → size-check → parse → validate
-  → overlay stage/version/sourcemap + app metadata + user
-  → main beforeSubmit → sent to Flare
-
-main-process error
-  → process handlers → sent to Flare (app.exit on report-and-exit)
-
-renderer / GPU crash
-  → render-process-gone / child-process-gone → reported → sent to Flare
-```
+When your renderer uses React, Vue, or Svelte, inject the Electron Flare instance through the framework's `/inject` entry instead of the `@flareapp/js` web singleton. See the framework configuration guides:
 
-The API key is held only in the main process because that is the single egress point: every report, wherever it originates, is sent from main.
-
-## Filtering reports (`beforeSubmit`)
-
-`beforeSubmit` runs in **two stages**: once in the renderer (scrub close to the source) and once in main (the final gate before sending). Returning `null`/`false` from either drops the report.
-
-```ts
-// main
-flare.configure({
-    beforeSubmit: (report) => {
-        // final scrub before sending
-        return report;
-    },
-});
-
-// renderer
-import { flare } from '@flareapp/electron/renderer';
-flare.configure({
-    beforeSubmit: (report) => {
-        delete report.attributes['context.custom'];
-        return report;
-    },
-});
-```
-
-## Sender trust
-
-The main process only accepts reports from frames it trusts. By **default** it accepts:
-
-- `file:` URLs (packaged builds), and
-- `http(s)` on `localhost` / `127.0.0.1` (dev servers).
-
-It rejects everything else, including remote origins and custom protocols. If your app serves its renderer over a custom protocol or loads trusted remote content, opt in:
-
-```ts
-// Add a custom protocol scheme:
-flare.configureElectron({ trustedProtocols: ['app'] });
-
-// Or take full control:
-flare.configureElectron({
-    trustSender: (frame) => new URL(frame.url).origin === 'https://app.example.com',
-});
-```
-
-## Attaching the current user
-
-```ts
-import { flare } from '@flareapp/electron/main';
-
-flare.setUser({ id: 123, email: 'user@example.com', username: 'jane' });
-flare.setUser(null); // clear on logout
-```
+- [Electron + React](https://flareapp.io/docs/react/electron/configuration)
+- [Electron + Vue](https://flareapp.io/docs/vue/electron/configuration)
+- [Electron + Svelte](https://flareapp.io/docs/svelte/electron/configuration)
 
-The user is attached to main-process reports and to forwarded renderer reports.
+## Documentation
 
-## Not captured
+Full documentation on the report flow, `beforeSubmit` filtering, sender trust, attaching users, and the framework integrations is available at [flareapp.io/docs/javascript/electron/how-it-works](https://flareapp.io/docs/javascript/electron/how-it-works).
 
-- Native crashes / Crashpad minidumps.
-- Errors that occur before `flare.light('your-key')` runs in the main process. The fatal process handlers are attached by `light()`, and no report is sent without a key, so call `light()` as early as possible in your main entry. Errors before that point (in any process) are not sent.
+## License
 
-This is an experimental release — see the note at the top.
+The MIT License (MIT). Please see [License File](../../LICENSE.md) for more information.

package/dist/main.cjs

@@ -34,7 +34,7 @@ let node_fs_promises = require("node:fs/promises");
 let node_url = require("node:url");
 
 //#region src/env.ts
-const CLIENT_VERSION = typeof process !== "undefined" && true ? "0.1.0" : "?";
+const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.5.0" : "?";
 
 //#endregion
 //#region src/types.ts

package/dist/main.mjs

@@ -5,7 +5,7 @@ import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
 //#region src/env.ts
-const CLIENT_VERSION = typeof process !== "undefined" && true ? "0.1.0" : "?";
+const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.5.0" : "?";
 
 //#endregion
 //#region src/types.ts

package/dist/renderer.cjs

@@ -8,7 +8,7 @@ const FLARE_BRIDGE_KEY = "__flare";
 
 //#endregion
 //#region src/env.ts
-const CLIENT_VERSION = typeof process !== "undefined" && true ? "0.1.0" : "?";
+const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.5.0" : "?";
 
 //#endregion
 //#region src/renderer/RendererFlare.ts

package/dist/renderer.mjs

@@ -7,7 +7,7 @@ const FLARE_BRIDGE_KEY = "__flare";
 
 //#endregion
 //#region src/env.ts
-const CLIENT_VERSION = typeof process !== "undefined" && true ? "0.1.0" : "?";
+const CLIENT_VERSION = typeof process !== "undefined" && true ? "2.5.0" : "?";
 
 //#endregion
 //#region src/renderer/RendererFlare.ts

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@flareapp/electron",
-    "version": "0.1.0",
-    "description": "Experimental Electron SDK for flareapp.io",
+    "version": "2.5.0",
+    "description": "Electron SDK for flareapp.io",
     "homepage": "https://flareapp.io",
     "bugs": {
         "url": "https://github.com/spatie/flare-client-js/issues"
@@ -62,17 +62,21 @@
         "release": "release-it"
     },
     "dependencies": {
-        "@flareapp/core": "2.4.0",
-        "@flareapp/js": "2.4.0"
+        "@flareapp/core": "2.5.0",
+        "@flareapp/js": "2.5.0"
     },
     "peerDependencies": {
         "electron": ">=35"
     },
     "devDependencies": {
+        "@flareapp/react": "file:../react",
+        "@flareapp/vue": "file:../vue",
         "electron": "^35.0.0",
+        "react": "^19.0.0",
         "tsdown": "^0.20.3",
         "typescript": "^5.7.0",
-        "vitest": "^4.0.18"
+        "vitest": "^4.0.18",
+        "vue": "^3.4.0"
     },
     "publishConfig": {
         "access": "public"