Static Assets

Static assets are files served by Spaceport directly to the user's browser without any server-side processing. This includes common resources like images, stylesheets (CSS), JavaScript files, and fonts. Because Spaceport serves these files "as-is," it ensures fast delivery and optimal performance for your web application.

This is different from dynamic content, which Spaceport generates on-the-fly. Dynamic content is handled by Spaceport's https://www.google.com/search?q=routing and templating systems, allowing for real-time content generation based on user interactions or database queries. For more information, see the Routing Documentation and Launchpad Documentation.

Note: Configuring static assets is done in the config.spaceport file. If you are unfamiliar with this file, please review the Spaceport Manifest Configuration File documentation first.

# Configuring Static Asset Paths

To tell Spaceport where to find your static assets, you map a public URL Path to a private Filesystem Path.

• URL Path: The path a user types into their browser (e.g., /assets/images/logo.png).
• Filesystem Path: The actual folder on your server where the files are stored (e.g., public/images/logo.png).

The configuration happens within the static assets section of your config.spaceport file.

# Example config.spaceport snippet
static assets:
  paths:
    /assets/* : assets/

What's going on in the config?

• static assets:: The top-level key for all static asset settings.
• paths:: The sub-section where you define your URL-to-filesystem mappings.
• /assets/: This is the URL Path. It's the key in the mapping. Clients will use this path to request files. We'll cover the (wildcard) in the next section.
• assets/: This is the Filesystem Path. It's the value in the mapping. Spaceport will look for files in this directory on the server.

## Default Behavior

By default, if you do not configure any static asset paths, Spaceport will serve files from a folder named assets/ in your Spaceport root, but subdirectories will not be served unless explicitly configured. A default mapping is equivalent to:

static assets:
  paths:
    /assets/ : assets/

Why '/assets/'?

Spaceport uses /assets/ as the default URL path for static assets. Change this up as desired to fit your application's structure and requirements. Some other common choices include /static/, /public/, or even /www/.

## Serving Subdirectories with Wildcards

A URL path without a wildcard will only serve files directly inside the matching folder. It will not serve files from its subdirectories.

To serve a directory and all of its subdirectories, you must add an asterisk (*) wildcard to the end of the URL path key. This is the most common and recommended configuration.

# ❌ INEFFECTIVE for subdirectories like assets/css/
# A request for /assets/css/styles.css will return a 404.
static assets:
  paths:
    /assets/ : assets/

# ✅ RECOMMENDED for serving an entire directory tree
# A request for /assets/css/styles.css works perfectly.
static assets:
  paths:
    /assets/* : assets/

## Relative vs. Absolute Paths

You can use either relative or absolute paths for the filesystem location:

• Relative Path (e.g., assets/): This path is relative to the Spaceport root directory. The root is determined by the spaceport root setting in your configuration, or if not specified, the directory from which you launch the Spaceport server. This is flexible and recommended for most projects.
• Absolute Path (e.g., /var/www/myapp/assets/): The full path from the filesystem root. Use this when your assets are stored outside of your project directory.

Warning: For security and clarity, avoid using a single /, which will serve the Spaceport root directory (not the filesystem root). Always point to a specific, dedicated asset directory.

# ❌ DANGER! Avoid this configuration unless you know what you're doing
static assets:
  paths:
    /assets/* : /

# Asset Precedence: Static vs. Dynamic Routes

Spaceport checks for a matching static asset before it tries to match a dynamic route. This means if a request matches both a static file and a dynamic route, the static file will be served. For example, if you have:

• A static file at public/about.html.
• A static assets configuration of / : public/.
• A dynamic route that handles /about.

A request to /about.html will serve the static file. A request to /about will be handled by the dynamic route. If you had named your static file public/about, the static file would win and your dynamic route would never be reached.

# Advanced Configuration & Features

## Directory Listings

When debug mode is enabled, Spaceport will show browsable directory listings for your static asset paths. This is useful for checking the contents of a directory during development. When debug mode is disabled (for production), this feature is turned off as a security measure.

## File Map Buffer

For maximum throughput in production, Spaceport leverages the underlying Jetty web server's high-performance fileMapBuffer feature. This is more advanced than simple path caching; it memory-maps your static asset files, creating a direct, high-speed link between the files on disk and the server's memory.

This mechanism allows the operating system to handle caching and enables near "zero-copy" serving. Data is transferred directly from the filesystem cache to the network socket, drastically reducing I/O overhead and resulting in significantly faster file delivery.

The main trade-off is that memory-mapping can lock the files on the filesystem, preventing them from being updated while the server is running. For this reason, Spaceport intelligently manages this feature for you:

• Disabled in Debug Mode: To allow you to edit CSS, JavaScript, and other assets and see changes instantly, this feature is off during development.
• Enabled in Production Mode: For the best possible performance, the file buffer is on by default when debug mode is disabled.

If you need to update assets in a production environment without restarting the server, you can explicitly disable this feature by setting buffer to false.

# Disable file map buffering (caching)
static assets:
  buffer: false
  paths:
    /assets/* : assets/

## MIME Types

You don't need to worry about setting Content-Type headers for your assets. Spaceport automatically detects the correct MIME type based on the file's extension (e.g., .css becomes text/css, .png becomes image/png) and sends the appropriate header with the response.

# Serving a Full Static Website

Yes, you can easily serve an entire static website. Place all your HTML, CSS, JavaScript, and image files into a single folder (e.g., site/) and create a simple mapping:

# Serve an entire static website from the root URL
static assets:
  paths:
    /* : site/

Now, a request to http://yourdomain.com/about.html will serve the site/about.html file.