nuxt-betterstack

A Nuxt module for integrating BetterStack into your Nuxt application

nuxt-betterstack

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

npm install nuxt-betterstack

Setup

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

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

Configuration

The module supports two configuration approaches via runtimeConfig:

Public Configuration (Client + Server)

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

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
      },
    },
  },
})

Private Configuration (Server Only)

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

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
    },
  },
})

Options

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

Environment Variables

Config Type	Variable
Public	`NUXT_PUBLIC_BETTERSTACK_SOURCE_TOKEN`
Public	`NUXT_PUBLIC_BETTERSTACK_ENDPOINT`
Private	`NUXT_BETTERSTACK_SOURCE_TOKEN`
Private	`NUXT_BETTERSTACK_ENDPOINT`

Security Considerations

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).

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

Logger

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

In Vue Components


<script setup>
  const betterstack = useBetterstack()

  function handleClick () {
    betterstack.logger.info('Button clicked', {
      userId: user.id,
      action: 'purchase'
    })
  }

  async function handlePurchase () {
    try {
      // do something
      betterstack.logger.info('Purchase completed')
    } catch (error) {
      betterstack.logger.error('Purchase failed', { error: error.message })
    }
  }
</script>

In API Routes

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:

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:

const betterstack = useBetterstack()

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

Heartbeats

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

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

Local development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

License

MIT