als-static-routes

als-static-routes is a utility for handling static files in web applications, enabling efficient static content management. It integrates seamlessly with frameworks like Express, but can also operate as a standalone static file server.

Key Features

Efficient Caching: once file used, it cached (effective cache management by memory limit with als-uni-store).
ETag Handling: Minimizes server load and enhances client load times by utilizing ETags.
Dynamic Charset Management: Automates character set determination to ensure text files are compatible with various clients.
Flexible Content Delivery: Supports direct file downloads and automated handling of HTML index files.
Real-time Configuration: Allows live changes to how files are served without needing to restart the server.

Installation

Install the package using npm:

npm install als-static-routes

Quick Start

Standalone Static Server

const StaticRouter = require('als-static-routes');
const staticRouter = new StaticRouter(__dirname);
staticRouter.add('/', 'public');

const http = require('http');
const server = http.createServer(staticRouter.handler);
server.listen(3000);

const StaticRouter = require('als-static-routes');
const staticRouter = new StaticRouter(__dirname);
staticRouter.add('/', 'public')

const http = require('http');
const server = http.createServer((req,res) => {
   staticRouter.handler(req,res,(req,res) => {
      // if no static files response with something else
      res.end('Some another route')
   })
})
server.listen(3000);

Integration with Express

const StaticRouter = require('als-static-routes');
const staticRouter = new StaticRouter(__dirname);
staticRouter.add('/', 'public');

const express = require('express');
const app = express();
app.use(staticRouter.handler);
app.listen(3000);

API Reference

Constructor

Create a new router:

const options = {
   index: true, // Serve 'index.html' files for directory routes
   download: false, // Send files with 'Content-Disposition: attachment'
   etag: true, // Enable ETag header for caching optimization
   charset: true // Append charset to 'Content-Type' header based on file content and mime type
};

const router = new StaticRouter(rootDir, options);

add(url, path, [options])

Add routes for serving files or directories:

url: URL path to serve the file or directory.
path: Path relative to rootDir.
options: Overrides constructor options for specific routes.

Throwing errors when:

path not exists
something wrong with directory reading

Examples:

router.add('/','public',{index:false})
router.add('/route-to-file','/some/file.txt')
router.add('/file-for-download','/some/file.txt',{download:true}) // download link

Each add, updates previous adds.

remove(path)

You can remove specific route or group of routes, by passing as argument url for routes which starts with this url.

Remove a file or directory from being served:

await router.remove('/path/to/resource');

handler(req, res, [next])

Handler function to integrate with Node.js HTTP server or Express:

const server = http.createServer((req, res) => {
   router.handler(req, res, () => {
      res.writeHead(404);
      res.end('Not Found');
   });
});

If next is not provided, a default 404 handler is used.

The handler by default:

next = () => {
   res.writeHead(404);
   res.end('Not Found');
}

Properties

staticRouter.store // instance of DiskStore(als-uni-store) for managing static files
staticRouter.routes // routes