Nexios

Appearance

Static Files ​

Serving static files is a common requirement for web applications. Nexios provides a robust and flexible system for serving static assets like CSS, JavaScript, images, and other file types with security and performance in mind.

Basic Setup ​

To serve static files in Nexios, use the StaticFiles class:

python
from nexios import NexiosApp
from nexios.static import StaticFiles

app = NexiosApp()

# Create a static files handler for a single directory
static_files = StaticFiles(directory="static")

## Mounting with Group
static_group = Group(path="/static", app=static_files)
app.add_route(static_group)

With this setup, a file at static/css/style.css would be accessible at /static/css/style.css.

Single Directory ​

The simplest configuration uses a single directory for all static files:

python
static_files = StaticFiles(directory="static")
static_group = Group(path="/static", app=static_files)
app.add_route(static_group)

Multiple Directories ​

For more complex setups, you can serve files from multiple directories:

python
static_files = StaticFiles(directories=["static", "public/assets", "uploads"])
static_group = Group(path="/static", app=static_files)
app.add_route(static_group)

When serving from multiple directories, Nexios searches for files in the order the directories are specified.

URL Prefixing ​

The prefix parameter defines the URL path under which static files are served:

python
static_files = StaticFiles(directory="static")
app.register(static_files, prefix="/assets")  # Serve files at /assets/ instead of /static/

Examples ​

Complete Application Setup ​

python
from nexios import NexiosApp
from nexios.static import StaticFiles
from nexios.routing import Group

app = NexiosApp()

# Serve static files with optimizations
static_files = StaticFiles(
    directory="static",
    prefix="/static",
    cache_control="public, max-age=3600",
    allowed_extensions=["css", "js", "png", "jpg"]
)
static_group = Group(path="/static", app=static_files)
app.add_route(static_group)

# Add middleware for logging
app.add_middleware(StaticFileLogger())

Security & Extension Filtering ​

For security reasons, you can restrict which file extensions are allowed to be served:

python
from nexios.routing import Group
# Only allow specific file extensions
static_files = StaticFiles(
    directory="static",
    allowed_extensions=["css", "js", "png", "jpg", "jpeg", "gif", "svg", "ico"]
)
static_group = Group(path="/static", app=static_files)
app.add_route(static_group)

This prevents serving potentially dangerous files like .php, .py, or other executable files.

Custom 404 Handler ​

You can provide a custom handler for when static files are not found:

python
def custom_404_handler(request, response):
    """Custom 404 handler for static files"""
    return response.html(
        """
        <html>
            <head><title>Custom 404</title></head>
            <body>
                <h1>Custom 404 - File Not Found</h1>
                <p>The requested file could not be found.</p>
                <p><a href="/">Go back home</a></p>
            </body>
        </html>
        """,
        status_code=404
    )

static_files = StaticFiles(
    directory="static",
    custom_404_handler=custom_404_handler
)
app.register(static_files, prefix="/static")

Performance & Caching ​

Cache Control ​

Configure caching headers for better performance:

python
static_files = StaticFiles(
    directory="static",
    cache_control="public, max-age=3600"  # Cache for 1 hour
)
app.register(static_files, prefix="/static")

Advanced Configuration ​

You can combine all these features for a fully configured static file server:

python
def custom_not_found(request, response):
    """Custom 404 page with styling"""
    return response.html(
        """
        <!DOCTYPE html>
        <html>
        <head>
            <title>Page Not Found</title>
            <style>
                body { font-family: Arial, sans-serif; text-align: center; padding: 50px; }
                .container { max-width: 600px; margin: 0 auto; }
                h1 { color: #333; }
                a { color: #007bff; text-decoration: none; }
                a:hover { text-decoration: underline; }
            </style>
        </head>
        <body>
            <div class="container">
                <h1> File Not Found</h1>
                <p>The requested file could not be found on this server.</p>
                <p><a href="/">Return to Home</a></p>
            </div>
        </body>
        </html>
        """,
        status_code=404
    )

# Advanced static file configuration
static_files = StaticFiles(
    directories=["static", "assets", "uploads"],
    allowed_extensions=["css", "js", "png", "jpg", "jpeg", "gif", "svg", "ico", "txt", "pdf"],
    custom_404_handler=custom_not_found,
    cache_control="public, max-age=86400",  # Cache for 24 hours
)

static_group = Group(path="/static", app=static_files)
app.add_route(static_group)