Configuring Assets

There are three settings parameters we must know to work with static files in Kalgan.

...
static:
  folders: static
  path: /static
  version: v001
...

Find a description of these fields in the table below:

By default all the incoming requests are parsed by the routing system. This means static files won't be parsed (we'll get an erorr 404) unless we give a value to static.folders.

When a request arrives, Kalgan checks whether the uri matches the location of one the folders defined in parameter static.folders. If it finds a match, it passes the request to the module kalgan::handler::asset. If it doesn't, it passes the request to the Router. Needless to say that these folders must exist in our project, otherwise we'll get an error 404.

Notice these static folders must located at the same level of our folder src, that it to say:

project/
    Cargo.toml
    config/
        app/
            settings.yaml
        routes/
            ...
    src/
        main.rs
        ...
    static/
        css/
            ...
        vendor/
            ...

Calling Assets

There's nothing special to do to call a static file from our HTML templates. For example:

...
<script src="/static/vendor/jquery/dist/jquery.min.js"></script>
...

However hard-code the URLs of web assets is not recommended as it makes difficult (if not impossible) to version these files or change their location. These issues are especially significant in big applications.

For this purpose Trator supports out of the box the built-in filter asset for Tera templates which offers a couple of features which might be helpful. For example:

...
<script src="{{ "/vendor/jquery/dist/jquery.min.js"|asset }}"></script>
...

In a dev environment ( environment.is_prod: false ) this will render as follows:

...
<script src="/static/vendor/jquery/dist/jquery.min.js?14:33:49.710194842"></script>
...

We can see 2 things here:

• We don't have to specify the root folder (or base URL) of our static files already set in static.path. This is extremely useful when switching between dev and prod environments as we might use different servers or locations for our static content files.
• A extension ?<timestamp> is appended at the end of the route. This timestamp value is updated everytime we refresh the browser. This prevents the browser from using the cached content of the static files, which can be really anoying while developing.

In a prod environment ( environment.is_prod: true ) the previous code would render as follows:

...
<script src="/static/vendor/jquery/dist/jquery.min.js?v001"></script>
...

Notice that in this case the extension ?v001 is appended at the end of the route. This let us assure that browsers will use only the cached content of files for the given version in static.version.

Reverse Proxy

Kalgan built-in server does the job. It's really helpful being able to start developing without setting any other external software to manage our web assets.

However Kalgan server should not be the way to go when parsing web assets in a production environment. There are many other better options out there to carry out this task (for example NGINX Reverse Proxy).

For this purpose we recommend to set up a reverse proxy server in front of our app. However the way to do this is out the scope of these docs.

As soon as we delegate the parsing of assets to a third party, we must remember to remove parameter static.folders in the settings file to stop Kalgan looking for these static files in the request.

For more information regarding running our app in prod environment go to Production in the docs.