ngxs-logrocket-plugin 21.0.0

package/README.md

@@ -0,0 +1,178 @@
+# ngxs-logrocket-plugin
+
+NGXS plugin for [LogRocket](https://logrocket.com/) that augments LogRocket sessions with actions and state from your NGXS store.
+
+[![npm version](https://badge.fury.io/js/ngxs-logrocket-plugin.svg)](https://www.npmjs.com/package/ngxs-logrocket-plugin)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🔍 **Complete Action Logging** - Captures all NGXS actions with their status (Dispatched, Successful, Errored, Canceled)
+- 📸 **State Snapshots** - Records state before and after each action
+- ⚡ **Optimized Performance** - Runs outside Angular zone to prevent unnecessary change detection
+- 🛡️ **Privacy Controls** - Sanitize sensitive data from actions and state
+- 🔧 **Flexible Integration** - Load LogRocket from npm package or CDN script tag
+
+## Installation
+
+```bash
+npm install ngxs-logrocket-plugin logrocket
+```
+
+Or with yarn:
+
+```bash
+yarn add ngxs-logrocket-plugin logrocket
+```
+
+Or with pnpm:
+
+```bash
+pnpm add ngxs-logrocket-plugin logrocket
+```
+
+## Requirements
+
+- `@ngxs/store` >= 21.0.0
+- `logrocket` (peer dependency)
+- Angular (compatible with your NGXS version)
+
+## Usage
+
+### Basic Setup
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideStore } from '@ngxs/store';
+import { withNgxsLogRocketReduxMiddlewarePlugin } from 'ngxs-logrocket-plugin';
+import LogRocket from 'logrocket';
+
+// Initialize LogRocket
+LogRocket.init('your-app-id');
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideStore(
+      [
+        /* your states */
+      ],
+      withNgxsLogRocketReduxMiddlewarePlugin({
+        logrocket: () => LogRocket,
+      }),
+    ),
+  ],
+};
+```
+
+### Loading LogRocket from CDN
+
+If you load LogRocket via a script tag instead of npm:
+
+```html
+<!-- index.html -->
+<script src="https://cdn.logr-in.com/LogRocket.min.js" crossorigin="anonymous"></script>
+<script>
+  window.LogRocket && window.LogRocket.init('your-app-id');
+</script>
+```
+
+```typescript
+// app.config.ts
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideStore(
+      [
+        /* your states */
+      ],
+      withNgxsLogRocketReduxMiddlewarePlugin({
+        logrocket: () => window.LogRocket,
+      }),
+    ),
+  ],
+};
+```
+
+## Action Status Types
+
+The plugin logs actions with the following statuses:
+
+| Status       | Description                                            |
+| ------------ | ------------------------------------------------------ |
+| `DISPATCHED` | Action has been dispatched                             |
+| `SUCCESSFUL` | Action handler completed successfully                  |
+| `ERRORED`    | Action handler threw an error                          |
+| `CANCELED`   | Action was canceled by another action of the same type |
+
+Example in LogRocket:
+
+```
+[Countries] Load countries (DISPATCHED)
+[Countries] Load countries (SUCCESSFUL)
+[Auth] Login (DISPATCHED)
+[Auth] Login (ERRORED)
+```
+
+## How It Works
+
+The plugin integrates with NGXS as a middleware and leverages LogRocket's Redux middleware under the hood:
+
+1. Intercepts all NGXS actions before they're processed
+2. Logs action dispatch with current state
+3. Captures action completion (success, error, or cancellation)
+4. Compresses actions and state using LogRocket's binary format
+5. Performs state diffs to minimize network data
+
+All logging operations run outside the Angular zone to prevent triggering unnecessary change detection cycles.
+
+## Viewing Logs in LogRocket
+
+Once configured, you can view NGXS actions in the LogRocket dashboard:
+
+1. Open a session in LogRocket
+2. Navigate to the "Redux" tab
+3. Browse actions and state changes
+4. Click an action to see state before and after
+
+## Performance Considerations
+
+- **Zone Optimization**: All LogRocket operations run outside Angular's zone
+- **Data Compression**: Actions and state are compressed using binary format
+- **State Diffing**: Only state changes are transmitted, not full snapshots
+- **Error Handling**: LogRocket errors are caught and logged without breaking your app
+
+## TypeScript Support
+
+Full TypeScript support is included. The plugin exports all necessary types:
+
+```typescript
+import type { NgxsLogRocketReduxMiddlewareOptions } from 'ngxs-logrocket-plugin';
+```
+
+## Troubleshooting
+
+### Actions Not Appearing in LogRocket
+
+1. Verify LogRocket is initialized before NGXS
+2. Check that the plugin is registered with `provideStore`
+3. Ensure you're not returning `null` from `actionSanitizer`
+
+### Performance Issues
+
+- Use `actionSanitizer` to filter high-frequency actions
+- Sanitize large state objects to reduce payload size
+- Verify you're using the factory pattern `() => LogRocket` (not direct reference)
+
+## Related Projects
+
+- [logrocket](https://www.npmjs.com/package/logrocket) - LogRocket JavaScript SDK
+- [@ngxs/store](https://www.npmjs.com/package/@ngxs/store) - NGXS State Management
+- [logrocket-ngrx](https://www.npmjs.com/package/logrocket-ngrx) - NgRx middleware for LogRocket
+
+## Version Compatibility
+
+This package follows the major version of `@ngxs/store`:
+
+| ngxs-logrocket-plugin | @ngxs/store |
+| --------------------- | ----------- |
+| 21.x.x                | >=21.0.0    |

package/fesm2022/ngxs-logrocket-plugin.mjs

@@ -0,0 +1,87 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, NgZone, Injector, Injectable, makeEnvironmentProviders } from '@angular/core';
+import { ActionStatus, Store, getActionTypeFromInstance, withNgxsPlugin } from '@ngxs/store';
+import { tap } from 'rxjs';
+
+const ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS = new InjectionToken(typeof ngDevMode !== 'undefined' && ngDevMode
+    ? 'NGXS_LOGROCKET_MIDDLEWARE_OPTIONS'
+    : '');
+
+class ɵNgxsLogRocketReduxMiddlewarePlugin {
+    _ngZone = inject(NgZone);
+    _injector = inject(Injector);
+    _options = inject(ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS);
+    _store;
+    _logRocketStore;
+    handle(state, action, next) {
+        // The `next(...)` observable will do following things:
+        // * will emit `next` and then complete when the action is completed
+        // * will emit `error` (not `next` or `complete`) when one of the @Action handlers errors
+        // * will emit only `complete` (and not `next`) when the action is cancelled by another action of the same type
+        const result = next(state, action);
+        // Synchronous actions have been handled after the `next()` has been called.
+        this._logReduxEvent(null, action, ActionStatus.Dispatched);
+        let hasBeenCancelled = true;
+        return result.pipe(tap({
+            next: (newState) => {
+                hasBeenCancelled = false;
+                this._logReduxEvent(newState, action, ActionStatus.Successful);
+            },
+            error: () => {
+                this._logReduxEvent(null, action, ActionStatus.Errored);
+            },
+            complete: () => {
+                if (hasBeenCancelled) {
+                    this._logReduxEvent(null, action, ActionStatus.Canceled);
+                }
+            },
+        }));
+    }
+    _logReduxEvent(newState, action, status) {
+        // Retrieve lazily to avoid any cyclic dependency injection errors.
+        this._store ??= this._injector.get(Store);
+        this._logRocketStore ??= this._ngZone.runOutsideAngular(() => {
+            return this._options.logrocket().reduxMiddleware()({
+                getState: () => this._store.snapshot(),
+            });
+        });
+        newState = newState || this._store.snapshot();
+        const newAction = {
+            type: `${getActionTypeFromInstance(action)} (${status})`,
+            payload: action.payload || { ...action },
+        };
+        // Run outside Angular zone to prevent unnecessary change detection cycles.
+        // Logrocket internally queues events and may trigger async operations.
+        this._ngZone.runOutsideAngular(() => {
+            try {
+                this._logRocketStore(() => newState)(newAction);
+            }
+            catch (error) {
+                // Swallow errors from Logrocket to prevent breaking app flow.
+                console.error(error);
+            }
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: ɵNgxsLogRocketReduxMiddlewarePlugin, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: ɵNgxsLogRocketReduxMiddlewarePlugin });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.1.1", ngImport: i0, type: ɵNgxsLogRocketReduxMiddlewarePlugin, decorators: [{
+            type: Injectable
+        }] });
+
+function withNgxsLogRocketReduxMiddlewarePlugin(options) {
+    return makeEnvironmentProviders([
+        {
+            provide: ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS,
+            useValue: options,
+        },
+        withNgxsPlugin(ɵNgxsLogRocketReduxMiddlewarePlugin),
+    ]);
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { withNgxsLogRocketReduxMiddlewarePlugin, ɵNgxsLogRocketReduxMiddlewarePlugin };
+//# sourceMappingURL=ngxs-logrocket-plugin.mjs.map

package/fesm2022/ngxs-logrocket-plugin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngxs-logrocket-plugin.mjs","sources":["../../../../libs/ngxs-logrocket-plugin/src/lib/symbols.ts","../../../../libs/ngxs-logrocket-plugin/src/lib/logrocket-redux-middleware.plugin.ts","../../../../libs/ngxs-logrocket-plugin/src/lib/providers.ts","../../../../libs/ngxs-logrocket-plugin/src/ngxs-logrocket-plugin.ts"],"sourcesContent":["import { InjectionToken } from '@angular/core';\nimport type LogRocket from 'logrocket';\n\nexport interface NgxsLogRocketReduxMiddlewareOptions {\n  /**\n   * Factory function that returns the LogRocket object.\n   *\n   * This allows flexibility in how LogRocket is loaded:\n   *\n   * @example\n   * // Option 1: Import from npm package\n   * import LogRocket from 'logrocket';\n   *\n   * logrocket: () => LogRocket\n   *\n   * @example\n   * // Option 2: Load from window (script tag)\n   * logrocket: () => window.LogRocket\n   */\n  logrocket: () => typeof LogRocket;\n}\n\nexport const ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS =\n  new InjectionToken<NgxsLogRocketReduxMiddlewareOptions>(\n    typeof ngDevMode !== 'undefined' && ngDevMode\n      ? 'NGXS_LOGROCKET_MIDDLEWARE_OPTIONS'\n      : '',\n  );\n","import { inject, Injectable, Injector, NgZone } from '@angular/core';\nimport {\n  ActionStatus,\n  getActionTypeFromInstance,\n  Store,\n  type NgxsNextPluginFn,\n  type NgxsPlugin,\n} from '@ngxs/store';\nimport { tap } from 'rxjs';\n\nimport { ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS } from './symbols';\n\n@Injectable()\nexport class ɵNgxsLogRocketReduxMiddlewarePlugin implements NgxsPlugin {\n  private readonly _ngZone = inject(NgZone);\n  private readonly _injector = inject(Injector);\n  private readonly _options = inject(ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS);\n\n  private _store!: Store;\n  private _logRocketStore!: (newState: any) => (newAction: any) => void;\n\n  handle(state: any, action: any, next: NgxsNextPluginFn) {\n    // The `next(...)` observable will do following things:\n    // * will emit `next` and then complete when the action is completed\n    // * will emit `error` (not `next` or `complete`) when one of the @Action handlers errors\n    // * will emit only `complete` (and not `next`) when the action is cancelled by another action of the same type\n    const result = next(state, action);\n\n    // Synchronous actions have been handled after the `next()` has been called.\n    this._logReduxEvent(null, action, ActionStatus.Dispatched);\n\n    let hasBeenCancelled = true;\n\n    return result.pipe(\n      tap({\n        next: (newState) => {\n          hasBeenCancelled = false;\n          this._logReduxEvent(newState, action, ActionStatus.Successful);\n        },\n        error: () => {\n          this._logReduxEvent(null, action, ActionStatus.Errored);\n        },\n        complete: () => {\n          if (hasBeenCancelled) {\n            this._logReduxEvent(null, action, ActionStatus.Canceled);\n          }\n        },\n      }),\n    );\n  }\n\n  private _logReduxEvent(\n    newState: any,\n    action: any,\n    status: ActionStatus,\n  ): void {\n    // Retrieve lazily to avoid any cyclic dependency injection errors.\n    this._store ??= this._injector.get(Store);\n\n    this._logRocketStore ??= this._ngZone.runOutsideAngular(() => {\n      return this._options.logrocket().reduxMiddleware()({\n        getState: () => this._store.snapshot(),\n      });\n    });\n\n    newState = newState || this._store.snapshot();\n    const newAction = {\n      type: `${getActionTypeFromInstance(action)} (${status})`,\n      payload: action.payload || { ...action },\n    };\n    // Run outside Angular zone to prevent unnecessary change detection cycles.\n    // Logrocket internally queues events and may trigger async operations.\n    this._ngZone.runOutsideAngular(() => {\n      try {\n        this._logRocketStore(() => newState)(newAction);\n      } catch (error) {\n        // Swallow errors from Logrocket to prevent breaking app flow.\n        console.error(error);\n      }\n    });\n  }\n}\n","import { makeEnvironmentProviders } from '@angular/core';\nimport { withNgxsPlugin } from '@ngxs/store';\n\nimport {\n  ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS,\n  type NgxsLogRocketReduxMiddlewareOptions,\n} from './symbols';\nimport { ɵNgxsLogRocketReduxMiddlewarePlugin } from './logrocket-redux-middleware.plugin';\n\nexport function withNgxsLogRocketReduxMiddlewarePlugin(\n  options: NgxsLogRocketReduxMiddlewareOptions,\n) {\n  return makeEnvironmentProviders([\n    {\n      provide: ɵNGXS_LOGROCKET_REDUX_MIDDLEWARE_OPTIONS,\n      useValue: options,\n    },\n    withNgxsPlugin(ɵNgxsLogRocketReduxMiddlewarePlugin),\n  ]);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ngxs-logrocket-plugin",
+  "version": "21.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arturovt/ngxs-logrocket-plugin.git"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/arturovt/ngxs-logrocket-plugin#readme",
+  "bugs": {
+    "url": "git+https://github.com/arturovt/ngxs-logrocket-plugin/issues"
+  },
+  "keywords": [
+    "angular",
+    "ngxs",
+    "logrocket",
+    "plugin",
+    "middleware",
+    "state-management",
+    "session-replay",
+    "error-tracking",
+    "debugging",
+    "monitoring",
+    "redux",
+    "analytics"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@angular/core": ">=21.0.0",
+    "@ngxs/store": ">=21.0.0"
+  },
+  "dependencies": {
+    "@scarf/scarf": "^1.4.0",
+    "tslib": "^2.3.0"
+  },
+  "module": "fesm2022/ngxs-logrocket-plugin.mjs",
+  "typings": "types/ngxs-logrocket-plugin.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/ngxs-logrocket-plugin.d.ts",
+      "default": "./fesm2022/ngxs-logrocket-plugin.mjs"
+    }
+  }
+}

package/types/ngxs-logrocket-plugin.d.ts

@@ -0,0 +1,39 @@
+import * as i0 from '@angular/core';
+import LogRocket from 'logrocket';
+import { NgxsPlugin, NgxsNextPluginFn } from '@ngxs/store';
+
+interface NgxsLogRocketReduxMiddlewareOptions {
+    /**
+     * Factory function that returns the LogRocket object.
+     *
+     * This allows flexibility in how LogRocket is loaded:
+     *
+     * @example
+     * // Option 1: Import from npm package
+     * import LogRocket from 'logrocket';
+     *
+     * logrocket: () => LogRocket
+     *
+     * @example
+     * // Option 2: Load from window (script tag)
+     * logrocket: () => window.LogRocket
+     */
+    logrocket: () => typeof LogRocket;
+}
+
+declare function withNgxsLogRocketReduxMiddlewarePlugin(options: NgxsLogRocketReduxMiddlewareOptions): i0.EnvironmentProviders;
+
+declare class ɵNgxsLogRocketReduxMiddlewarePlugin implements NgxsPlugin {
+    private readonly _ngZone;
+    private readonly _injector;
+    private readonly _options;
+    private _store;
+    private _logRocketStore;
+    handle(state: any, action: any, next: NgxsNextPluginFn): any;
+    private _logReduxEvent;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ɵNgxsLogRocketReduxMiddlewarePlugin, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ɵNgxsLogRocketReduxMiddlewarePlugin>;
+}
+
+export { withNgxsLogRocketReduxMiddlewarePlugin, ɵNgxsLogRocketReduxMiddlewarePlugin };
+export type { NgxsLogRocketReduxMiddlewareOptions };