# finalhandler

> Node.js final http responder

Latest version **2.1.1** (published 2025-12-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install finalhandler
pnpm add finalhandler
yarn add finalhandler
bun add finalhandler
```

## Health

**Score 58/100 (C)** — status: stable.

Positive: has types package; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2025-12-01 |
| First published | 2014-06-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/finalhandler) |
| Module format | CommonJS |
| Node | >= 18.0.0 |
| Dependencies | 6 |
| Unpacked size | 17.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 241 |
| Author | Douglas Christopher Wilson |
| Maintainers | ulisesgascon, wesleytodd, dougwilson |

## Links

- npm: https://www.npmjs.com/package/finalhandler
- Repository: https://github.com/pillarjs/finalhandler
- Homepage: https://github.com/pillarjs/finalhandler#readme
- Issues: https://github.com/pillarjs/finalhandler/issues
- Funding: https://opencollective.com/express
- npm.io page: https://npm.io/package/finalhandler

## Dependencies (6)

- [debug](https://npm.io/package/debug.md) ^4.4.0
- [parseurl](https://npm.io/package/parseurl.md) ^1.3.3
- [statuses](https://npm.io/package/statuses.md) ^2.0.1
- [encodeurl](https://npm.io/package/encodeurl.md) ^2.0.0
- [escape-html](https://npm.io/package/escape-html.md) ^1.0.3
- [on-finished](https://npm.io/package/on-finished.md) ^2.4.1

## Recent versions

- 2.1.1 (latest) — 2025-12-01
- 1.3.2 (latest-1.x) — 2025-12-01
- 2.1.0 — 2025-03-05
- 1.3.1 — 2024-09-11
- 1.3.0 — 2024-09-03
- 2.0.0 — 2024-09-02
- 1.2.1 — 2024-09-02
- 1.2.0 — 2022-03-23
- 1.1.2 — 2019-05-10
- 1.1.1 — 2018-03-06
- 1.1.0 — 2017-09-25
- 1.0.6 — 2017-09-22
- 1.0.5 — 2017-09-16
- 1.0.4 — 2017-08-04
- 1.0.3 — 2017-05-17
- … 20 more at https://npm.io/package/finalhandler/versions

## README

# finalhandler

[![NPM Version][npm-image]][npm-url]
[![NPM Downloads][downloads-image]][downloads-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]
[![OpenSSF Scorecard Badge][ossf-scorecard-badge]][ossf-scorecard-visualizer]

Node.js function to invoke as the final step to respond to HTTP request.

## Installation

This is a [Node.js](https://nodejs.org/en/) module available through the
[npm registry](https://www.npmjs.com/). Installation is done using the
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):

```sh
$ npm install finalhandler
```

## API

```js
const finalhandler = require('finalhandler')
```

### finalhandler(req, res, [options])

Returns function to be invoked as the final step for the given `req` and `res`.
This function is to be invoked as `fn(err)`. If `err` is falsy, the handler will
write out a 404 response to the `res`. If it is truthy, an error response will
be written out to the `res` or `res` will be terminated if a response has already
started.

When an error is written, the following information is added to the response:

  * The `res.statusCode` is set from `err.status` (or `err.statusCode`). If
    this value is outside the 4xx or 5xx range, it will be set to 500.
  * The `res.statusMessage` is set according to the status code.
  * The body will be the HTML of the status code message if `env` is
    `'production'`, otherwise will be `err.stack`.
  * Any headers specified in an `err.headers` object.

The final handler will also unpipe anything from `req` when it is invoked.

#### options.env

By default, the environment is determined by `NODE_ENV` variable, but it can be
overridden by this option.

#### options.onerror

Provide a function to be called with the `err` when it exists. Can be used for
writing errors to a central location without excessive function generation. Called
as `onerror(err, req, res)`.

## Examples

### always 404

```js
const finalhandler = require('finalhandler')
const http = require('http')

const server = http.createServer((req, res) => {
  const done = finalhandler(req, res)
  done()
})

server.listen(3000)
```

### perform simple action

```js
const finalhandler = require('finalhandler')
const fs = require('fs')
const http = require('http')

const server = http.createServer((req, res) => {
  const done = finalhandler(req, res)

  fs.readFile('index.html', (err, buf) => {
    if (err) return done(err)
    res.setHeader('Content-Type', 'text/html')
    res.end(buf)
  })
})

server.listen(3000)
```

### use with middleware-style functions

```js
const finalhandler = require('finalhandler')
const http = require('http')
const serveStatic = require('serve-static')

const serve = serveStatic('public')

const server = http.createServer((req, res) => {
  const done = finalhandler(req, res)
  serve(req, res, done)
})

server.listen(3000)
```

### keep log of all errors

```js
const finalhandler = require('finalhandler')
const fs = require('fs')
const http = require('http')

const server = http.createServer((req, res) => {
  const done = finalhandler(req, res, { onerror: logerror })

  fs.readFile('index.html', (err, buf) => {
    if (err) return done(err)
    res.setHeader('Content-Type', 'text/html')
    res.end(buf)
  })
})

server.listen(3000)

function logerror (err) {
  console.error(err.stack || err.toString())
}
```

## License

[MIT](LICENSE)

[npm-image]: https://img.shields.io/npm/v/finalhandler.svg
[npm-url]: https://npmjs.org/package/finalhandler
[node-image]: https://img.shields.io/node/v/finalhandler.svg
[node-url]: https://nodejs.org/en/download
[coveralls-image]: https://img.shields.io/coveralls/pillarjs/finalhandler.svg
[coveralls-url]: https://coveralls.io/r/pillarjs/finalhandler?branch=master
[downloads-image]: https://img.shields.io/npm/dm/finalhandler.svg
[downloads-url]: https://npmjs.org/package/finalhandler
[github-actions-ci-image]: https://github.com/pillarjs/finalhandler/actions/workflows/ci.yml/badge.svg
[github-actions-ci-url]: https://github.com/pillarjs/finalhandler/actions/workflows/ci.yml
[ossf-scorecard-badge]: https://api.scorecard.dev/projects/github.com/pillarjs/finalhandler/badge
[ossf-scorecard-visualizer]: https://ossf.github.io/scorecard-visualizer/#/projects/github.com/pillarjs/finalhandler

---
_Source: https://npm.io/package/finalhandler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._