@routup/assets NPM

@routup/assets

This is a plugin for serving static files from a specified directory.

Table of Contents

Installation

npm install @routup/assets --save

Documentation

To read the docs, visit https://routup.net

Usage

Create a new middleware function to serve files from within a given directory. When a file is not found, instead of sending a 404 response, this module will instead call next() to move on to the next middleware, allowing for stacking and fall-backs.

import {createServer} from 'node:http';
import {
    createNodeDispatcher,
    Router
} from 'routup';
import { assets } from '@routup/assets';

const router = new Router();

// serve static files of folder: public
router.use(assets('public'));

const server = createServer(createNodeDispatcher(router));
server.listen(3000);

Multiple Directories

Sometimes it may be necessary to serve static files from multiple directories. To accomplish this, this plugin can be used multiple times. An example of this is shown below:

import {createServer} from 'node:http';
import {
    createNodeDispatcher,
    Router
} from 'routup';
import { assets } from '@routup/assets';

const router = new Router();

router.use(assets('public'));
router.use(assets('files'));

const server = createServer(createNodeDispatcher(router));
server.listen(3000);

This will allow to serve files from the public and the files directories. When a request for a file is made, those in the public directory will be checked before those in the files directory. If a file with the same name exists in both directories, the one in the public directory will be served.

Mount Path

It is also possible to define a mount path for a root directory. This is done as follows:

import {createServer} from 'node:http';
import {
    createNodeDispatcher,
    Router
} from 'routup';
import { assets } from '@routup/assets';

const router = new Router();

router.use('/public', assets('public'));

const server = createServer(createNodeDispatcher(router));
server.listen(3000);

With this setup, requests for files in the public directory must start with /public.

Options

The assets function takes an optional options object. The available options are:

scan

Type: Boolean
Default: true
Description: Define if the metadata of given files in the directory should be preloaded. The advantage here is, that the filesystem must not be traversed on every request.

cacheMaxAge

Type: Number
Default: 0
Description: Set the max-age (in seconds) directive of the cache-control header.

cacheImmutable

Type: Boolean
Default: false
Description: Append the immutable directive to the cache-control header.

fallback

Type: Boolean|String
Default: false
Description: Resolve files, which are not found to a specific directory (default: '/')

fallbackIgnores

Type: RegExp[]
Default: []
Description: Specify paths/patterns that should not be forwarded to the fallback path.

fallthrough

Type: Boolean
Default: true
Description: Pass the request to the next handler, if no file was found and the fallback strategy is disabled.

extensions

Type: String[]
Default: ['html', 'htm']
Description: Set file extension fallbacks. When set, if a file is not found, the middleware will search for files with the specified extensions and serve the first one that exists.