After the Phoenix 1.6 esbuild switch, who should pin Elixir/OTP versions for a team?

Phoenix does not provide a built-in mechanism to pin Elixir or Erlang/OTP versions. While the 1.6+ asset toolchain (esbuild and Tailwind) is pinned via Hex packages and config/config.exs, the runtime environment remains the responsibility of the development team. To ensure parity across local environments and CI, teams should use an external version manager or containerization strategy.

Recommended Pinning Strategies

Since the framework is agnostic to the runtime manager, the community standard is to use one of the following three patterns:

• Version Managers (asdf / mise): Create a .tool-versions file in the project root. This is the most common approach for Elixir teams, as it allows developers to switch versions automatically upon entering the directory.
• Nix Flakes: Provides a purely functional, reproducible shell environment. This is preferred for teams requiring strict guarantees that every dependency (including system libraries) is identical.
• Docker: Define a specific elixir:1.x-otp-2x-alpine image tag in your Dockerfile. This is the primary method for ensuring CI and production parity.

Implementation and Migration

Timing the Pinning Strategy

When migrating a pre-1.6 app from Webpack to esbuild, you should decide and implement your version-pinning strategy before the asset migration. Because CI must reproduce the build, having a locked Elixir/OTP version prevents "ghost" failures where asset compilation succeeds on a developer's machine but fails in CI due to a mismatch in the underlying BEAM version or environment variables.

Compatibility Constraints

There are no direct compatibility constraints between specific OTP releases and the esbuild or tailwind Hex wrappers. These wrappers download standalone binaries that execute independently of the Erlang VM. However, you must still respect the following dependencies:

• Elixir & Phoenix: Ensure your pinned Elixir version meets the minimum requirement defined in mix.exs.
• OTP & Elixir: Ensure the Elixir version is compatible with the chosen OTP release (refer to the official Elixir compatibility matrix).

Verification Steps

To verify your current environment alignment, run the following commands across different team machines:

elixir -v
# Compare the Elixir and OTP versions listed in the output

Check your config/config.exs to ensure asset versions are explicitly set, for example:

config :esbuild, version: "1.28.0"
config :tailwind, version: "3.0.0"