@spec browser_name(map(), String.t() | nil) :: String.t()

The name a runtime hook is registered under in the browser.

Public because the builder's hook picker has to write exactly this string into phx-hook, and a second copy of the rule would drift from the one that does the registering.

Compiles JavaScript from app.js, vendor files, and hooks for a specific site.

This is the main compilation function that orchestrates the entire JavaScript bundling process for a specific site. It handles temporary file management, runtime hook generation, and ESBuild execution.

Parameters

• site_name - The name/identifier of the site to compile JavaScript for

Returns

• {:ok, %{js: compiled_js, lazy: modules}} - On successful compilation: the bundle, and the module of each lazy hook it loads on first use, as %{hook: name, hash: hash, js: module}
• {:error, reason} - On failure, returns an error with descriptive message

Compilation Steps

1. Creates temporary directories for build process
2. Generates runtime hooks from database-stored JavaScript
3. Ensures Phoenix colocated hooks are available
4. Executes ESBuild bundling with optimizations
5. Cleans up temporary files

Error Handling

Failures at any step will result in automatic cleanup of temporary files and return a descriptive error message. Common failure points:

• Missing app.js file
• ESBuild compilation errors
• Database connection issues when fetching hooks
• File system permission errors

Example

# Compile JavaScript for main site
case JavaScriptCompiler.compile("main") do
  {:ok, %{js: js}} ->
    IO.puts("Compiled JS size: #{byte_size(js)} bytes")
  {:error, reason} ->
    IO.puts("Compilation failed: #{reason}")
end

Compiles and stores the JS in AssetsState for a specific site.

This function combines compilation with caching, storing the compiled JavaScript along with compressed versions (Brotli and Gzip) in the AssetsState for fast serving.

Parameters

• site_name - The name/identifier of the site to compile JavaScript for

Returns

• {:ok, compiled_js} - On success, returns the compiled JavaScript string
• {:error, reason} - On failure, returns compilation error

Storage Details

Creates three entries in AssetsState:

• "js" - Original compiled JavaScript
• "brotli_js" - Brotli-compressed version (best compression)
• "gzip_js" - Gzip-compressed version (wide compatibility)

Each entry includes:

• MD5 hash for cache validation
• Timestamp for cache invalidation
• Compressed content for optimal delivery

Example

# Compile and cache JavaScript
case JavaScriptCompiler.compile_and_store("main") do
  {:ok, js} ->
    Logger.info("JavaScript compiled and cached: #{byte_size(js)} bytes")
  {:error, reason} ->
    Logger.error("Failed to compile: #{reason}")
end

Compiles + stores the shared base JS (app.js + global hooks only) under __shared_base__. Built once and reused by every global-only site.

Deletes compiled JS for a site.

Removes all cached JavaScript assets for the specified site from AssetsState. This includes the original JS and all compressed versions.

Parameters

• site_name - The site identifier to delete JavaScript for

Returns

• :ok on successful deletion
• Error tuple if deletion fails

Usage

# Clean up old JavaScript
JavaScriptCompiler.delete_compiled_js("old_site")

# Force recompilation by deleting and recompiling
JavaScriptCompiler.delete_compiled_js("main")
JavaScriptCompiler.compile_and_store("main")

Drops the cached shared base JS (all formats), and the lazy hooks' modules it loads.

Ensures the configured ESBuild is installed and runnable, caching the answer in :persistent_term so the check costs one --version run per node rather than one per compile.

It asks the binary, not the path. Esbuild.bin_path/0 BUILDS a string and returns it whether or not a file sits at the end of it, so testing it told us only that esbuild has a name — a missing binary then reached System.cmd and came back as ErlangError :enoent, an error naming neither esbuild nor a path, underneath a log line saying the binary had been found.

The version is checked too, and not as a formality: bin_path/0 puts no version in the filename, and Esbuild.configured_version/0 falls back to the library's own @latest_version when this project's config is not loaded. So anything that installs esbuild from outside this config leaves a differently-versioned binary at exactly the path we look at, and it stays there. That is how 0.25.0 came to sit where 0.25.4 was pinned.

Raises when esbuild is still unusable after installing, rather than caching a verification that is not true. MishkaCmsCore.Runtime.Handlers.BootHandler expects that and boots without it.

Retrieves compiled JS from AssetsState for a specific site.

Fast retrieval of cached JavaScript without recompilation. Returns a fallback comment if JavaScript is not found for the specified site.

Parameters

• site_name - The site identifier to retrieve JavaScript for

Returns

• Compiled JavaScript string if found in cache
• Fallback comment string if not found: "// JS not found for site: {site_name}"

Usage

js = JavaScriptCompiler.get_compiled_js("main")

# In Phoenix template
<script><%= raw(js) %></script>

Cached shared base JS, compiling + caching it on first use.

Checks if compiled JS exists for a site.

Quick boolean check to determine if JavaScript has been compiled and cached for the specified site.

Parameters

• site_name - The site identifier to check

Returns

• true if compiled JavaScript exists in cache
• false if no JavaScript found for the site

Usage

if JavaScriptCompiler.js_exists?("main") do
  js = JavaScriptCompiler.get_compiled_js("main")
else
  JavaScriptCompiler.compile_and_store("main")
end

@spec lazy_type(String.t()) :: String.t()

The AssetsState type a lazy hook's module is stored under, beside its site's bundle, from the hash its file is named by: lazy_js:<hash>, with brotli_lazy_js:<hash> and gzip_lazy_js:<hash> for its compressed copies.

@spec left_out(String.t()) :: [{String.t(), String.t()}]

The bundles the JS hook hook_id was left out of when they were last built, each with the reason, sorted by bundle: [{"localhost", ~s(Could not resolve "echarts" (globalChart.js:28))}].

A bundle is a site's name, or "__shared_base__" for the global hooks every site without hooks of its own shares. A global hook is built into every site's bundle, so it can be left out of several.

Refreshes JS for a site (recompiles and updates).

Convenience function that recompiles JavaScript for a site and updates the cache. This is useful when JavaScript hooks or configurations change.

Parameters

• site_name - The site identifier to refresh JavaScript for

Returns

• {:ok, compiled_js} - On successful recompilation
• {:error, reason} - On compilation failure

Usage

# Refresh after updating JavaScript hooks
case JavaScriptCompiler.refresh_js("main") do
  {:ok, js} ->
    Logger.info("JavaScript refreshed successfully")
  {:error, reason} ->
    Logger.error("Failed to refresh: #{reason}")
end

When to Use

• After updating JavaScript hooks in database
• When site configuration changes
• During development when app.js changes
• For periodic cache invalidation