`jekyll_asset_map`

GitHub License: Parity-6.0.0 Buy a license for use in closed source

When to use this

You should use this if all of the below are true:

you’ve got an existing Jekyll site written using liquid templates

you want to use some of the hot new tools from the JS ecosystem

but you don’t want to completely rewrite your build process.

If you’re going to process your HTML with some tool that runs in Node.js (webpack, rollup, parcel, gulp, or anything else), that tool likely has its own asset map implementation.

installation

Copy the _includes/asset_map directory into your own _includes directory.

API

asset_map/path

Arguments

map: optional string. The name of the asset map hash table within site.data. Defaults:

include.map
  | default: page.asset_map.name
  | default: site.asset_map.name
  | default: "manifest"

name: optional string. The name of the asset within the asset map.

Examples

{%
  include asset_map/path
    name="foo.js"
%}

foo.h4sh3d.js

However, if path fails to map a name to a path, it will return an empty string:

{%
  include asset_map/path
    name="missing.js"
%}

asset_map/integrity

Arguments

map: optional string. The name of the asset map hash table within site.data. Defaults:

include.map
  | default: page.asset_map.name
  | default: site.asset_map.name
  | default: "manifest"

name: optional string. The name of the asset within the asset map.

Examples

{%
  include asset_map/integrity
    name="bar.js"
%}

sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC

If missing, integrity returns nothing:

{%
  include asset_map/integrity
    name="missing.js"
%}

asset_map/error

There are four errors you can throw, from most severe to least: alert, error, comment, and 404. All asset_map/* includes respect the same options for an error parameter.

Arguments

message: optional string. A specific error message.

error: optional one of “alert”, “error”, “comment”, or “404”. What kind of error to raise. Defaults:

include.error
  | default: site.asset_map.error
  | default: "404" if jekyll.environment is "production", else "alert"

Examples

{%
  include asset_map/error
    error="alert"
    message="this failed. Here's why:..."
%}

<script>alert("this failed. Here's why:...")</script>

{%
  include asset_map/error
    error="error"
    message="this failed. Here's why:..."
%}

<script>throw new Error("this failed. Here's why:...")</script>

{%
  include asset_map/error
    error="comment"
    message="this failed. Here's why:..."
%}

<!-- this failed. Here's why:... -->

{%
  include asset_map/error
    error="404"
    name="a-missing-pack.js"
%}

<script src="/pack/does/not/exist/a-missing-pack.js"></script>

Causing a 404 error is the default in production. In other environments, alert is the default.

asset_map/script

Arguments

map: optional string. The name of the asset map hash table within site.data. Defaults:

include.map
  | default: page.asset_map.name
  | default: site.asset_map.name
  | default: "manifest"

name: optional string. The name of the asset within the asset map.

error: optional one of “alert”, “error”, “comment”, or “404”. What kind of error to raise. Defaults:

include.error
  | default: site.asset_map.error
  | default: "404" if jekyll.environment is "production", else "alert"

…other script tag attrs: optional bool or string. Other script tag attributes: async, defer, nomodule, type, crossorigin, referrerpolicy. Default: false/blank

Examples

{%
  include asset_map/script
    name="foo.js"
%}

<script src="foo.h4sh3d.js"></script>

You can use script attributes such as async, defer, type, nomodule, crossorigin, or referrerpolicy.

{%
  include asset_map/script
    name="foo.js"
    async=true
%}

<script src="foo.h4sh3d.js" async></script>

Setting a boolean attribute to false will result in it being omitted (equivalent to false in html).

{%
  include asset_map/script
    name="foo.js"
    async=false
%}

<script src="foo.h4sh3d.js"></script>

Missing scripts accept the standard error parameter (see the error documentation)

{%
  include asset_map/script
    error="comment"
    name="quux.js"
%}

<!-- WARNING! Missing script pack named quux.js -->

By default, if your asset map includes integrity information, that integrity is included in the generated script tag.

{%
  include asset_map/script
    name="bar.js"
%}

<script src="bar.md5hd.js" integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"></script>

asset_map/stylesheet

Arguments

map: optional string. The name of the asset map hash table within site.data. Defaults:

include.map
  | default: page.asset_map.name
  | default: site.asset_map.name
  | default: "manifest"

name: optional string. The name of the asset within the asset map.

error: optional one of “alert”, “error”, “comment”, or “404”. What kind of error to raise. Defaults:

include.error
  | default: site.asset_map.error
  | default: "404" if jekyll.environment is "production", else "alert"

…other stylesheet tag attrs: optional bool or string. Other <link rel="stylesheet"> attributes: crossorigin, importance, media, type. Default: false/blank

Examples

{%
  include asset_map/stylesheet
    name="foo.css"
%}

<link rel="stylesheet" href="foo.h45h3d.css">

{%
  include asset_map/stylesheet
    name="missing.css"
%}

<script src="/pack/does/not/exist/missing.css"></script>

asset_map/chunks_js

Arguments

map: optional string. The name of the asset map hash table within site.data. Defaults:

include.map
  | default: page.asset_map.name
  | default: site.asset_map.name
  | default: "manifest"

entrypoints: optional string. a list of entrypoint names, separated by include.sep or commas. Whitespace-sensitive.

sep: optional string. the string that separates the entrypoint names in include.entrypoints. Default: ","

asset_key: optional string. the sub-array of the entrypoint containing the js chunk descriptors. Default: "js"

entrypoint_key: optional string. where within the asset map to look for the arrays of chunks that make up your entrypoints. Default: "entrypoints"

error: optional one of “alert”, “error”, “comment”, or “404”. What kind of error to raise. Defaults:

include.error
  | default: site.asset_map.error
  | default: "404" if jekyll.environment is "production", else "alert"

…other script tag attrs: optional bool or string. Other script tag attributes: async, defer, nomodule, type, crossorigin, referrerpolicy. Default: false/blank

Examples

Chunks shared between entrypoints are deduplicated. Here, app1 and app2 share app.chunk.1.js.

{%
  include asset_map/chunks_js
    entrypoints="app1,app2"
%}

<script src="app.chunk.1.js"></script>
<script src="app.chunk.2.js"></script>
<script src="app.chunk.3.js"></script>

Missing entrypoints cause an error

{%
  include asset_map/chunks_js
    entrypoints="missing,app2"
%}

<script src="app.chunk.1.js"></script>
<script src="app.chunk.3.js"></script>

You can even mix css and js chunks in your entrypoints array.

{%
  include asset_map/chunks_js
    entrypoints="app3,app2"
%}

<script src="app.chunk.1.js"></script>
<script src="app.chunk.2.js" integrity="sha256-h4sh"></script>
<script src="app.chunk.3.js"></script>

asset_map/chunks_css

Arguments

map: optional string. The name of the asset map hash table within site.data. Defaults:

include.map
  | default: page.asset_map.name
  | default: site.asset_map.name
  | default: "manifest"

entrypoints: optional string. a list of entrypoint names, separated by include.sep or commas. Whitespace-sensitive.

sep: optional string. the string that separates the entrypoint names in include.entrypoints. Default: ","

asset_key: optional string. the sub-array of the entrypoint containing the css chunk descriptors. Default: "css"

entrypoint_key: optional string. where within the asset map to look for the arrays of chunks that make up your entrypoints. Default: "entrypoints"

error: optional one of “alert”, “error”, “comment”, or “404”. What kind of error to raise. Defaults:

include.error
  | default: site.asset_map.error
  | default: "404" if jekyll.environment is "production", else "alert"

…other stylesheet tag attrs: optional bool or string. Other script tag attributes: async, defer, nomodule, type, crossorigin, referrerpolicy. Default: false/blank

Examples

{%
  include asset_map/chunks_css
    entrypoints="app1,app2"
%}

<link rel="stylesheet" href="app.chunk.1.css">
<link rel="stylesheet" href="app.chunk.2.css">
<link rel="stylesheet" href="app.chunk.3.css">

Missing chunks throw errors exactly like missing stylesheets do.

{%
  include asset_map/chunks_css
    entrypoints="missing,app2"
    error="alert"
%}

<script>alert("Warning! No entrypoint named missing found in manifest#entrypoints.")</script>
<link rel="stylesheet" href="app.chunk.1.css">
<link rel="stylesheet" href="app.chunk.3.css">

JS Compiler Configuration Examples

Example app to compile

// example/foo.js
export default "hello";
export const world = "world";

// example/app1.js
import hello, { world } from "./foo.js";
import { snakeCase, join, concat } from "lodash-es";
export default function() {
  const salutation = join([hello, world], "~");
  console.log(snakeCase(salutation));
}

// example/app2.js
import { camelCase, join } from "lodash-es";
export default function app2() {
  import("./foo.js").then(({ default: foo, world }) => {
    const salutation = join([foo, world], " ");
    console.log(camelCase(salutation));
  });
}

Configurations:

rollup
- simple configuration
- maximally-split, maximally-hashed
webpack
- webpack-assets-manifest-plugin
  - simple configuration
  - with integrity hashes
- webpack-manifest-plugin
  - simple configuration
  - with arrays of chunks for each entrypoint