@lenne.tech/bug.lt

Ein Nuxt 4 Modul für Bug-Reporting mit Linear Integration, Screenshots und automatischer Label-Verwaltung.

Features

🐛 Bug Report Button - Konfigurierbarer Button in der Ecke des Bildschirms
📸 Client-Side Screenshots - Schnelle DOM-Screenshots mit modern-screenshot (kein Chrome/Puppeteer nötig)
🚶 User Journey Tracking - Automatische Erfassung von Benutzerinteraktionen (Klicks, Navigation, Formulare)
🌐 Network Requests - Erfassung aller Netzwerkanfragen mit Status und Fehlerdetails
🏷️ Automatische Label-Verwaltung - Erstellt und verwaltet Labels basierend auf Bug-Type automatisch
🎯 Linear Integration - Direkte Erstellung von Issues in Linear mit Team/Project-Resolution
📱 Browser-Informationen - Automatische Erfassung von Browser-, OS- und Performance-Daten
📝 Console Logs - Erfassung und Anhang von Console-Ausgaben (CSS-Styles werden bereinigt)
⚠️ Error Boundary - Automatische Fehlererfassung bei JavaScript-Exceptions
🌓 Theme Support - Dark/Light Theme mit modernen OKLCH Farben
🔒 Server-Side Sicherheit - API-Keys werden nur server-seitig verwendet
🇩🇪 Deutsche Lokalisierung - Vollständig deutsche Benutzeroberfläche

Installation

npm install @lenne.tech/bug.lt

Setup

1. Nuxt Konfiguration

Füge das Modul zu deiner nuxt.config.ts hinzu:

export default defineNuxtConfig({
  modules: [
    '@lenne.tech/bug.lt'
    // @nuxt/ui wird automatisch hinzugefügt
  ],
  bug: {
    // Module Control
    enabled: true, // false deaktiviert das komplette Modul
    ui: true, // false = eigenständiger Modus ohne @nuxt/ui (siehe unten)

    // Server-Endpunkt für den Bug-Report (Server-Handler + Client-`$fetch`).
    // Standard liegt bewusst NICHT unter `/api/`, damit ein `/api/**`-Proxy der
    // Consumer-App (Nitro `routeRules`) den Request nicht abfängt. Siehe Hinweis unten.
    endpoint: '/_bug-lt/report',

    // Linear Integration
    linearApiKey: process.env.NUXT_LINEAR_API_KEY,
    linearTeamName: process.env.NUXT_LINEAR_TEAM_NAME || 'Entwicklung',
    linearProjectName: process.env.NUXT_LINEAR_PROJECT_NAME, // optional

    // UI Konfiguration
    autoShow: true,
    position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    buttonColor: '#ef4444',

    // Features
    enableScreenshot: true,
    enableBrowserInfo: true,
    enableConsoleLogs: true,
    enableNetworkRequests: true,
    enableUserJourney: true,
    enableErrorBoundary: true,
    autoOpenOnError: false, // Modal automatisch öffnen bei JS-Fehlern

    // Styling
    theme: 'auto', // 'light' | 'dark' | 'auto'
    maxConsoleLogs: 50,
    maxNetworkRequests: 50,

    // User Journey Konfiguration (optional)
    userJourney: {
      maxEvents: 50,
      captureClicks: true,
      captureNavigation: true,
      captureFormInteractions: true,
      captureKeyboard: true,
      captureErrors: true,
    }
  }
})

2. Umgebungsvariablen

Erstelle eine .env Datei (zuvor hießen die Variablen LINEAR_API_KEY, LINEAR_TEAM_NAME, LINEAR_PROJECT_NAME — bitte umbenennen):

# Linear API Konfiguration (erforderlich)
# Hole dir deinen API Key aus Linear Settings -> API
NUXT_LINEAR_API_KEY=lin_api_...

# Linear Team Name oder Key (erforderlich)
NUXT_LINEAR_TEAM_NAME=Entwicklung

# Linear Projekt Name (optional)
NUXT_LINEAR_PROJECT_NAME=Website

Deployte Stages: `NUXT_BUG_LT_*` statt `.env`

Der Weg oben funktioniert nur lokal. process.env in der nuxt.config.ts wird zur Build-Zeit ausgewertet, und ein Container-Build (Docker, CI) bekommt die Credentials dort typischerweise nicht — die Secrets werden erst zur Laufzeit injiziert. Das Modul landet damit unkonfiguriert im Image, und jeder Report antwortet 500 "Linear API is not configured. Please set linearApiKey." — aber erst in dem Moment, in dem jemand einen Bug meldet. Bis dahin sieht alles gesund aus.

Für deployte Stages werden die Credentials deshalb nicht in der nuxt.config.ts gesetzt, sondern direkt als Umgebungsvariablen der Stage. Nitro leitet sie automatisch aus dem Config-Pfad runtimeConfig.bugLt ab:

# Auf der Stage setzen (nicht im Build!)
NUXT_BUG_LT_LINEAR_API_KEY=lin_api_...
NUXT_BUG_LT_LINEAR_TEAM_NAME=Entwicklung
NUXT_BUG_LT_LINEAR_PROJECT_NAME=Website

Der bug:-Block in der nuxt.config.ts bleibt dann ohne linearApiKey & Co. — die Werte kommen pro Request aus runtimeConfig.bugLt.

Zwei Fallstricke, die in der Praxis Zeit gekostet haben:

enabled ist ein Build-Time-Flag. enabled: process.env.IRGENDWAS !== 'production' wertet im Container-Build gegen eine leere Variable aus und ist damit immer true. Wer den Button pro Stage ein- und ausschalten will, nimmt zur Laufzeit NUXT_PUBLIC_BUG_LT_AUTO_SHOW=false — das greift ohne Rebuild.
Alte Variablennamen bleiben still liegen. Wird ein Projekt von NUXT_LINEAR_* auf NUXT_BUG_LT_* umgestellt, muss das auf jeder Stage passieren. Eine Stage mit den alten Namen liest niemand mehr, meldet aber auch nichts — sie antwortet nur den 500er oben.

NUXT_BUG_LT_LINEAR_API_KEY ist ein Linear Personal Access Token mit Schreibrechten auf den gesamten Workspace. Auf jeder Stage als Secret ablegen.

Verwendung

Automatisch (empfohlen)

Das Modul fügt automatisch einen Bug-Report-Button zu deiner Anwendung hinzu (wenn autoShow: true).

Programmatisch

<template>
  <div>
    <BugReportButton/>
    <!-- oder -->
    <button @click="openBugReport">
      Bug melden
    </button>
  </div>
</template>

<script setup>
  const {openModal} = useBugReport()

  const openBugReport = () => {
    openModal()
  }
</script>

Features im Detail

Automatische Label-Verwaltung

Das Modul erstellt automatisch Labels in Linear basierend auf dem Bug-Report-Type:

Bug → bug Label (rot)
Feature → feature Label (blau)
Enhancement → enhancement Label (grün)
Other → other Label (lila)

Falls Labels nicht existieren, werden sie automatisch erstellt.

Screenshot-Funktionalität

Client-seitige Erfassung mit modern-screenshot (kein Server/Chrome nötig)
Viewport-Screenshot - Erfasst den aktuell sichtbaren Bereich inkl. Scroll-Position
Automatische Anhang-Erstellung in Linear Issues
Theme-Erkennung - Passt Hintergrundfarbe an Light/Dark Mode an

User Journey Tracking

Klick-Tracking - Erfasst alle Klicks mit Element-Informationen
Navigation - Protokolliert Seitenwechsel und URL-Änderungen
Formular-Interaktionen - Erfasst Fokus, Blur und Submit-Events
Keyboard-Events - Protokolliert wichtige Tastatureingaben
Fehler-Tracking - Erfasst JavaScript-Exceptions automatisch
Timeline-Darstellung - Übersichtliche Darstellung der letzten Aktionen

Network Requests

Fetch & XHR - Erfasst alle Netzwerkanfragen
Status-Tracking - Zeigt erfolgreiche und fehlgeschlagene Requests
Error-Details - Speichert Fehlerinformationen bei fehlgeschlagenen Requests
Request-Body - Erfasst gesendete Daten (ohne sensitive Inhalte)

Linear Integration

Team-Resolution - Verwendet Team-Namen statt UUIDs
Projekt-Resolution - Optionale Projekt-Zuordnung per Name
Attachment-Upload - Screenshots werden direkt als Anhänge verknüpft
Strukturierte Issues - Organisierte Darstellung aller Informationen

Browser-Informationen

Automatische Erfassung von:

Browser-Details (Name, Version, User-Agent)
Betriebssystem-Informationen
Viewport und Screen-Größe
Performance-Metriken
Sprach- und Timezone-Einstellungen

API

Composable: `useBugReport()`

const {
  openModal,           // () => Promise<void>
  submitBugReport,     // (data: BugReportData) => Promise<void>
  isSubmitting,        // Ref<boolean>
  error,              // Ref<string | null>
  previewScreenshot,  // Ref<string | null>
  capturingScreenshot // Ref<boolean>
} = useBugReport()

Komponenten

<BugReportButton /> - Konfigurierbarer Bug-Report-Button
<BugReportModal /> - Modal-Dialog für Bug-Reports

UI-Modi: @nuxt/ui vs. eigenständig

Das Modul bringt zwei vollständig getrennte UI-Implementierungen mit, gesteuert über die ui-Option:

`ui: true` (Standard)

Button, Modal, Formular und Toasts werden mit @nuxt/ui gerendert. @nuxt/ui wird automatisch installiert und fügt sich nahtlos in das Design einer App ein, die bereits @nuxt/ui (Tailwind CSS v4) nutzt.

`ui: false` (eigenständiger Modus)

Das Modul ist vollständig self-contained: eigener Button, eigenes Modal, eigenes Formular und eigene Toasts – komplett ohne @nuxt/ui-Import. Es wird kein #ui-Alias benötigt und @nuxt/ui wird nicht installiert. Alle Komponenten bringen ihre Styles als scoped-CSS mit (Inline-/SVG-Icons), funktionieren also in jedem Nuxt-Projekt – unabhängig vom Styling-Stack:

export default defineNuxtConfig({
  modules: ['@lenne.tech/bug.lt'],
  bug: {
    ui: false, // kein @nuxt/ui / Tailwind v4 erforderlich
    position: 'bottom-right',
  },
})

Damit lässt sich bug.lt z. B. in Projekten mit Tailwind CSS v3 (@nuxtjs/tailwindcss) oder ganz ohne Tailwind einsetzen, ohne vorher auf @nuxt/ui / Tailwind v4 migrieren zu müssen.

Hinweis: Im eigenständigen Modus wird die Option buttonIcon nicht unterstützt (es ist kein Icon-Framework eingebunden). Ohne buttonText zeigt der Button das mitgelieferte Bug-Icon.

Konfigurationsoptionen

Option	Typ	Standard	Beschreibung
`enabled`	`boolean`	`true`	Komplettes Modul aktivieren
`ui`	`boolean`	`true`	`true`: nutzt @nuxt/ui · `false`: eigenständiger Modus ohne @nuxt/ui (siehe Abschnitt „UI-Modi" oben)
`endpoint`	`string`	`'/_bug-lt/report'`	Server-Route für den Bug-Report (siehe Hinweis unten)
`linearApiKey`	`string`	-	Linear API Key (erforderlich)
`linearTeamName`	`string`	-	Linear Team Name oder Key
`linearProjectName`	`string`	-	Linear Projekt Name (optional)
`autoShow`	`boolean`	`true`	Automatische Anzeige des Buttons
`position`	`string`	`'bottom-right'`	Button-Position
`buttonColor`	`string`	`'#ef4444'`	Button-Farbe
`enableScreenshot`	`boolean`	`true`	Screenshot-Funktionalität
`enableBrowserInfo`	`boolean`	`true`	Browser-Info-Erfassung
`enableConsoleLogs`	`boolean`	`true`	Console-Log-Erfassung
`enableNetworkRequests`	`boolean`	`true`	Netzwerk-Request-Erfassung
`enableUserJourney`	`boolean`	`true`	User Journey Tracking
`enableErrorBoundary`	`boolean`	`true`	Error Boundary Komponente
`autoOpenOnError`	`boolean`	`false`	Modal bei JS-Fehlern öffnen
`theme`	`string`	`'auto'`	Theme ('light', 'dark', 'auto')
`maxConsoleLogs`	`number`	`50`	Maximale Anzahl Console-Logs
`maxNetworkRequests`	`number`	`50`	Maximale Anzahl Network-Requests
`userJourney`	`object`	siehe unten	User Journey Konfiguration

Important

Warum liegt der Endpunkt nicht unter /api/? Viele Nuxt-Apps leiten alle /api/**-Requests per Nitro-routeRules-Proxy an ein separates Backend weiter. Ein solcher Catch-all würde /api/bug-report verschlucken und an das Backend weiterreichen (→ 404), sodass der Handler dieses Moduls nie ausgeführt wird. Deshalb liegt der Standard-endpoint bewusst außerhalb von /api/ (/_bug-lt/report, im Nuxt-internen _-Präfix-Stil). Server und Client lesen denselben Wert aus runtimeConfig.public.bugLt.endpoint — du kannst ihn frei überschreiben, solange er nicht von einem Proxy abgefangen wird.

User Journey Optionen

Option	Typ	Standard	Beschreibung
`enabled`	`boolean`	`true`	User Journey aktivieren
`maxEvents`	`number`	`50`	Maximale Anzahl Events
`captureClicks`	`boolean`	`true`	Klick-Events erfassen
`captureNavigation`	`boolean`	`true`	Navigation erfassen
`captureFormInteractions`	`boolean`	`true`	Formular-Events erfassen
`captureKeyboard`	`boolean`	`true`	Keyboard-Events erfassen
`captureErrors`	`boolean`	`true`	Fehler erfassen
`captureModalEvents`	`boolean`	`true`	Modal-Events erfassen
`throttleRate`	`number`	`100`	Throttle-Rate in ms

Voraussetzungen

Nuxt 4.0+
Linear API Key mit write-Berechtigung

Entwicklung

# Dependencies installieren
npm install

# Type Stubs generieren
npm run dev:prepare

# Entwicklung mit Playground
npm run dev

# Build
npm run build

# Tests
npm run test

# Linting
npm run lint

Lizenz

MIT License - siehe LICENSE Datei für Details.

Entwickelt von lenne.Tech für effizientes Bug-Reporting in Nuxt-Anwendungen.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
playground		playground
public		public
src		src
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
nuxt.config.ts		nuxt.config.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

@lenne.tech/bug.lt

Features

Installation

Setup

1. Nuxt Konfiguration

2. Umgebungsvariablen

Deployte Stages: `NUXT_BUG_LT_*` statt `.env`

Verwendung

Automatisch (empfohlen)

Programmatisch

Features im Detail

Automatische Label-Verwaltung

Screenshot-Funktionalität

User Journey Tracking

Network Requests

Linear Integration

Browser-Informationen

API

Composable: `useBugReport()`

Komponenten

UI-Modi: @nuxt/ui vs. eigenständig

`ui: true` (Standard)

`ui: false` (eigenständiger Modus)

Konfigurationsoptionen

User Journey Optionen

Voraussetzungen

Entwicklung

Lizenz

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

@lenne.tech/bug.lt

Features

Installation

Setup

1. Nuxt Konfiguration

2. Umgebungsvariablen

Deployte Stages: NUXT_BUG_LT_* statt .env

Verwendung

Automatisch (empfohlen)

Programmatisch

Features im Detail

Automatische Label-Verwaltung

Screenshot-Funktionalität

User Journey Tracking

Network Requests

Linear Integration

Browser-Informationen

API

Composable: useBugReport()

Komponenten

UI-Modi: @nuxt/ui vs. eigenständig

ui: true (Standard)

ui: false (eigenständiger Modus)

Konfigurationsoptionen

User Journey Optionen

Voraussetzungen

Entwicklung

Lizenz

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Deployte Stages: `NUXT_BUG_LT_*` statt `.env`

Composable: `useBugReport()`

`ui: true` (Standard)

`ui: false` (eigenständiger Modus)