add a section about npm when using phx.gen.release --docker

Fixes #5976.

Author: SteffenDE

guides/asset_management.md

@@ -46,6 +46,10 @@ If you want to import JavaScript dependencies, you have at least three options t
    be used by Hex packages, so if you intend to publish your project to Hex,
    consider vendoring the files instead.
 
+Note that if you use third party JS package managers, you might need to adjust your deployment steps
+to properly include the packages. If you're using `mix phx.gen.release --docker`, have a look at the
+[documentation](Mix.Tasks.Phx.Gen.Release.html#module-docker) for further details.
+
 ## Images, fonts, and external files
 
 If you reference an external file in your CSS or JavaScript files, `esbuild` will attempt to validate and manage them, unless told otherwise.

lib/mix/tasks/phx.gen.release.ex

@@ -31,6 +31,38 @@ defmodule Mix.Tasks.Phx.Gen.Release do
 
   For extended release configuration, the `mix release.init` task can be used
   in addition to this task. See the `Mix.Release` docs for more details.
+
+  If you are using third party JS package managers like `npm` or `yarn`, you will
+  need to update the generated Dockerfile with an extra step to fetch those packages.
+  This might look like this:
+
+  ```dockerfile
+  ...
+  ARG RUNNER_IMAGE="debian:..."
+
+  FROM node:20 as node
+  COPY assets assets
+  RUN cd assets && npm install
+
+  FROM ${BUILDER_IMAGE} as builder
+
+  ...
+
+  COPY assets assets
+  COPY --from=node assets/node_modules assets/node_modules
+  ...
+  ```
+
+  If you are using esbuild through Node.js or other JavaScript build tools, the approach
+  above can also be modified to invoke those in the node stage, for example:
+
+  ```dockerfile
+  FROM node:20 as node
+  COPY assets assets
+  RUN cd assets && npm install && node build.js --deploy
+  ```
+
+  Note that you may need to adjust the `assets.deploy` task to not invoke Node.js again.
   """
 
   use Mix.Task