Skip to content

Commit 05d21a8

Browse files
authored
Add more info how to manager 3rd party assets (phoenixframework#6256)
1 parent 48e4108 commit 05d21a8

File tree

1 file changed

+21
-0
lines changed

1 file changed

+21
-0
lines changed

guides/asset_management.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,18 @@ If you want to import JavaScript dependencies, you have at least three options t
2626
import topbar from "topbar"
2727
```
2828

29+
To ensure that `npm install` is being run when checking out your project, or when building a release add a `"cmd --cd assets npm ci"` step in `mix.exs` to the `assets.deploy` and `assets.build` steps:
30+
31+
```elixir
32+
"assets.build": ["cmd --cd assets npm ci", "tailwind your_app", "esbuild your_app"],
33+
"assets.deploy": [
34+
"cmd --cd assets npm ci",
35+
"tailwind your_app --minify",
36+
"esbuild your_app --minify",
37+
"phx.digest"
38+
]
39+
```
40+
2941
3. Use Mix to track the dependency from a source repository:
3042

3143
```elixir
@@ -77,6 +89,15 @@ args: ~w(js/app.js --bundle --target=es2022 --outdir=../priv/static/assets/js --
7789

7890
If you need to reference other directories, you need to update the arguments above accordingly. Note running `mix phx.digest` will create digested files for all of the assets in `priv/static`, so your images and fonts are still cache-busted.
7991

92+
### Ensuring fonts and images from third-party libraries are loaded
93+
94+
If you import a Node package that depends on additional fonts or images, you might find them to fail to load. This is because they are referenced in the JS or CSS but by default Esbuild will not touch or process referenced files. You can add arguments to esbuild in `config/config.exs` to ensure that the referenced resources are copied to the output folder. The following example would copy all referenced font files to the output folder and prefix the paths with `/assets/`:
95+
96+
```elixir
97+
args: ~w(js/app.js --bundle --target=es2017 --outdir=../priv/static/assets --external:/fonts/* --external:/images/* --public-path=/assets/ --loader:.woff=copy --loader:.ttf=copy --loader:.eot=copy --loader:.woff2=copy),
98+
```
99+
For more information, see [the esbuild documentation](https://esbuild.github.io/content-types/#copy).
100+
80101
## Esbuild plugins
81102

82103
Phoenix's default configuration of `esbuild` (via the Elixir wrapper) does not allow you to use [esbuild plugins](https://esbuild.github.io/plugins/). If you want to use an esbuild plugin, for example to compile SASS files to CSS, you can replace the default build system with a custom build script.

0 commit comments

Comments
 (0)