@nlite/logger-vue

Vue 3 plugin (with first-class support for the Composition API, Pinia, and Vue Router) that turns your SPA into a self-instrumenting NLite logger client. Captures global errors, unhandled rejections, console logs, route transitions, and component lifecycle breadcrumbs automatically.

Built on top of @nlite/logger-core. Designed to be ingested by @nlite/logger-server.

Table of Contents

1. Why this SDK?
2. Installation
3. Quick Start
4. Plugin Options
5. API Surface
6. Router & Pinia Helpers
7. Workflow & Lifecycle
8. Architecture Diagrams
9. Examples
10. Environment Variables
11. Scripts
12. Compatibility
13. License & Author

Why this SDK?

• One-line integration — app.use(NliteLoggerPlugin, config).
• Auto-capture of onerror, unhandledrejection, Vue's errorHandler, and errorCaptured.
• Component lifecycle breadcrumbs via a global mixin.
• Vue Router support — navigation breadcrumbs and error tracking.
• Pinia support — store mutation breadcrumbs.
• Composition API first — useLogger() / useNLiteLogger().
• Console capture in development so you don't have to rewrite your calls.

Installation

# npm
npm install @nlite/logger-vue

# pnpm
pnpm add @nlite/logger-vue

# yarn
yarn add @nlite/logger-vue

Requirements

| Tool | Version | |------|---------| | vue | >=3.3.0 (peer) | | vue-router | >=4.0.0 (optional, for router integration) | | pinia | >=2.0.0 (optional, for store integration) | | Node.js | >=18.0.0 |

Quick Start

import { createApp } from 'vue';
import { createRouter, createWebHistory } from 'vue-router';
import { createPinia } from 'pinia';
import App from './App.vue';
import { NliteLoggerPlugin, createRouterLogger } from '@nlite/logger-vue';

const router = createRouter({ history: createWebHistory(), routes: [/* ... */] });
const pinia = createPinia();

const app = createApp(App);

app.use(NliteLoggerPlugin, {
  apiKey: import.meta.env.VITE_NLITE_KEY,
  endpoint: import.meta.env.VITE_NLITE_ENDPOINT ?? 'http://localhost:3000',
  appName: 'shop-web',
  appVersion: '1.0.0',
  environment: import.meta.env.MODE,
  platform: 'vue',
  enableVueErrorHandler: true,
  enableRouterIntegration: true,
  enablePiniaIntegration: true,
});

app.use(pinia);
app.use(router);

// Optional: attach router-specific logger handlers
router.afterEach(createRouterLogger(app.config.globalProperties.$logger).afterEach);

app.mount('#app');

Plugin Options

VueSdkConfig extends SdkConfig and adds:

| Field | Type | Default | Description | |-------|------|---------|-------------| | platform | 'vue' \| 'web' | 'vue' | Required. | | app | App | — | Set automatically when installed via app.use(). | | enableVueErrorHandler | boolean | true | Hook into app.config.errorHandler. | | enableRouterIntegration | boolean | true | Detect a router from app._context.provides.router and emit navigation breadcrumbs. | | enablePiniaIntegration | boolean | false | Enable Pinia plugin helpers (see below). | | enableConsoleCapture | boolean | true (in dev) | Mirror console.* into logs. | | ErrorBoundary | Component | — | Reserved for future boundary integration. |

API Surface

Plugin

import { NliteLoggerPlugin } from '@nlite/logger-vue';
app.use(NliteLoggerPlugin, { apiKey, endpoint, appName, /* ... */ });

The plugin:

1. Builds a VueFetchTransport and creates a logger via @nlite/logger-core.
2. Provides it as nliteLogger (injection key NliteLoggerKey).
3. Sets app.config.globalProperties.$logger.
4. Wires app.config.errorHandler (unless disabled).
5. Patches window.onerror and window.onunhandledrejection.
6. Adds a global mixin for component lifecycle breadcrumbs.
7. Overrides app.unmount to flush + destroy the logger.

useLogger() / useNLiteLogger()

Both throw if the plugin isn't installed:

import { useLogger } from '@nlite/logger-vue';

export default {
  setup() {
    const logger = useLogger();
    const onClick = () => logger.info('clicked');
    return { onClick };
  },
};

provideLogger(app, config)

Alternative to app.use(...) that returns the logger instance directly.

getLogger()

Returns the singleton, or null if not installed. Useful for non-component code (Pinia stores, plugins).

setUser / setTags / addBreadcrumb / flush / destroyLogger

Convenience wrappers around the singleton. See @nlite/logger-core.

Injection key

import { inject } from 'vue';
import { NliteLoggerKey } from '@nlite/logger-vue';

const logger = inject(NliteLoggerKey);

Router & Pinia Helpers

createRouterLogger(logger)

Returns { afterEach, onError } callbacks you can pass to Vue Router:

const handlers = createRouterLogger(getLogger()!);
router.afterEach(handlers.afterEach);
router.onError(handlers.onError);

createPiniaLogger(logger)

Returns a Pinia plugin function:

pinia.use(createPiniaLogger(getLogger()!));

Every mutation becomes a breadcrumb (type: 'custom', category: 'store').

Workflow & Lifecycle

                    ┌────────────────────────────────────┐
                    │  app.use(NliteLoggerPlugin, cfg)   │
                    └─────────────────┬──────────────────┘
                                      │
                                      ▼
        ┌────────────────────────────────────────────────────────┐
        │ VueFetchTransport                                     │
        │  - POST {endpoint}/api/logs/batch                     │
        │  - AbortController timeout                            │
        └────────────────────────────────────────────────────────┘
                                      │
                                      ▼
        ┌────────────────────────────────────────────────────────┐
        │ setupAutoCapture(logger, config, app)                 │
        │  - window.onerror                                     │
        │  - window.onunhandledrejection                        │
        │  - console.* capture (in dev)                         │
        │  - Vue errorHandler                                   │
        │  - Router afterEach (if provided in context)          │
        │  - Global mixin (component created/destroyed)         │
        └────────────────────────────────────────────────────────┘
                                      │
                                      ▼
              ┌────────────────────────────────────────┐
              │  @nlite/logger-core                    │
              │  queue → batch → retry → transport     │
              └────────────────────┬───────────────────┘
                                   │
                                   ▼
                       POST {endpoint}/api/logs/batch
                       @nlite/logger-server (SQLite + Redis)

Component lifecycle

• beforeCreate → logger.addBreadcrumb({ type: 'ui', category: 'component', message: 'Component created: <Name>', level: 'trace' }) (only when the component has a name).
• beforeUnmount → mirror "Component destroyed" breadcrumb.
• errorCaptured(err, instance, info) → logger.error(err.message, err, { component, info }).

Log levels (errors)

| Source | Level | |--------|-------| | window.onerror | error | | onunhandledrejection | error | | Vue errorHandler | error | | Vue errorCaptured | error | | Router onError | error | | Store mutations | debug (breadcrumb only) | | Route navigation | info (breadcrumb only) |

Architecture Diagrams

Component view

   ┌─────────────────────────────────────────────────────┐
   │  Vue 3 Application                                 │
   │   ├─ app.use(NliteLoggerPlugin, config)             │
   │   ├─ components using useLogger()                   │
   │   ├─ router.afterEach(handlers.afterEach)           │
   │   └─ pinia.use(createPiniaLogger(logger))           │
   └────────────────────────┬────────────────────────────┘
                            │
                            ▼
   ┌─────────────────────────────────────────────────────┐
   │  NliteLoggerPlugin                                  │
   │   ├─ VueFetchTransport (fetch with AbortController) │
   │   ├─ app.config.errorHandler hook                   │
   │   ├─ window.onerror / onunhandledrejection hook     │
   │   ├─ console.* patch (dev only)                     │
   │   ├─ Router detection → navigation breadcrumbs      │
   │   └─ Global mixin (created/destroyed/errorCaptured) │
   └────────────────────────┬────────────────────────────┘
                            │
                            ▼
        ┌────────────────────────────────────────┐
        │  @nlite/logger-core                    │
        │  queue → batch → retry → transport     │
        └────────────────────┬───────────────────┘
                             │
                             ▼
                  POST {endpoint}/api/logs/batch
                  @nlite/logger-server

Sequence — unhandled error

Window    Vue app    NliteLoggerPlugin    CoreLogger    Transport    Server
  |          |             |                  |             |          |
  | throw    |             |                  |             |          |
  |--------->| errorHandler|                  |             |          |
  |          |------------>|                  |             |          |
  |          |             | logger.error()   |             |          |
  |          |             |----------------->|             |          |
  |          |             |                  | batch POST  |          |
  |          |             |                  |------------>|          |
  |          |             |                  |   200 OK    |          |
  |          |             |                  |<------------|          |

Sequence — route change

Router    NliteLoggerPlugin    CoreLogger    Transport    Server
  |              |                  |             |          |
  | afterEach    |                  |             |          |
  |------------->| breadcrumb       |             |          |
  |              |----------------->|             |          |
  |              |                  | flush (timer)         |
  |              |                  |------------>|          |
  |              |                  |   200 OK   |          |
  |              |                  |<-----------|          |

Examples

Composition API with auto-tracking

<script setup lang="ts">
import { onMounted } from 'vue';
import { useNLiteLogger } from '@nlite/logger-vue';

const logger = useNLiteLogger();
onMounted(() => logger.addBreadcrumb({
  type: 'navigation',
  category: 'screen',
  message: 'ProductDetail mounted',
  level: 'info',
}));
</script>

<template>
  <main>...</main>
</template>

User session binding

import { setUser } from '@nlite/logger-vue';

async function login(credentials) {
  const { user } = await api.login(credentials);
  setUser(user.id, { email: user.email, plan: user.plan });
}

Use a custom transport (e.g. send to a Kafka topic)

import { createLogger } from '@nlite/logger-core';
import { provideLogger } from '@nlite/logger-vue';

class KafkaTransport {
  constructor(private producer, private topic) {}
  async send(logs) { await this.producer.send({ topic: this.topic, messages: logs.map(l => ({ value: JSON.stringify(l) })) }); }
  async close() { await this.producer.disconnect(); }
}

provideLogger(app, {
  apiKey: 'KEY',
  appName: 'shop-web',
  platform: 'vue',
  endpoint: 'http://localhost:3000', // ignored when transport is overridden
  // Override via @nlite/logger-core directly if you need full transport control.
});

(For full transport override, call createLogger(config, transport) directly.)

Environment Variables

| Variable | Description | |----------|-------------| | VITE_NLITE_KEY / VUE_APP_NLITE_KEY | API key | | VITE_NLITE_ENDPOINT | Override endpoint (default http://localhost:3000) | | import.meta.env.MODE | Mapped to environment | | import.meta.env.DEV | Toggles enableConsole & enableConsoleCapture |

Scripts

| Script | Description | |--------|-------------| | npm run build | tsc + copy dist/index.js to dist/index.cjs. | | npm run dev | Watch-mode build. | | npm test | Vitest. | | npm run test:watch | Vitest watch. | | npm run lint | ESLint over src. | | npm run typecheck | tsc --noEmit. |

Compatibility

• Vue 3.3 → 3.5+.
• Vue Router 4.x.
• Pinia 2.x.
• Vite, Vue CLI, Nuxt 3 (client side).

License & Author

MIT — © Debanjan Dasgupta. See the root README.