185 lines
5.5 KiB
Markdown
185 lines
5.5 KiB
Markdown
# ♡ serve-placeholder
|
|
|
|
<!-- automd:badges color=yellow -->
|
|
|
|
[](https://npmjs.com/package/serve-placeholder)
|
|
[](https://npmjs.com/package/serve-placeholder)
|
|
|
|
<!-- /automd -->
|
|
|
|
Smart placeholder for missing assets
|
|
|
|
## 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:
|
|
|
|
<!-- automd:pm-install -->
|
|
|
|
```sh
|
|
# ✨ Auto-detect
|
|
npx nypm install serve-placeholder
|
|
|
|
# npm
|
|
npm install serve-placeholder
|
|
|
|
# yarn
|
|
yarn add serve-placeholder
|
|
|
|
# pnpm
|
|
pnpm install serve-placeholder
|
|
|
|
# bun
|
|
bun install serve-placeholder
|
|
```
|
|
|
|
<!-- /automd -->
|
|
|
|
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({ skipUnknown: 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
|
|
const headers = {
|
|
"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.ts). 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
|
|
|
|
<details>
|
|
|
|
<summary>local development</summary>
|
|
|
|
- Clone this repository
|
|
- Install latest LTS version of [Node.js](https://nodejs.org/en/)
|
|
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
|
|
- Install dependencies using `pnpm install`
|
|
- Run interactive tests using `pnpm dev`
|
|
|
|
</details>
|
|
|
|
## License
|
|
|
|
<!-- automd:contributors author=pi0 license=MIT -->
|
|
|
|
Published under the [MIT](https://github.com/unjs/serve-placeholder/blob/main/LICENSE) license.
|
|
Made by [@pi0](https://github.com/pi0) and [community](https://github.com/unjs/serve-placeholder/graphs/contributors) 💛
|
|
<br><br>
|
|
<a href="https://github.com/unjs/serve-placeholder/graphs/contributors">
|
|
<img src="https://contrib.rocks/image?repo=unjs/serve-placeholder" />
|
|
</a>
|
|
|
|
<!-- /automd -->
|
|
|
|
<!-- automd:with-automd -->
|
|
|
|
---
|
|
|
|
_🤖 auto updated with [automd](https://automd.unjs.io)_
|
|
|
|
<!-- /automd -->
|