# connect-gzip-static

> gzip/brotli static middleware for connect - serves compressed files if they exist, falls through to connect-static if they don't

Latest version **5.0.0** (published 2025-10-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install connect-gzip-static
pnpm add connect-gzip-static
yarn add connect-gzip-static
bun add connect-gzip-static
```

## Health

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

Positive: esm support; no vulnerabilities; has provenance.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2025-10-25 |
| First published | 2013-09-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >= 22 |
| Dependencies | 5 |
| Unpacked size | 7.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 41 |
| Author | Damian Krzeminski |
| Maintainers | pirxpilot |
| Keywords | connect, middleware, gzip, brotli, compress |

## Links

- npm: https://www.npmjs.com/package/connect-gzip-static
- Repository: https://github.com/pirxpilot/connect-gzip-static
- Homepage: https://github.com/pirxpilot/connect-gzip-static#readme
- Issues: https://github.com/pirxpilot/connect-gzip-static/issues
- npm.io page: https://npm.io/package/connect-gzip-static

## Dependencies (5)

- [send](https://npm.io/package/send.md) ~0 || ~1
- [debug](https://npm.io/package/debug.md) ~4
- [parseurl](https://npm.io/package/parseurl.md) ~1
- [mime-types](https://npm.io/package/mime-types.md) ~2||~3
- [serve-static](https://npm.io/package/serve-static.md) ~1 || ~2

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 5.0.0 (latest) — 2025-10-25
- 4.2.2 — 2025-05-18
- 4.2.1 — 2024-12-29
- 4.2.0 — 2024-12-03
- 4.1.0 — 2024-12-03
- 4.0.0 — 2023-10-16
- 3.0.1 — 2023-10-16
- 3.0.0 — 2022-05-14
- 2.1.1 — 2017-08-27
- 2.1.0 — 2017-08-26
- 2.0.1 — 2017-02-18
- 2.0.0 — 2017-02-07
- 1.0.0 — 2014-10-18
- 0.4.1 — 2014-09-30
- 0.4.0 — 2014-08-27
- … 6 more at https://npm.io/package/connect-gzip-static/versions

## README

[![NPM version][npm-image]][npm-url]
[![Build Status][build-image]][build-url]
[![Dependency Status][deps-image]][deps-url]

# connect-gzip-static

Middleware for [connect]: serves compressed files if they exist, falls through to connect-static
if they don't, or if browser does not send 'Accept-Encoding' header.

You should use `connect-gzip-static` if your build process already creates compressed (using gzip, 
[brotli], or [zstd]) files. If you want to compress your data on the fly use [compression]
middleware. And if you want to compress your files dynamically you may want to look up [connect
gzip].

## Installation

	  $ npm install connect-gzip-static

## Options

gzip-static is meant to be a drop in replacement for [connect static] middleware. Use the same
options as you would with [connect static].


## Usage

```javascript
var gzipStatic = require('connect-gzip-static');
var oneDay = 86400000;

connect()
  .use(gzipStatic(__dirname + '/public'))

connect()
  .use(gzipStatic(__dirname + '/public', { maxAge: oneDay }))
```

## How it works

We start by locating all compressed files (ie. _files with .gz and .br extensions_) in `root`
directory. All HTTP GET and HTTP HEAD requests with Accept-Encoding header set to gzip are checked
against the list of compressed files and, if possible, fulfilled by returning the compressed
versions. If compressed version is not found or if the request does not have an appropriate Accept-
Encoding header, the request is processed in the same way as standard static middleware would
handle it.

## Debugging

This project uses [debug] module. To enable the debug log, just set the debug enviromental variable:

    DEBUG="connect:gzip-static"

# License

MIT © [Damian Krzeminski](https://pirxpilot.me)

[brotli]: https://en.wikipedia.org/wiki/Brotli
[zstd]: https://en.wikipedia.org/wiki/Zstd

[debug]: https://github.com/visionmedia/debug
[connect]: https://github.com/senchalabs/connect
[connect static]: https://github.com/expressjs
[compression]: https://github.com/expressjs/compression
[connect gzip]: https://github.com/tikonen/connect-gzip

[npm-image]: https://img.shields.io/npm/v/connect-gzip-static
[npm-url]: https://npmjs.org/package/connect-gzip-static

[build-url]: https://github.com/pirxpilot/connect-gzip-static/actions/workflows/check.yaml
[build-image]: https://img.shields.io/github/actions/workflow/status/pirxpilot/connect-gzip-static/check.yaml?branch=main
 
[deps-image]: https://img.shields.io/librariesio/release/npm/connect-gzip-static
[deps-url]: https://libraries.io/npm/connect-gzip-static

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