@cooperco/nuxt-layer-base 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,287 @@
+# Base Layer
+
+A foundational layer that provides essential configuration and tooling for Nuxt 4 projects.
+
+## Features
+
+- TypeScript integration with strict mode enabled
+- ESLint configuration with stylistic rules for Vue templates
+- Test utilities integration
+- Internationalization (i18n) via `@nuxtjs/i18n`
+- Nuxt DevTools enabled
+- CI/CD workflows for code quality checks
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Run ESLint
+npm run lint
+
+# Fix linting issues automatically
+npm run lint:fix
+
+# Run TypeScript type checking
+npm run typecheck
+```
+
+## Configuration Details
+
+### Key Features
+
+- **Compatibility Date:** 2025-07-15
+- **Strict TypeScript:** Enforces type safety throughout your projects
+- **ESLint Integration:** Pre-configured with stylistic rules for Vue templates
+  - Custom ESLint rules for code style consistency
+  - Vue template formatting rules
+- **Testing Utilities:** Built-in test utils for comprehensive testing
+
+### Configuration Details
+
+The base layer includes:
+
+- Nuxt ESLint module (`@nuxt/eslint`)
+- Nuxt Test Utils module (`@nuxt/test-utils`) 
+- Nuxt i18n module (`@nuxtjs/i18n`)
+- Nuxt DevTools enabled
+- TypeScript configuration with strict mode
+- Custom ESLint configuration with rules for:
+  - JavaScript stylistic preferences
+  - TypeScript unused variables handling
+  - Vue template formatting
+
+## Internationalization (i18n)
+
+This layer integrates the Nuxt i18n module (`@nuxtjs/i18n`). You can override or extend its configuration in your application.
+
+- Docs: https://i18n.nuxtjs.org
+
+Override example in a consuming app:
+
+```ts
+// nuxt.config.ts (in your app)
+export default defineNuxtConfig({
+  extends: ['@cooperco/nuxt-layer-base'],
+  i18n: {
+    locales: [
+      { code: 'en', language: 'en-US', name: 'English' },
+      { code: 'fr', language: 'fr-FR', name: 'Français' }
+    ],
+    defaultLocale: 'en'
+  }
+})
+```
+
+Basic usage in a component:
+
+```vue
+<script setup lang="ts">
+const { t, locale } = useI18n()
+</script>
+
+<template>
+  <p>{{ t('hello') }}</p>
+</template>
+```
+
+Note: Provide your own translation files (for example, `locales/en.json`) in your application.
+
+## Usage
+
+To use this layer in your Nuxt project:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [
+    '@cooperco/nuxt-layer-base'
+  ]
+})
+```
+
+## Nuxt 4 directory structure
+This layer follows Nuxt 4's app directory structure:
+- app/plugins/... for plugins (e.g., app/plugins/loggly.client.ts)
+- app/composables/... for composables (e.g., app/composables/useLoggly.ts)
+
+If you previously looked under plugins/ or composables/ at the layer root, note they have been relocated under app/ for Nuxt 4.
+
+## Error logging (Loggly)
+
+This base layer includes optional, secure error logging via Loggly using a server proxy. It is off by default and can be enabled per consuming app using environment variables.
+
+What you get when enabled:
+- Automatic server-side error capture (Nitro request errors)
+- Automatic client-side error capture (Nuxt/Vue/global browser errors)
+- Composable for custom logs from your features (useLoggly)
+- Centralized PII scrubbing on the server proxy before forwarding to Loggly
+
+### 1) Enable in your app (env vars)
+Set the following environment variables in your consuming app (do not expose the token on the client):
+
+- LOGGLY_ENABLED=true
+- LOGGLY_TOKEN=your-loggly-customer-token
+- LOGGLY_TAGS=nuxt,base,app-name,env  (comma-separated; optional)
+- LOG_LEVEL=error  (optional; error|warn|info|debug)
+- LOGGLY_ENDPOINT=https://logs-01.loggly.com/inputs  (optional override)
+
+Notes
+- LOGGLY_TOKEN is server-only and never shipped to the client. The client sends logs to the server proxy at /api/loggly.
+- If LOGGLY_ENABLED is not true or the token is missing, logging is skipped.
+
+### 2) Using the composable in your app
+The base layer exposes a composable you can call anywhere in your app.
+
+Example:
+```ts
+// inside a component or any composable
+const log = useLoggly()
+await log.error('Checkout failed', { orderId, step: 'place-order' }, ['checkout'])
+await log.info('User clicked CTA', { campaign: 'summer' }, ['marketing'])
+```
+
+API:
+- error(message, meta?, tags?)
+- warn(message, meta?, tags?)
+- info(message, meta?, tags?)
+- debug(message, meta?, tags?)
+
+Tags are merged with your global LOGGLY_TAGS (duplicates removed, limited to 10).
+
+### 3) Auto-captured errors
+When enabled, the base layer automatically forwards:
+- Server: request-time exceptions via a Nitro plugin
+- Client: Nuxt app errors, Vue component errors, window error events, and unhandled promise rejections
+
+These are forwarded to /api/loggly, which safely shapes the payload before sending to Loggly.
+
+### 4) Security and privacy
+- The server proxy masks common sensitive keys (password, token, authorization, etc.) in meta payloads.
+- Prefer adding any app-specific sensitive keys to your meta scrubbing in the proxy if needed.
+- Logging is fire-and-forget; failures to log do not block requests or UI.
+
+### 5) Verifying locally
+1) In your consuming app, set env vars (e.g. in .env.local):
+```
+LOGGLY_ENABLED=true
+LOGGLY_TOKEN=...your token...
+LOGGLY_TAGS=nuxt,base,local,app-name
+LOG_LEVEL=error
+```
+2) Start your app and induce an error (e.g., throw new Error('Test') in onMounted of a test component).
+3) Watch your network tab for POST /api/loggly (200 OK). Then check Loggly for the entry with your tags.
+
+### 6) Troubleshooting
+- No logs? Ensure LOGGLY_ENABLED=true and LOGGLY_TOKEN is set in the server environment.
+- CORS or network errors from the browser? The client never talks to Loggly directly; it only posts to /api/loggly.
+- Too much volume? Consider adding sampling or batching later; the proxy makes this easy to change centrally.
+
+
+## Playground: Test Loggly in the base layer
+
+A tiny playground app is included so you can run the base layer by itself and verify Loggly end‑to‑end before integrating into another app.
+
+Location: playground
+
+How it works:
+- The playground extends the base layer (extends: ['../layers/base']).
+- It includes a simple page to send logs via useLoggly and buttons to trigger client/server errors.
+- The server exposes GET /api/boom to intentionally throw and test server‑side logging.
+
+Run it:
+1) From the repo root:
+   - cd playground && npm run dev
+
+2) Provide environment variables for Loggly in the playground (optional but required to actually send to Loggly):
+   Copy playground/.env.example to playground/.env and fill in your values.
+
+   LOGGLY_ENABLED=true
+   LOGGLY_TOKEN=your-loggly-customer-token
+   LOGGLY_TAGS=nuxt,base,playground,local
+   LOG_LEVEL=debug
+   # Optional override
+   # LOGGLY_ENDPOINT=https://logs-01.loggly.com/inputs
+
+3) Open http://localhost:3000
+   - Click the Send error/warn/info/debug buttons to send custom logs.
+   - Click Throw client error to exercise the client plugin.
+   - Click Call /api/boom to exercise the server plugin.
+
+Notes:
+- If LOGGLY_ENABLED is not true or LOGGLY_TOKEN is missing, the server proxy will skip sending and respond with { ok: false, skipped: true }.
+- The token is server‑only; it is never exposed to the client. The browser only talks to /api/loggly on your dev server.
+
+
+---
+
+## Publishing to npm (tag-based)
+
+This layer is published using GitHub Actions when you push a tag that matches the base-vX.Y.Z pattern.
+
+High-level flow:
+- Bump the version in layers/base/package.json (SemVer).
+- Commit and push your changes to main (or ensure the commit is on main).
+- Create and push a tag named base-vX.Y.Z (matching the package.json version).
+- The Publish Base Layer workflow installs deps, checks if that exact version already exists on npm, and if not, publishes privately with --access restricted.
+
+Important notes:
+- Do NOT rely on npm version creating a tag for you (it will create vX.Y.Z). We use a custom tag prefix base-v.
+- First-time private publish is already configured via publishConfig.access: "restricted".
+- The workflow will skip if the version already exists (you'll see "Skipping; version already exists.").
+
+### Step-by-step
+
+1) Bump the version in layers/base/package.json
+- Option A (recommended): use npm version without creating a tag
+  - Bash:
+    ```bash
+    cd layers/base
+    npm version patch --no-git-tag-version  # or minor | major
+    ```
+  - PowerShell:
+    ```powershell
+    Set-Location layers/base
+    npm version patch --no-git-tag-version  # or minor | major
+    ```
+- Option B: manually edit the version field in layers/base/package.json (SemVer: MAJOR.MINOR.PATCH)
+
+2) Commit and push the change (from repo root or layers/base)
+```bash
+git add layers/base/package.json
+git commit -m "chore(base): bump version"
+git push origin main
+```
+
+3) Create and push the tag using the new version
+- Get the new version value:
+  - Bash:
+    ```bash
+    cd layers/base
+    VERSION=$(node -p "require('./package.json').version")
+    cd ../..
+    git tag "base-v$VERSION"
+    git push origin "base-v$VERSION"
+    ```
+  - PowerShell:
+    ```powershell
+    Set-Location layers/base
+    $version = node -p "require('./package.json').version"
+    Set-Location ../..
+    git tag "base-v$version"
+    git push origin "base-v$version"
+    ```
+
+4) GitHub Actions will publish
+- Workflow: .github/workflows/publish-base.yml
+- Auth: uses NPM_TOKEN (Classic Automation token) configured as a GitHub secret
+- Behavior: installs, checks npm view @cooperco/nuxt-layer-base@<version>, publishes if not found
+
+### Troubleshooting
+- Version already exists: bump the version again (patch/minor/major) and push a new tag.
+- Auth errors (401/403): ensure NPM_TOKEN is set in repo secrets and org access is correct.
+- Registry mismatch: this repo’s .npmrc pins @cooperco to https://registry.npmjs.org/; keep that file intact.

package/app/composables/useLoggly.ts

@@ -0,0 +1,28 @@
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug'
+
+export const useLoggly = () => {
+  const { public: pub } = useRuntimeConfig()
+  const enabled = !!pub?.logglyEnabled
+  const baseTags = (pub?.logglyTags || []) as string[]
+
+  const send = (
+    level: LogLevel,
+    message: string,
+    meta?: Record<string, unknown>,
+    tags: string[] = []
+  ) => {
+    if (!enabled) return
+    const mergedTags = [...new Set([...baseTags, ...tags])].slice(0, 10)
+    return $fetch('/api/loggly', {
+      method: 'POST',
+      body: { level, message, meta, tags: mergedTags }
+    }).catch(() => {})
+  }
+
+  return {
+    error: (m: string, meta?: Record<string, unknown>, tags?: string[]) => send('error', m, meta, tags),
+    warn: (m: string, meta?: Record<string, unknown>, tags?: string[]) => send('warn', m, meta, tags),
+    info: (m: string, meta?: Record<string, unknown>, tags?: string[]) => send('info', m, meta, tags),
+    debug: (m: string, meta?: Record<string, unknown>, tags?: string[]) => send('debug', m, meta, tags)
+  }
+}

package/app/plugins/loggly.client.ts

@@ -0,0 +1,70 @@
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig()
+  if (!config.public?.logglyEnabled) return
+
+  const post = (payload: Record<string, unknown>) =>
+    $fetch('/api/loggly', { method: 'POST', body: payload }).catch(() => { /* swallow */ })
+
+  // Nuxt app-level errors
+  nuxtApp.hook('app:error', (err) => {
+    post({
+      level: 'error',
+      message: extractMessage(err) || 'App error',
+      error: toErrorShape(err),
+      tags: ['client', 'nuxt']
+    })
+  })
+
+  // Vue component-level errors
+  const originalHandler = nuxtApp.vueApp.config.errorHandler
+  nuxtApp.vueApp.config.errorHandler = (err, instance, info) => {
+    post({
+      level: 'error',
+      message: extractMessage(err) || 'Vue error',
+      error: toErrorShape(err),
+      meta: { info, component: getComponentName(instance) },
+      tags: ['client', 'vue']
+    })
+    if (originalHandler) originalHandler(err, instance, info)
+  }
+
+  if (import.meta.client) {
+    window.addEventListener('error', (event: ErrorEvent) => {
+      post({ level: 'error', message: event.message, error: toErrorShape(event.error), tags: ['client', 'window'] })
+    })
+    window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
+      const reason = event.reason
+      post({ level: 'error', message: extractMessage(reason) || 'Unhandled rejection', error: toErrorShape(reason), tags: ['client', 'promise'] })
+    })
+  }
+})
+
+const toErrorShape = (err: unknown) => {
+  if (!err || typeof err !== 'object') return undefined
+  const e = err as { name?: string, message?: unknown, stack?: unknown }
+  return {
+    name: e.name || 'Error',
+    message: String(e.message ?? 'Error'),
+    stack: typeof e.stack === 'string' ? e.stack.split('\n').slice(0, 20) : undefined
+  }
+}
+
+const extractMessage = (err: unknown): string | undefined => {
+  if (!err) return undefined
+  if (typeof err === 'string') return err
+  if (typeof err === 'object' && 'message' in err) {
+    return String((err as { message?: unknown }).message)
+  }
+  return undefined
+}
+
+const getComponentName = (instance: unknown): string | undefined => {
+  if (!instance) return undefined
+  const rec = instance as Record<string, unknown>
+  const typeVal = rec?.type as unknown
+  if (typeof typeVal === 'string') return typeVal
+  if (typeVal && typeof typeVal === 'object' && 'name' in typeVal) {
+    return String((typeVal as { name?: unknown }).name)
+  }
+  return undefined
+}

package/nuxt.config.ts

@@ -1,8 +1,23 @@
+/* eslint-disable nuxt/nuxt-config-keys-order */
 export default defineNuxtConfig({
-  modules: ['@nuxt/eslint', '@nuxt/test-utils'],
+  modules: ['@nuxt/eslint', '@nuxtjs/i18n'],
   devtools: { enabled: true },
   compatibilityDate: '2025-07-15',
 
+  runtimeConfig: {
+    // server-only
+    logglyToken: process.env.LOGGLY_TOKEN || '',
+    logglyEndpoint: process.env.LOGGLY_ENDPOINT || 'https://logs-01.loggly.com/inputs',
+
+    // public (safe to expose)
+    public: {
+      // Allow either LOGGLY_ENABLED or NUXT_PUBLIC_LOGGLY_ENABLED to enable client features
+      logglyEnabled: (process.env.NUXT_PUBLIC_LOGGLY_ENABLED ?? process.env.LOGGLY_ENABLED) === 'true',
+      logglyTags: (process.env.NUXT_PUBLIC_LOGGLY_TAGS ?? process.env.LOGGLY_TAGS ?? 'nuxt,base').split(',').map(s => s.trim()).filter(Boolean),
+      logLevel: (process.env.NUXT_PUBLIC_LOG_LEVEL ?? process.env.LOG_LEVEL) || 'error' // error|warn|info|debug
+    }
+  },
+
   typescript: {
     tsConfig: {
       compilerOptions: {
@@ -13,7 +28,14 @@ export default defineNuxtConfig({
 
   eslint: {
     config: {
-      stylistic: true // needed for Vue Template linting rules
+      stylistic: true
     }
+  },
+
+  i18n: {
+    locales: [
+      { code: 'enUS', language: 'en-US' }
+    ],
+    defaultLocale: 'enUS'
   }
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cooperco/nuxt-layer-base",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "main": "./nuxt.config.ts",
   "scripts": {
@@ -11,7 +11,8 @@
   },
   "description": "Base Nuxt layer for cooperco projects",
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "repository": {
     "type": "git",
@@ -21,10 +22,13 @@
   "author": "cooperco",
   "license": "MIT",
   "dependencies": {
-    "@nuxt/eslint": "^1.7.1",
+    "@nuxt/eslint": "^1.9.0",
+    "@nuxtjs/i18n": "^10.0.6",
+    "nuxt": "^4.0.3"
+  },
+  "devDependencies": {
     "@nuxt/test-utils": "^3.19.2",
-    "eslint": "^9.32.0",
-    "nuxt": "^4.0.0",
-    "vue-tsc": "^3.0.4"
+    "eslint": "^9.33.0",
+    "vue-tsc": "^3.0.5"
   }
 }

package/server/api/loggly.post.ts

@@ -0,0 +1,58 @@
+import { defineEventHandler, readBody } from 'h3'
+
+type LogglyBody = {
+  level?: string
+  message?: string
+  error?: unknown
+  tags?: string[]
+  meta?: Record<string, unknown>
+}
+
+const sanitizeMeta = (input: unknown) => {
+  if (!input || typeof input !== 'object') return undefined
+  const blocked = ['password', 'token', 'authorization', 'auth', 'ssn', 'creditcard', 'credit_card']
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+    out[k] = blocked.includes(k.toLowerCase()) ? '[REDACTED]' : v
+  }
+  return out
+}
+
+const serializeError = (err: unknown) => {
+  if (!err || typeof err !== 'object') return undefined
+  const e = err as { name?: string, message?: unknown, stack?: unknown }
+  return {
+    name: e.name || 'Error',
+    message: String(e.message ?? 'Error'),
+    stack: typeof e.stack === 'string' ? e.stack.split('\n').slice(0, 20) : undefined
+  }
+}
+
+export default defineEventHandler(async (event) => {
+  const { logglyToken, logglyEndpoint, public: pub } = useRuntimeConfig()
+  if (!pub?.logglyEnabled || !logglyToken) {
+    return { ok: false, skipped: true }
+  }
+
+  const body = await readBody<LogglyBody>(event)
+
+  const scrubbed = {
+    level: body?.level ?? 'error',
+    message: body?.message?.toString().slice(0, 5000),
+    tags: [...new Set([...(pub.logglyTags || []), ...(body?.tags || [])])].slice(0, 10),
+    meta: sanitizeMeta(body?.meta),
+    error: body?.error ? serializeError(body.error) : undefined,
+    ts: new Date().toISOString()
+  }
+
+  const url = `${logglyEndpoint}/${encodeURIComponent(logglyToken)}/tag/${encodeURIComponent(scrubbed.tags.join(','))}`
+
+  try {
+    await $fetch(url, { method: 'POST', body: scrubbed })
+    return { ok: true }
+  }
+  catch {
+    // do not throw here to avoid cascading failures
+    return { ok: false }
+  }
+})

package/server/plugins/loggly.ts

@@ -0,0 +1,46 @@
+type NitroErrorCtx = {
+  event?: {
+    path?: string
+    method?: string
+    node?: { res?: { statusCode?: number } }
+  }
+}
+
+const toErrorShape = (err: unknown) => {
+  if (!err || typeof err !== 'object') {
+    return undefined
+  }
+  const e = err as { name?: string, message?: unknown, stack?: unknown }
+  return {
+    name: e.name || 'Error',
+    message: String(e.message ?? 'Error'),
+    stack: typeof e.stack === 'string' ? e.stack.split('\n').slice(0, 20) : undefined
+  }
+}
+
+export default defineNitroPlugin((nitroApp) => {
+  const config = useRuntimeConfig()
+  if (!config.public?.logglyEnabled || !config.logglyToken) return
+
+  nitroApp.hooks.hook('error', async (error: unknown, ctx?: NitroErrorCtx) => {
+    try {
+      await $fetch('/api/loggly', {
+        method: 'POST',
+        body: {
+          level: 'error',
+          message: (typeof error === 'object' && error && 'message' in error) ? String((error as { message?: unknown }).message) : 'Server error',
+          error: toErrorShape(error),
+          meta: {
+            url: ctx?.event?.path,
+            method: ctx?.event?.method,
+            status: ctx?.event?.node?.res?.statusCode
+          },
+          tags: ['server']
+        }
+      })
+    }
+    catch {
+      // swallow logging errors
+    }
+  })
+})