595aea1 more query options + view options [كارل مبارك]
# ♡ serve-placeholder
> Smart placeholder for missing assets
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![Github Actions][github-actions-src]][github-actions-href]
[![Codecov][codecov-src]][codecov-href]
## Why?
**💵 Rendering Errors is costly**
Serving each 404 page for assets adds extra load to the server and increases crashing chances. This is crucial for setups with server-side-rendering and removes additional SSR loads when assets like `robots.txt` or `favicon.ico` don't exist.
**👌 Meaningful Responses**
We can always send a better 404 response than an HTML page by knowing file extensions. For example, we send a fallback transparent 1x1 image for image extensions.
**🔍 SEO Friendly**
Instead of indexing invalid URLs with HTML pages, we properly send 404 and the right content type.
## Usage
Install package:
```sh
# npm
npm install serve-placeholder
# yarn
yarn install serve-placeholder
# pnpm
pnpm install serve-placeholder
```
Import:
```js
// ESM
import { servePlaceholder } from 'serve-placeholder'
// CommonJS
const { servePlaceholder } = require('serve-placeholder')
```
Create and add server middleware between serve-static and router middleware:
```diff
app.use('/assets', serveStatic(..))
++ app.use('/assets', servePlaceholder())
app.use('/', router)
```
Additionally, we can have a default placeholder for arbitrary routes which handles known extensions **assuming other routes have no extension**:
```diff
app.use('/assets', serveStatic(..))
app.use('/assets', servePlaceholder())
++ app.use('/', placeholder({ skipUnkown: true }))
app.use('/', router)
```
## Options
### `handlers`
A mapping from file extensions to the handler. Extensions should start with *dot* like `.js`.
You can disable any of the handlers by setting the value to `null`
If the value of a handler is set to `false`, the middleware will be ignored for that extension.
### `statusCode`
- Default: `404`
Sets `statusCode` for all handled responses. Set to `false` to disable overriding statusCode.
### `skipUnknown`
- Default: `false`
Skip middleware when no handler is defined for the current request.
Please note that if this option is set to `true`, then `default` handler will be disabled!
### `placeholders`
- Type: `Object`
A mapping from handler to placeholder. Values can be `String` or `Buffer`. You can disable any of the placeholders by setting the value to `false`.
### `mimes`
- Type: `Object`
A mapping from handler to the mime type. Mime type will be set as `Content-Type` header. You can disable sending any of the mimes by setting the value to `false`.
### `cacheHeaders`
- Default: `true`
Set headers to prevent accidentally caching 404 resources.
When enabled, these headers will be sent:
```js
{
'cache-control': 'no-cache, no-store, must-revalidate',
'expires': '0',
'pragma': 'no-cache'
}
```
### `placeholderHeader`
- Default: `true`
Sets an `X-Placeholder` header with value of handler name.
## Defaults
These are [default handlers](./src/defaults.js). You can override every of them using provided options.
Handler | Extensions | Mime type | Placeholder
-----------|------------------------|--------------------------|-------------------
`default` | any unknown extension | - | -
`css` | `.css` | `text/css` | `/* style not found */`
`html` | `.html`, `.htm` | `text/html` | `<!-- page not found -->`
`js` | `.js` | `application/javascript` | `/* script not found */`
`json` | `.json` | `application/json` | `{}`
`map` | `.map` | `application/json` | [empty sourcemap v3 json]
`plain` | `.txt`, `.text`, `.md` | `text/plain` | [empty]
`image` | `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.bmp`, `.ico` | `image/gif` | [transparent 1x1 image]
## 💻 Development
- Clone this repository
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js < 16.10)
- Install dependencies using `pnpm install`
- Run interactive tests using `pnpm dev`
## License
Made with 💛
Published under [MIT License](./LICENSE).
<!-- Badges -->
[npm-version-src]: https://img.shields.io/npm/v/serve-placeholder?style=flat-square
[npm-version-href]: https://npmjs.com/package/serve-placeholder
[npm-downloads-src]: https://img.shields.io/npm/dm/serve-placeholder?style=flat-square
[npm-downloads-href]: https://npmjs.com/package/serve-placeholder
[github-actions-src]: https://img.shields.io/github/workflow/status/unjs/serve-placeholder/ci/main?style=flat-square
[github-actions-href]: https://github.com/unjs/serve-placeholder/actions?query=workflow%3Aci
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/serve-placeholder/main?style=flat-square
[codecov-href]: https://codecov.io/gh/unjs/serve-placeholder