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 inPhoenixImportmap.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 forPlug.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
Copies mapped assets to :copy_destination_path
, which defaults to /priv/static/assets
.
For use in phoenix_importmap.copy
mix task.
Does an initial copy of assets, then starts a child process to watch for asset changes.
For use with Phoenix.Endpoint watchers.
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.