app/js Modules

Keep source outside public files

Application JavaScript source lives under app/js:

app/js/app.js
app/js/controllers/hello_controller.js

Generated browser assets live under public files:

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

lazy js reads the source files, expands GoLazy directives in app/js/app.js, writes readable content-hashed public outputs, and maps stable browser specifiers to those outputs. App-owned scripts are not bundled or minified.

Add-ons can own structured library and entrypoint declarations in js.toml. lazy add preserves existing entries, records ownership in addons.toml, and stops on an incompatible value instead of rewriting arbitrary JavaScript. Run the normal lazy js workflow after installing or updating an add-on with browser contributions. See Add-ons.

Load the app entry

The layout inlines the importmap before importing the app module:

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

The generated importmap can map app.js to a hashed lazyshaft file:

{
  "imports": {
    "app.js": "/assets/lazyshaft/app/app-ZWUSRUPQ.js"
  }
}

Templates keep using the stable app.js specifier while browsers receive the fingerprinted asset.

Import Turbo and Stimulus

The app entry may use GoLazy source directives:

// golazy:turbo
// golazy:stimulus

// golazy:turbo imports Hotwire Turbo. // golazy:stimulus imports Stimulus, starts the application, scans app/js/controllers/**/*_controller.js, and registers each controller with an import name relative to app/js, such as controllers/hello_controller.js.

Add a Stimulus controller

Create a controller source file:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.element.dataset.ready = "true"
  }
}

For this file:

app/js/controllers/hello_controller.js

GoLazy registers the identifier:

hello

Nested directories use --, and underscores in filenames become dashes.

Use lazy js for the manifest, library bundles, workers, copied assets, and generated outputs.