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:

1npm install als-static-routes

Quick Start

Standalone Static Server

1const StaticRouter = require('als-static-routes');
2const staticRouter = new StaticRouter(__dirname);
3staticRouter.add('/', 'public');
4
5const http = require('http');
6const server = http.createServer(staticRouter.handler);
7server.listen(3000);

Or

1const StaticRouter = require('als-static-routes');
2const staticRouter = new StaticRouter(__dirname);
3staticRouter.add('/', 'public')
4
5const http = require('http');
6const server = http.createServer((req,res) => {
7   staticRouter.handler(req,res,(req,res) => {
8      // if no static files response with something else
9      res.end('Some another route')
10   })
11})
12server.listen(3000);

Integration with Express

1const StaticRouter = require('als-static-routes');
2const staticRouter = new StaticRouter(__dirname);
3staticRouter.add('/', 'public');
4
5const express = require('express');
6const app = express();
7app.use(staticRouter.handler);
8app.listen(3000);

API Reference

Constructor

Create a new router:

1const options = {
2   index: true, // Serve 'index.html' files for directory routes
3   download: false, // Send files with 'Content-Disposition: attachment'
4   etag: true, // Enable ETag header for caching optimization
5   charset: true // Append charset to 'Content-Type' header based on file content and mime type
6};
7
8const 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:

1router.add('/','public',{index:false})
2router.add('/route-to-file','/some/file.txt')
3router.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:

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

handler(req, res, [next])

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

1const server = http.createServer((req, res) => {
2   router.handler(req, res, () => {
3      res.writeHead(404);
4      res.end('Not Found');
5   });
6});

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

The handler by default:

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

Properties

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

2staticRouter.routes // routes