[−][src]Macro reinda::assets

assets!() { /* proc-macro */ }

Compile time configuration of assets. Returns a Setup.

Simple example:

ⓘ
use reinda::{assets, Setup};

const ASSETS: Setup = assets! {
    #![base_path = "frontend/build"]

    "index.html": { template },
    "bundle.js": { hash },
};

Syntax

The basic syntax looks like this:

ⓘ
use reinda::{assets, Setup};

const ASSETS: Setup = assets! {
    #![global_setting1 = "value1"]
    #![global_setting2 = 3]

    "path/to/asset-x.html": {
        asset_setting_a: false,
        asset_setting_b: "data",
    },
    "another-path/asset-y.js": {
        asset_setting_b: "other data",
    },
};

Global settings

  • base_path (string, required): specifies a base path. It is relative to CARGO_MANIFEST_DIR. The resulting compile time path of an asset is $CARGO_MANIFEST_DIR/$base_path/$asset_path. When assets are loaded at runtime, everything is relative to the current directory instead of CARGO_MANIFEST_DIR. You can overwrite the base path for the runtime via Config::base_path.

Assets

Each asset is defined by a path, followed by colon and then a set of settings for that asset. In many cases, the path can simply be a file name. See the base_path global setting.

The settings are specified with the Rust struct initializer syntax. However, you can just omit fields for which you want to use the default value. Also, boolean fields can omit their value if it is true. For example, "bundle.js": { template } is the same as "bundle.js": { template: true }.

Asset settings:

  • serve (bool, default: true): if set to false, this asset cannot be directly retrieved via Assets::get. This only makes sense for assets that are intended to be included by another asset.

  • template (bool, default: false): if set to true, the included file is treated as a template with the reinda specific template syntax. Otherwise it is treated as verbatim file.

  • dynamic (bool, default: false): if set to true, this is treated as a dynamic asset which has to be loaded at runtime and cannot be embedded. In dev mode, the asset is loaded on each Assets::get (like all other assets); in prod mode, it is loaded from the file system in Assets::new.

  • hash (optional pair of strings, disabled by default): see section about hashed filenames below.

  • prepend/append (optional string, default: None): if specified, a fixed string is prepended or appended to the included asset before any other processing (e.g. template) takes place.

Hashed filename

If hash is specified for an asset, a hash of the asset's contents are included into its filename. Assets::get won't serve it with the path you specified in this macro, but with a path that includes a hash. Filename hashing is disable in dev mode.

By default, the hash (and an additional .) will be inserted before the first . in the filename of the asset's path. If that filename does not contain a ., a - and the hash is appended to the filename. For example:

  • sub/main.js.map → sub/main.JdeK1YeQ90aJ.js.map
  • folder/raw-data → folder/raw-data-JdeK1YeQ90aJ

If that doesn't suit you, you can override this behavior by specifying two strings in between which the hash will be inserted. For example:

"main-v1.0-min.js.map": {
    hash: "main-v1.0-min." ... ".js.map",
}

The resulting filename would be main-v1.0-min.JdeK1YeQ90aJ.js.map for example.