# on-headers

> Execute a listener when a response is about to write headers

Latest version **1.1.0** (published 2025-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install on-headers
pnpm add on-headers
yarn add on-headers
bun add on-headers
```

## Health

**Score 43/100 (D)** — status: stable.

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

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2025-07-17 |
| First published | 2014-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/on-headers) |
| Module format | CommonJS |
| Node | >= 0.8 |
| Dependencies | 0 |
| Unpacked size | 8.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 162 |
| Author | Douglas Christopher Wilson |
| Maintainers | ulisesgascon, blakeembrey, dougwilson |
| Keywords | event, headers, http, onheaders |

## Links

- npm: https://www.npmjs.com/package/on-headers
- Repository: https://github.com/jshttp/on-headers
- Homepage: https://github.com/jshttp/on-headers#readme
- Issues: https://github.com/jshttp/on-headers/issues
- npm.io page: https://npm.io/package/on-headers

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 1.1.0 (latest) — 2025-07-17
- 1.0.2 — 2019-02-22
- 1.0.1 — 2015-09-30
- 1.0.0 — 2014-08-10
- 0.0.0 — 2014-05-14

## README

# on-headers

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Node.js Version][node-image]][node-url]
[![Build Status][ci-image]][ci-url]
[![Coverage Status][coveralls-image]][coveralls-url]

Execute a listener when a response is about to write headers.

## 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 on-headers
```

## API

<!-- eslint-disable no-unused-vars -->

```js
var onHeaders = require('on-headers')
```

### onHeaders(res, listener)

This will add the listener `listener` to fire when headers are emitted for `res`.
The listener is passed the `response` object as it's context (`this`). Headers are
considered to be emitted only once, right before they are sent to the client.

When this is called multiple times on the same `res`, the `listener`s are fired
in the reverse order they were added.

## Examples

```js
var http = require('http')
var onHeaders = require('on-headers')

http
  .createServer(onRequest)
  .listen(3000)

function addPoweredBy () {
  // set if not set by end of request
  if (!this.getHeader('X-Powered-By')) {
    this.setHeader('X-Powered-By', 'Node.js')
  }
}

function onRequest (req, res) {
  onHeaders(res, addPoweredBy)

  res.setHeader('Content-Type', 'text/plain')
  res.end('hello!')
}
```

## Testing

```sh
$ npm test
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/jshttp/on-headers/master?label=ci
[ci-url]: https://github.com/jshttp/on-headers/actions/workflows/ci.yml
[coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/on-headers/master
[coveralls-url]: https://coveralls.io/r/jshttp/on-headers?branch=master
[node-image]: https://badgen.net/npm/node/on-headers
[node-url]: https://nodejs.org/en/download
[npm-downloads-image]: https://badgen.net/npm/dm/on-headers
[npm-url]: https://npmjs.org/package/on-headers
[npm-version-image]: https://badgen.net/npm/v/on-headers

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