aaronransley/nuxt-winston-log

Nuxt module for logging SSR errors using winston

nuxt-winston-log

A Nuxt 2.x module to add winston-powered logging to your Nuxt application.

• Works with: Nuxt @2.x projects running on a server (e.g. universal, SSR mode).
• Does not support: Statically generated Nuxt projects (i.e. SSG via nuxt generate).

Introduction

By default the following events are captured:

1. error level: SSR errors via Nuxt middleware hooks
2. info level: Basic access logs for serverMiddleware endpoints + pages in your Nuxt app

All logs captured include a bit of additional metadata pulled from the Node.js request object:

{
  url: 'https://cool.net',
  method: 'GET',
  headers: {
    'X-Plumbus': "36f7b241-2910-4439-8671-749fc77dc213"
  }
}

Logs are output at ./logs/{NODE_ENV}.log by default. They are created in JSON Lines format.

Installation

1. Install npm package

$ yarn add nuxt-winston-log # or npm i nuxt-winston-log

2. Edit your nuxt.config.js file to add module

{
  modules: ['nuxt-winston-log']
}

3. Change options using the winstonLog key as needed. See Usage section for details.

Usage

1. By default, nuxt-winston-log exposes some basic options for common needs. Internally, these options are used to create a basic Logger instance and wire up middleware.

   The default values are:

   // ...
   {
     // Path that log files will be created in.
     // Change this to keep things neat.
     logPath: './logs',
   
     // Name of log file.
     // Change this to keep things tidy.
     logName: `${process.env.NODE_ENV}.log`,
   
     // Setting to determine if filesystem is accessed to auto-create logPath.
     // Set this to `false` for non-filesystem based logging setups.
     autoCreateLogPath: true,
   
     // Setting to determine if default logger instance is created for you.
     // Set this to `false` and provide `loggerOptions` (usage item #3) to
     // completely customize the logger instance (formatting, transports, etc.)
     useDefaultLogger: true,
   
     // Settings to determine if default handlers should be
     // registered for requests and errors respectively.
     // Set to `true` to skip request logging (level: info).
     skipRequestMiddlewareHandler: false,
     // Set to `true` to skip error logging (level: error).
     skipErrorMiddlewareHandler: false
   }
   // ...

2. To customize the File Transport instance, pass options to the transportOptions key:

   Example in your apps ~/nuxt.config.js file:

   import path from 'path'
   const logfilePath = path.resolve(process.cwd(), './logs', `${process.env.NODE_ENV}.log`)
   
   export default {
     // Configure nuxt-winston-log module
     winstonLog: {
       transportOptions: {
         filename: logfilePath
       }
     }
   }

3. To customize the Logger instance, set useDefaultLogger option to false, and make sure you provide a custom set of loggerOptions to be passed to Winston's createLogger under the hood:

   Example in your apps ~/nuxt.config.js file:

   // Note imports from winston core for transports, formatting helpers, etc.
   import { format, transports } from 'winston'
   const { combine, timestamp, label, prettyPrint } = format
   
   export default {
     // Configure nuxt-winston-log module
     winstonLog: {
       useDefaultLogger: false,
       loggerOptions: {
         format: combine(
           label({ label: 'Custom Nuxt logging!' }),
           timestamp(),
           prettyPrint()
         ),
         transports: [new transports.Console()]
       }
     }
   }

4. To disable automatic creation of the logPath directory, set autoCreateLogPath option to false:

   Example in your apps ~/nuxt.config.js file:

   // ...
   export default {
     // Configure nuxt-winston-log module
     winstonLog: {
       autoCreateLogPath: false
     }
   }
   // ...

5. To access the winston logger instance from within Nuxt lifecycle areas, use the $winstonLog key from the Nuxt context object. Note: This is only available for server-side executions. For example, because asyncData is an isomorphic function in Nuxt, you will need to guard $winstonLog access with something like if (process.server) { ... }

   Example nuxtServerInit in your apps ~/store/index.js:

   // ...
   export const actions = {
     async nuxtServerInit({ store, commit }, { req, $winstonLog }) {
       $winstonLog.info(`x-forwarded-host: ${req.headers['x-forwarded-host']}`)
     }
   }
   // ...

   Example asyncData in your apps ~/pages/somepage.vue:

   // ...
   asyncData(context) {
     if (process.server) {
       context.$winstonLog.info('Hello from asyncData on server')
     }
   }
   // ...

6. To disable default request and error logging behaviors, the skipRequestMiddlewareHandler and skipErrorMiddlewareHandler options can be set to true. For more information on what these handlers do out of the box, see the source at the bottom of the ~/index.js file.

   Example in your apps ~/nuxt.config.js file:

   // ...
   export default {
     // Configure nuxt-winston-log module
     winstonLog: {
       skipRequestMiddlewareHandler: true,
       skipErrorMiddlewareHandler: true
     }
   }
   // ...

   Adding your own middleware handlers to Nuxt is outside the scope of this documentation, but can be accomplished using a custom module of your own.

Using process.winstonLog in a Nuxt Module

Because modules are executed sequentially, any additional Nuxt modules should be loaded after the nuxt-winston-log module. You can then access the logger instance via process.winstonLog as needed.

Changelog