TypeScript icon, indicating that this package has built-in type declarations

    2.0.1 • Public • Published

    ♡ 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({ skipUnkown: 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.




    npm i serve-placeholder

    DownloadsWeekly Downloads






    Unpacked Size

    19 kB

    Total Files


    Last publish


    • atinux
    • pi0