View Source PhoenixImportmap (Phoenix Importmap v0.4.0)

Installation

The package can be installed by adding phoenix_importmap to your list of dependencies in mix.exs:

def deps do
  [
    {:phoenix_importmap, "~> 0.4.0"}
  ]
end

If you are using the esbuild package you may also remove it, along with its configuration.

In config/dev.exs add the asset watcher to your Endpoint configuration:

watchers: [
  assets: {PhoenixImportmap, :copy_and_watch, [~w(/assets)]},
]

In config/config.exs add an importmap. The following is a good start for a conventional Phoenix app:

config :phoenix_importmap, :importmap, %{
  app: "/assets/js/app.js",
  topbar: "/assets/vendor/topbar.js",
  phoenix_html: "/deps/phoenix_html/priv/static/phoenix_html.js",
  phoenix: "/deps/phoenix/priv/static/phoenix.mjs",
  phoenix_live_view: "/deps/phoenix_live_view/priv/static/phoenix_live_view.esm.js"
}

If you are using topbar, replace the relative topbar import in assets/app/app.js with a module specifier. This asset will be resolved by our importmap:

import topbar from 'topbar';

You'll also need to replace the contents of assets/vendor/topbar.js with a wrapped version that supports ESM, like this from jsDelivr.

In lib/<project>/components/layouts/root.html.heex replace the app.js <script> tag.

Be sure to use your own project's module name in place of YourAppWeb.

<script type="importmap">
  <%= PhoenixImportmap.importmap(YourAppWeb.Endpoint) %>
</script>
<script type="module">
  import 'app';
</script>

Finally, in mix.exs update your assets aliases to replace esbuild with this library:

  "assets.setup": ["tailwind.install --if-missing"],
  "assets.build": ["tailwind default", "phoenix_importmap.copy"],
  "assets.deploy": ["tailwind default --minify", "phoenix_importmap.copy", "phx.digest"]

The phoenix_importmap_example repository demonstrates configuring a newly-generated Phoenix app.

Importmap configuration

  • :importmap - Map representing your assets. This is used to copy and watch files, and resolve public paths in PhoenixImportmap.importmap()

Asset path configuration

The defaults should work out of the box with a conventional Phoenix application. There are two global configuration options available.

  • :copy_destination_path - Where your mapped assets will be copied to. Defaults to /priv/static/assets which is the default path for to serve assets from.

  • :public_asset_path_prefix - The public path from which your assets are served. Defaults to /priv/static which is the default path for Plug.Static to serve / at.

Summary

Functions

Copies mapped assets to :copy_destination_path, which defaults to /priv/static/assets.

Does an initial copy of assets, then starts a child process to watch for asset changes.

Returns a t:PhoenixImportmap.Importmap struct that implements the Phoenix.HTML.Safe protocol, allowing safe interpolation in your template.

Functions

copy()

Copies mapped assets to :copy_destination_path, which defaults to /priv/static/assets.

For use in phoenix_importmap.copy mix task.

copy_and_watch(watch_dirs)

Does an initial copy of assets, then starts a child process to watch for asset changes.

For use with Phoenix.Endpoint watchers.

importmap(endpoint)

Returns a t:PhoenixImportmap.Importmap struct that implements the Phoenix.HTML.Safe protocol, allowing safe interpolation in your template.

The resulting JSON-formatted importmap is based on your application configuration.

Requires YourAppWeb.Endpoint to be passed in for path generation.