Serving Static Files

LiteNode includes a powerful static asset loader that automatically serves files from a designated directory. The loader includes intelligent caching, file watching, and automatic content-type detection.

Basic Configuration

Default Directory

By default, LiteNode serves static files from the static directory:

const app = new LiteNode()
app.startServer()

Files in the static directory will be accessible at:
http://localhost:5000/static/path/to/file.

Custom Directory

You can specify a custom directory for static files:

const app = new LiteNode("public")
app.startServer()

Disabling Static Assets

To run LiteNode without static asset serving:

const app = new LiteNode("__NO_STATIC_DIR__")

Caching and Performance Features

Development Mode

In development, LiteNode implements validation caching using ETags. To enable development mode, set NODE_ENV to anything other than "production" in your environment or .env file:

NODE_ENV=development

Development mode features:

• File changes are detected automatically
• Browser caching uses validation (304 Not Modified) instead of time-based caching
• Files are cached in memory for faster serving
• Changes are visible on regular refresh (no hard refresh needed)

Production Mode

When NODE_ENV is set to "production":

• Static assets (images, styles, scripts, fonts) are cached for 24 hours
• Other content uses validation caching
• Memory caching is disabled for better memory management
• Optimal Cache-Control headers are set automatically

Automatic Content Type Detection

The loader includes:

• Cached MIME type lookups for improved performance
• Support for all common web file types
• Proper content-type headers for browser rendering

Supported File Types

Browser-Renderable Files

• Images: .avif, .gif, .ico, .jpeg, .jpg, .png, .svg, .webp
• Styles: .css
• Scripts: .js, .mjs
• Documents: .html, .txt, .pdf
• Data: .json, .xml
• Media: .wav, .mp3, .mp4, .webm, .ogg

Downloadable Files

• Archives: .zip (requires appropriate Content-Disposition header)

File Watching and Auto-Updates

The static directory is monitored for:

• New files (automatically served)
• File deletions (routes removed)
• File modifications (cache cleared)

Changes are handled automatically with no server restart required.

Error Handling

The loader provides consistent error handling with informative messages:

# Missing directory
[StaticAssetLoader] Error while reading static directory: "static" directory doesn't exist!
LiteNode will continue running without serving static assets.

# File serving errors
[StaticAssetLoader] Error serving file {path}: {error message}

# Directory scanning errors
[StaticAssetLoader] Error scanning directory {dir}: {error message}

Cross-Platform Compatibility

The loader handles path normalization automatically for:

• Windows-style paths
• Unix-style paths
• Mixed path separators
• Nested directory structures (up to 10 levels deep)

Performance Optimizations

• Content-Type caching reduces MIME type lookups
• In-memory caching in development mode
• Efficient file watching with debounced updates
• Proper HTTP caching headers
• ETag support for validation caching