nuxt-betterstack

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]

A Nuxt module for integrating BetterStack logging into your Nuxt application. Send logs from
both server-side (SSR) and client-side to BetterStack with ease.

Features

- Dual-environment logging - Works seamlessly on both server and client
- Auto-import composable - useBetterstack() available everywhere
- Server utilities - Use in API routes and server middleware
- Flexible configuration - Use public config for client+server or private config for server-only
- Runtime config - Configure via environment variables for different deployments
- TypeScript support - Fully typed API

Installation

``bash
npm install nuxt-betterstack
`

Setup

Add the module to your nuxt.config.ts and configure via runtimeConfig:

`ts
export default defineNuxtConfig({
modules: ['nuxt-betterstack']
})
`

Configuration

The module supports two configuration approaches via runtimeConfig:

$3

Use runtimeConfig.public.betterstack when you need logging on both client and server:

`ts
export default defineNuxtConfig({
modules: ['nuxt-betterstack'],

runtimeConfig: {
public: {
betterstack: {
sourceToken: 'your-token', // Set via NUXT_PUBLIC_BETTERSTACK_SOURCE_TOKEN
endpoint: 'https://your-endpoint', // Set via NUXT_PUBLIC_BETTERSTACK_ENDPOINT
},
},
},
})
`

$3

Use runtimeConfig.betterstack for server-side only logging. This keeps your token private and out of the client bundle:

`ts
export default defineNuxtConfig({
modules: ['nuxt-betterstack'],

runtimeConfig: {
betterstack: {
sourceToken: 'your-token', // Set via NUXT_BETTERSTACK_SOURCE_TOKEN
endpoint: 'https://your-endpoint', // Set via NUXT_BETTERSTACK_ENDPOINT
},
},
})
`

$3

| Option | Type | Description |
|---------------|----------|------------------------------------|
| sourceToken | string | Your BetterStack source token |
| endpoint | string | The BetterStack ingesting endpoint |

$3

| Config Type | Variable |
|-------------|---------------------------------------|
| Public | NUXT_PUBLIC_BETTERSTACK_SOURCE_TOKEN |
| Public | NUXT_PUBLIC_BETTERSTACK_ENDPOINT |
| Private | NUXT_BETTERSTACK_SOURCE_TOKEN |
| Private | NUXT_BETTERSTACK_ENDPOINT |

$3

- Use private config if you only need server-side logging (API routes, server middleware). This prevents your BetterStack token from being exposed to the client.
- Use public config if you need client-side logging (Vue components, browser events). Be aware that the token will be visible in the client bundle.
- You can use both configurations together: private config for sensitive server logs and public config for general client-side telemetry (using separate BetterStack sources).

Graceful Fallback

When sourceToken or endpoint is not configured, logs are simply not sent to BetterStack. This allows you to safely run your application locally or in development without flooding your BetterStack logs.

Usage

$3

The module provides a flexible logging API that works on both server and client.

#### In Vue Components

`vue


`

#### In API Routes

`ts
export default defineEventHandler(async (event) => {
const betterstack = useBetterstack()

betterstack.logger.info('Fetching users', {
path: '/api/users'
})
return null
})
`

#### Log Levels

The logger provides four log levels:

`ts
const betterstack = useBetterstack()

betterstack.logger.debug('Debug message', {context: 'optional'})
betterstack.logger.info('Info message', {context: 'optional'})
betterstack.logger.warn('Warning message', {context: 'optional'})
betterstack.logger.error('Error message', {context: 'optional'})
`

#### Flushing Logs
You can manually flush logs to ensure they are sent to BetterStack:

`ts
const betterstack = useBetterstack()

await betterstack.logger.info('Important action')
await betterstack.logger.flush() // Ensure logs are sent before redirect
`

$3

The module supports BetterStack Heartbeat monitoring to monitor your scheduled tasks and cron jobs.

> Setup: Create a Heartbeat monitor in your BetterStack dashboard and copy the heartbeat ID.

#### Basic Usage

`ts
const betterstack = useBetterstack()

// Send success signal
await betterstack.heartbeat.success('your-heartbeat-id')

// Send failure signal
await betterstack.heartbeat.failure('your-heartbeat-id')

// Send failure with custom exit code
await betterstack.heartbeat.failure('your-heartbeat-id', '500')
`

Development

License

MIT

[npm-version-src]: https://img.shields.io/npm/v/nuxt-betterstack/latest.svg?style=flat&colorA=020420&colorB=00DC82

[npm-version-href]: https://npmjs.com/package/nuxt-betterstack

[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-betterstack.svg?style=flat&colorA=020420&colorB=00DC82

[npm-downloads-href]: https://npm.chart.dev/nuxt-betterstack

[license-src]: https://img.shields.io/npm/l/nuxt-betterstack.svg?style=flat&colorA=020420&colorB=00DC82

[license-href]: https://npmjs.com/package/nuxt-betterstack

[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt

[nuxt-href]: https://nuxt.com