1.11.41 • Published 10 months ago

jai-static v1.11.41

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

Jai Static

Jai Logo A powerful and flexible Node.js module for serving static files (images, videos, stream videos range, pdf, documents etc) with ease. Jai Static offers seamless integration with any Node.js framework and provides fine-grained control over how your static assets are served.


Twitter Follow Linkedin: Harpal Singh GitHub followers npm version


Table of Contents

Features

  • 🚀 Lightning-fast static file serving
  • 🔧 Seamless integration with any Node.js framework
  • ⚙️ Highly configurable for precise control
  • 🗂️ Support for serving from multiple directories
  • 🔒 Secure by default with customizable security options
  • 📦 Efficient caching mechanisms
  • 🎯 Content negotiation and partial content support
  • 🔍 Extensible file discovery system
  • 📏 File size limit control
  • 🔣 Custom MIME type support

Quick Start

  1. Install Jai Static:

    npm install jai-static
  2. Create a simple server (e.g., server.js):

    const http = require('http');
    const JaiStatic = require('jai-static');
    
    const server = http.createServer(JaiStatic({ dir: './public' }));
    
    server.listen(3000, () => {
      console.log('Server running at http://localhost:3000/');
    });
  3. Create a public folder in your project root and add some files.

  4. Run your server:

    node server.js
  5. Visit http://localhost:3000 in your browser to see your static files served!

Installation

Install Jai Static with npm:

npm install jai-static

Usage Examples

Jai Server

const jaiServer = require('jai-server');

const app = jaiServer({
  static: {
    dir: `${__dirname}/public`,
    basePath: '/static'
  }
});

app.listen(3000, () => {
  console.log('Jai Server listening on http://localhost:3000/ ...');
});

Express

const express = require('express');
const JaiStatic = require('jai-static');

const app = express();

app.use('/assets', JaiStatic({
  dir: `${__dirname}/public`,
  maxAge: 3600,
  index: ['index.html', 'index.htm'],
  extensions: ['html', 'htm', 'json'],
  lastModified: true
}));

app.listen(3000, () => {
  console.log('Express server listening on http://localhost:3000/ ...');
});

HTTP

const http = require('http');
const JaiStatic = require('jai-static');

const server = http.createServer(JaiStatic({
  dir: `${__dirname}/public`,
  maxAge: 3600,
  headers: {
    'X-Powered-By': 'Jai Static'
  },
  acceptRanges: true,
  cacheControl: true
}));

server.listen(3000, () => {
  console.log('HTTP server listening on http://localhost:3000/ ...');
});

Configuration Options

Jai Static offers a wide range of configuration options to fine-tune its behavior:

OptionTypeDefaultDescription
dirstring-Destination folder path (Required)
rootstring__dirnameRoot directory for serving files
basePathstring/Base URL path for serving files
urlPathstring/Alias for basePath
dotfilesstring'deny'How to treat dotfiles: 'allow', 'deny', or 'ignore'
maxAgenumber3600Browser cache max-age in seconds
headersobject{}Custom headers to set on the response
lastModifiedbooleantrueSet the Last-Modified header
etagbooleantrueEnable or disable ETag generation
acceptRangesbooleantrueEnable or disable accepting byte ranges
cacheControlbooleantrueEnable or disable setting Cache-Control header
indexstring | string[]'index.html'Default file name(s) for directory requests
extensionsstring[]['html', 'htm']File extensions to try when not specified
allowedExtensionsstring[]['*']Allowed file extensions. Use ['*'] to allow all
fallthroughbooleantruePass to next middleware if file not found
immutablebooleanfalseAdd immutable directive to Cache-Control header
defaultMimeTypestring'application/octet-stream'Default MIME type for files with unknown extensions
mimeTypesobject{}Custom MIME type mappings {"abc":"application/abc"}
maxAllowedSizenumber-Maximum allowed file size in bytes

Let's explore each option with examples:

dir (Required)

The directory from which to serve static files.

JaiStatic({ dir: './public' })

This will serve files from the 'public' folder in your project.

root

The root directory for resolving relative paths.

JaiStatic({ root: '/var/www', dir: 'html' })

This will serve files from '/var/www/html'.

basePath or urlPath

The base URL path for serving files.

JaiStatic({ dir: './public', basePath: '/static' })

Files in './public' will be accessible under 'http://yourdomain.com/static/'.

dotfiles

How to treat dotfiles (files starting with a dot).

JaiStatic({ dir: './public', dotfiles: 'ignore' })

Options: 'allow' (serve dotfiles), 'deny' (return 403 error), 'ignore' (pretend they don't exist).

maxAge

Browser cache max-age in seconds.

JaiStatic({ dir: './public', maxAge: 86400 }) // 1 day

This tells browsers to cache files for one day.

headers

Custom headers to set on the response.

JaiStatic({
  dir: './public',
  headers: { 'X-Powered-By': 'Jai Static' }
})

This adds a custom header to all responses.

lastModified

Set the Last-Modified header.

JaiStatic({ dir: './public', lastModified: false })

This disables the Last-Modified header, which can be useful for privacy.

etag

Enable or disable ETag generation.

JaiStatic({ dir: './public', etag: false })

ETags help with caching, but disabling them can reduce server load.

acceptRanges

Enable or disable accepting byte ranges.

JaiStatic({ dir: './public', acceptRanges: true })

This allows browsers to request parts of a file, useful for media streaming.

cacheControl

Enable or disable setting Cache-Control header.

JaiStatic({ dir: './public', cacheControl: false })

Disabling this gives you more control over caching behavior.

index

Default file name(s) for directory requests.

JaiStatic({ dir: './public', index: ['index.html', 'index.htm'] })

When a directory is requested, Jai Static will look for these files.

extensions

File extensions to try when not specified.

JaiStatic({ dir: './public', extensions: ['html', 'htm', 'json'] })

If '/page' is requested, Jai Static will look for 'page.html', 'page.htm', and 'page.json'.

allowedExtensions

Allowed file extensions.

JaiStatic({ dir: './public', allowedExtensions: ['html', 'css', 'js'] })

This restricts serving to only the specified file types.

fallthrough

Pass to next middleware if file not found.

JaiStatic({ dir: './public', fallthrough: false })

If false, Jai Static will send a 404 response instead of passing to the next middleware.

immutable

Add immutable directive to Cache-Control header.

JaiStatic({ dir: './public', immutable: true, maxAge: 31536000 })

This tells browsers that the file will never change, improving caching.

defaultMimeType

Default MIME type for files with unknown extensions.

JaiStatic({ dir: './public', defaultMimeType: 'application/octet-stream' })

This sets the content type for files with unrecognized extensions.

mimeTypes

Custom MIME type mappings.

JaiStatic({
  dir: './public',
  mimeTypes: { 'dat': 'application/octet-stream' }
})

This allows you to set custom MIME types for specific file extensions.

maxAllowedSize

Maximum allowed file size in bytes.

JaiStatic({ dir: './public', maxAllowedSize: 5 * 1024 * 1024 }) // 5MB

This prevents serving files larger than 5MB.

Advanced Usage

Serving from Multiple Directories

You can serve files from multiple directories by chaining middleware:

const express = require('express');
const JaiStatic = require('jai-static');

const app = express();

app.use('/assets', JaiStatic({ dir: './public/assets' }));
app.use('/images', JaiStatic({ dir: './public/images', maxAge: 86400 }));
app.use('/docs', JaiStatic({ dir: './public/documents', dotfiles: 'allow' }));

app.listen(3000);

Custom Error Handling

Implement custom error handling by setting fallthrough to false and using a custom error handler:

const express = require('express');
const JaiStatic = require('jai-static');

const app = express();

app.use(JaiStatic({ 
  dir: './public', 
  fallthrough: false 
}));

app.use((err, req, res, next) => {
  if (err.statusCode === 404) {
    res.status(404).send('Custom 404: File not found');
  } else {
    next(err);
  }
});

app.listen(3000);

Performance Optimization

To optimize performance with Jai Static:

  1. Enable caching by setting appropriate maxAge and immutable options.
  2. Use etag for efficient cache validation.
  3. Enable acceptRanges for partial content support.
  4. Set cacheControl to true for better client-side caching.

Example of a performance-optimized configuration:

JaiStatic({
  dir: './public',
  maxAge: 86400 * 30, // 30 days
  immutable: true,
  etag: true,
  acceptRanges: true,
  cacheControl: true
})

Security Considerations

Jai Static provides several security features:

  1. Dotfiles: By default, access to dotfiles is denied. You can change this with the dotfiles option.
  2. Allowed Extensions: Use allowedExtensions to restrict which file types can be served.
  3. Directory Traversal: Jai Static automatically prevents directory traversal attacks.
  4. File Size Limit: Use maxAllowedSize to prevent serving excessively large files.

Example of a security-focused configuration:

JaiStatic({
  dir: './public',
  dotfiles: 'deny',
  allowedExtensions: ['html', 'css', 'js', 'png', 'jpg', 'gif'],
  maxAllowedSize: 10 * 1024 * 1024, // 10MB limit
  headers: {
    'X-Frame-Options': 'SAMEORIGIN',
    'X-XSS-Protection': '1; mode=block'
  }
})

Troubleshooting

If you encounter issues:

  1. Check if the dir path is correct and accessible.
  2. Ensure basePath matches your URL structure.
  3. Verify that file permissions allow Node.js to read the files.
  4. Check for conflicting middleware in your application.
  5. If files aren't being served, check the allowedExtensions setting.
  6. For large files, make sure they don't exceed the maxAllowedSize limit.

For more help, please open an issue on the GitHub repository.

License

MIT

Author

Harpal Singh: @hsk11 . Website: Jaijs.org.

#jaijs #cdn #image-server #jai-static #static-files #stream-video #static-server #middleware