lazy js And js.toml

Declare entrypoints

The default manifest is intentionally short:

[entrypoint.turbo]
module = "@hotwired/turbo"

[entrypoint.stimulus]
module = "@hotwired/stimulus"

Each [entrypoint.<name>] block declares one library bundle. module is the package import that esbuild bundles.

Run the pipeline

Run lazy js from the application module root:

lazy js

The command prepares missing package dependencies, runs the detected package manager install through mise exec, bundles manifest entrypoints, bundles app/js modules, and writes:

app/public/assets/importmap.json
app/public/assets/lazyshaft/*.js

Load by importmap

The layout loads the generated map before app code:

{{importmap "/assets/importmap.json"}}
<script type="module">import "/js/app.js"</script>

The importmap maps stable browser imports to generated assets:

{
  "imports": {
    "@hotwired/turbo": "/assets/lazyshaft/turbo-QDEQVE6U.js",
    "/js/app.js": "/assets/lazyshaft/app/app-ZWUSRUPQ.js"
  }
}

Use explicit browser import names

When the browser import name should differ from the bundled module path, set imports:

[entrypoint.monaco]
module = "monaco-editor/esm/vs/editor/editor.api.js"
imports = ["monaco-editor"]

Application code can then import the shorter name:

import * as monaco from "monaco-editor"

Include workers and assets

Some libraries load extra files dynamically. Declare them in the same entrypoint block:

[entrypoint.monaco]
module = "monaco-editor/esm/vs/editor/editor.api.js"
imports = ["monaco-editor"]
workers = [
  "monaco-editor/esm/vs/editor/editor.worker.js",
]
assets = [
  "node_modules/monaco-editor/min/vs/**/*",
]

Workers are bundled as extra JavaScript outputs. Assets are copied into the lazyshaft output directory.

Commit outputs

Commit generated assets and package metadata:

js.toml
package.json
package-lock.json
app/js/**/*.js
app/public/assets/importmap.json
app/public/assets/lazyshaft/*.js

Do not commit node_modules.