There are different ways to serve static files like JavaScript and CSS. The easiest way is to simply register StaticSimple or StaticCompressed plugin in your reimplementation of Application::init(). Other ways are to use the static maps of Cutelyst Server or to use a web server like Apache in front of your Cutelyst server that also serves your static files directly without using Cutelyst.

Use a plugin to serve static files

Using a plugin like StaticSimple or StaticCompressed is the most easiest to implement way of serving static files with Cutelyst. Simply register one of the pulgins in your app’s init function and set include paths to the directories containing your static files:

using namespace Cutelyst;
 
bool MyCutelystApp::init()
{
 
    // other initialization stuff
    // ...
 
    // construct a new StaticSimple plugin that will automatically be registered
    auto stat = new StaticSimpe(this);
    stat->setIncludePaths({"/path/to/my/include/files"});
 
    // maybe more initialization stuff
    // ..
}

StaticCompressed is similar to use. Both plugins either serve files beginning with a specific configurable path or try to identify static files as paths ending with something that looks like a file extension like /assets/css/style.css. From the example above, the plugin would try to find style.css at /path/to/my/include/files/assets/css/style.css when your request path is /assets/css/style.css.

Using one of these plugins is also the easiest way to provide methods for your users/customers to override static files by adding multiple paths for static files.

See the documentation of StaticSimple and StaticCompressed to learn more about these plugins.

Use the Cutelyst server to serve static files

The Cutelyst Server, that is started by cutelystd4-qt6 or manually by your own application, can also directly serve static files. Using cutelystd4-qt6 you have the options --static-map and --static-map2 that can be used multiple times to add mappings for static file directories. While static-map removes the mount point from the request path, static-map2 appends the complete request path. When integrating the Server class in your own application, use the Server::static_map and Server::static_map2 properties.

Added mappings are automatically sorted by the string length of the mounpoint part from short to long and will be compared to the request path in that order.

static-map

The static-map option takes values of the form /mount/point=/path/to/static/files. When searching for the requested file in your local directory, it will remove the mountpoint part from the request path and will than append the rest of the request path to your local path and will try to find the file.

If you set the following static-map for example: --static-map /assets=/path/to/static/assets. If you than request a file like http://localhost:3000/assets/js/script.js, Cutelyst Server will try the static map for mountpoint /assets, that is available. It will than remove the mountpoint from the request path /assets/js/script.js and will append the rest to the local path. It will than try to find the requested file at /path/to/static/assets/js/scripts.js.

static-map2

The static-map2 option takes values of the form /mount/point=/path/to/static/files. When searching for the requested file in your local directory, it will completely append the request path including the mount point to the local path and will try to find the file.

If you set the followingstatic-map2 for example: --static-map2 /assets=/path/to/static. If you than request a file like http://localhost:3000/assets/js/script.js, Cutelyst Server will try the static map for mountpoint /assets, that is available. It will than append the complete request path to the local path and will try to find the requested file at /path/to/static/assets/js/script.js.

static-map vs. static-map2 overview

Static map comparison with /assets=/path/to/static and a request to /assets/css/style.css.

	static-map	static-map2
Mountpoint	/assets	/assets
Path	/path/to/static	/path/to/static
Request path	/assets/css/style.css	/assets/css/style.css
Local path	/path/to/static/css/style.css	/path/to/static/assets/css/style.css

Use a web server to serve static files

If you already use a web server like Apache or nginx in front of your Cutelyst application, you can also use that to directly serve your static files.

Apache

If using the Apache HTTP server in front of your Cutelyst application with mod_proxy, you can for example use mod_alias to serve your static files omitting Cutelyst. In the following example we will use a FastCGI proxy.

# myvhost.conf
<VirtualHost *:80>
    ServerName example.org:80
 
    # set the proxy type
    ProxyFCGIBackendType GENERIC
 
    # connect to your Cutelyst app via FastCGI
    ProxyPass / unix:/path/to/cutelyst/app.socket|fcgi://myapp/
 
    # create an alias for your assets
    Alias /assets /path/to/my/application/assets
    # configure the location and disable the FastCGI proxy for it
    <Location /assets>
        ProxyPass !
        Require all granted
    </Location>
</VirtualHost>

If you now request http://example.org/assets/css/style.css, the Apache server will not try to answer the request by giving it via FastCGI to the Cutelyst application but will try to find the requested file at /path/to/my/application/assets/css/style.css.

Table of Contents