Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aaronransley/nuxt-winston-log

Nuxt module for logging SSR errors using winston
https://github.com/aaronransley/nuxt-winston-log

error-handling logging nuxt nuxt-module nuxtjs winston

Last synced: 7 days ago
JSON representation

Nuxt module for logging SSR errors using winston

Host: GitHub
URL: https://github.com/aaronransley/nuxt-winston-log
Owner: aaronransley
Created: 2019-05-24T21:39:49.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2024-10-24T22:21:08.000Z (2 months ago)
Last Synced: 2024-10-30T00:43:58.964Z (2 months ago)
Topics: error-handling, logging, nuxt, nuxt-module, nuxtjs, winston
Language: JavaScript
Homepage:
Size: 76.2 KB
Stars: 45
Watchers: 3
Forks: 10
Open Issues: 5
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md

Awesome Lists containing this project

README

# nuxt-winston-log

A Nuxt `2.x` module to add [winston](https://github.com/winstonjs/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
3. `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](https://nodejs.org/dist/latest-v10.x/docs/api/http.html#http_class_http_incomingmessage):

```js
{
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](http://jsonlines.org/) format.

# Installation

1. Install npm package

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

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

```js
{
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](https://github.com/winstonjs/winston#creating-your-own-logger) and wire up middleware.

The default values are:

```js
// ...
{
// 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](https://github.com/winstonjs/winston/blob/master/docs/transports.md#file-transport), pass options to the `transportOptions` key:

Example in your apps `~/nuxt.config.js` file:
```js
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](https://github.com/winstonjs/winston#creating-your-own-logger), set `useDefaultLogger` option to `false`, and make sure you provide a custom set of `loggerOptions` to be passed to [Winston's `createLogger`](https://github.com/winstonjs/winston#creating-your-own-logger) under the hood:

Example in your apps `~/nuxt.config.js` file:
```js
// 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:
```js
// ...
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`:
```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`:
```js
// ...
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](https://github.com/aaronransley/nuxt-winston-log/blob/master/index.js#L58-L89).

Example in your apps `~/nuxt.config.js` file:
```js
// ...
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](https://nuxtjs.org/docs/2.x/directory-structure/modules#write-your-own-module).

# Using `process.winstonLog` in a Nuxt Module

Because modules are executed sequentially, any additional [Nuxt modules](https://nuxtjs.org/docs/2.x/directory-structure/modules#write-your-own-module) should be loaded _after the `nuxt-winston-log` module_. You can then access the logger instance via `process.winstonLog` as needed.

# [Changelog](./CHANGELOG.md)