Connect/Express middleware to respond placeholders for 404 assets

Discover other projects

♡ serve-placeholder

Smart placeholder for missing assets

npm version npm downloads Github Actions Codecov


💵 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.


Install package:

# npm
npm install serve-placeholder

# yarn
yarn install serve-placeholder

# pnpm
pnpm install serve-placeholder


// ESM
import { servePlaceholder } from 'serve-placeholder'

// CommonJS
const { servePlaceholder } = require('serve-placeholder')

Create and add server middleware between serve-static and router middleware:

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:

app.use('/assets', serveStatic(..))
app.use('/assets', servePlaceholder())
++ app.use('/', placeholder({ skipUnknown: true }))
app.use('/', router)



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.


  • Default: 404

Sets statusCode for all handled responses. Set to false to disable overriding statusCode.


  • 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!


  • 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.


  • 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.


  • Default: true

Set headers to prevent accidentally caching 404 resources.

When enabled, these headers will be sent:

  'cache-control': 'no-cache, no-store, must-revalidate',
  'expires': '0',
  'pragma': 'no-cache'


  • Default: true

Sets an X-Placeholder header with value of handler name.


These are default handlers. 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 using corepack enable (use npm i -g corepack for Node.js < 16.10)
  • Install dependencies using pnpm install
  • Run interactive tests using pnpm dev


Made with 💛

Published under MIT License.