Phoenix ships four artefacts, and the JS client version runs ahead of the tags

Four build sequences, because the repository is four products

The README's Building from source section is four separate sequences, and that is the clearest statement of what this repository contains.

mix deps.get
mix compile

That builds the framework. The installer needs one more step, because phx.new ships as a Mix archive.

mix deps.get
mix compile
mix archive.build

Phoenix.js is built by Mix as well, not by npm.

mix assets.build

And the documentation has its own environment.

MIX_ENV=docs mix docs

So a repository that reads like one Elixir library is really four artefacts with four build paths: the framework, the generator, the JavaScript client and the docs site. The top level reflects that split with lib/ for the framework, installer/ for the generator, assets/ for the client sources and priv/ for what gets published.

For a contributor the cost is that the JavaScript half needs Elixir tooling, not just Node, and the two halves are built by different commands with no single entry point named anywhere.

package.json reads 1.9.0-dev while the newest tag is v1.8.15

The npm package for Phoenix.js declares version 1.9.0-dev. The most recent release of the framework is v1.8.16, dated 2026-10-20, with v1.8.15 and v1.8.14 before it.

So the client package and the framework share a version scheme, and the client on the current branch is already at the next minor version. That has a consequence for anyone pinning: the client version is not independent of the framework version, so choosing a client release is also choosing which Phoenix the client was cut alongside.

The dev suffix is the other half. A -dev version is what npm and Mix treat as pre-release, so it will not be selected by a plain range and installing it is a deliberate act.

Release management lives in its own file. RELEASE.md sits at the root next to CHANGELOG.md. The README itself does not describe the process.

Three entry points in one package, and it ships sources alongside the build

The npm package is described as the official JavaScript client for the Phoenix web framework, and its entry points are laid out for three different consumers.

module points at priv/static/phoenix.mjs, main points at priv/static/phoenix.cjs.js, and unpkg and jsdelivr both point at priv/static/phoenix.min.js. The exports map repeats the first two, import for the ESM build and require for CommonJS.

That is a script tag, a bundler and a module-aware toolchain covered by one package, and the minified file is what a CDN serves. All of those files live in priv/static, which the README's mix assets.build step produces.

The files list is worth noting too, since it publishes priv/static/* and assets/js/phoenix/* together with the metadata files. Consumers therefore receive the built artefacts and the JavaScript sources, which is convenient for reading the protocol and unusual for a compiled client.

mix archive.uninstall phx_new is step one of testing unreleased code

The section on generating a project from unreleased versions is the most operationally useful part of the README, and it starts by telling you to delete something.

Remove any previously installed phx_new archives so that Mix will pick up the local source code, using mix archive.uninstall phx_new or deleting the file, which is usually in ~/.mix/archives/. Then copy the repository, then run the Mix task from within the installer directory.

cd phoenix/installer
mix phx.new dev_app --dev

What --dev does is worth reading closely. It configures the new project's :phoenix dependency as a relative path dependency, and the generated deps function ends up looking like this.

defp deps do
  [{:phoenix, path: "../..", override: true},

So the generated app depends on a directory that exists only on your machine, with override enabled. That is exactly what you want while testing a change and exactly what you must not commit, which is why the flag is opt-in rather than the default.

The silent failure mode is the archive. If an older phx_new is installed, Mix prefers it over your checkout and your changes appear to have no effect.

Phoenix.js is tested against mock-socket, not against a live Phoenix

The JavaScript test setup is Jest, with jsdom for the DOM, and mock-socket among the dev dependencies. The test script runs Node with the experimental VM modules flag before invoking the Jest binary directly.

node --experimental-vm-modules ./node_modules/jest/bin/jest.js

The important consequence is what mock-socket implies. The client is verified against a simulated WebSocket, which tests the client's behaviour in isolation.

The Elixir side has its own test/ directory and a separate integration_test/ directory, plus a .formatter.exs at the root for the standard formatter. So the two halves of the framework are tested by separate suites with separate tooling, and this README documents no command that runs both.

guides/ and usage-rules/ are documentation that lives in the tree

Two directories at the root are documentation rather than code, and one of them has a name that says what it is for. guides/ and usage-rules/ sit alongside the code.

The README does not describe the contents of either, which is an honest gap rather than an oversight: the front page routes readers elsewhere. It says to see the official site at phoenixframework.org for getting started, to follow the installation instructions at phoenix.hexdocs.pm for the latest released version, and to find API documentation at phoenix.hexdocs.pm with the client docs at phoenix.hexdocs.pm/js.

So the split is consistent across the project. Guides and usage rules are versioned with the code, while the rendered documentation and the installation instructions are hosted, and the front page carries links rather than content.

For questions and proposals there is a Phoenix Forum, and the Elixir channels are IRC on Libera and the elixir-lang Slack. Commercial consulting is pointed at DockYard, which is the one commercial relationship the README names.

Copyright 2014 Chris McCord, and a MIT licence with a sponsor section

The copyright line reads Copyright (c) 2014, Chris McCord, and the source is licensed under the MIT Licence with LICENSE.md at the root. The same author is named in package.json, with the project site in the author field.

The licence is the permissive one, so embedding the framework carries the usual MIT obligations and nothing more.

The governance files are conventional and complete for the size of the project: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md and RELEASE.md.

What the repository does not contain is worth noting too. There is no benchmark, no comparison against another framework, and no performance claim anywhere on the front page. The one sentence describing the project is Peace of mind from prototype to production, and everything a reader would use to evaluate that claim lives on the hosted documentation site instead.

Editorial conclusion

Phoenix fits an Elixir team that wants the framework, its project generator and its JavaScript client to move together in one release, and that is willing to read documentation on hexdocs rather than in the repository. It does not fit a team that wants a single artefact, because producing any of the four means deciding which Mix tasks to run, and it does not suit a contributor who works only on the client without Elixir installed. Verify first which Phoenix you are actually testing, because an installed phx_new archive silently shadows a local checkout until you remove it.

Frequently asked questions

Official sources

1. License: MIT
2. phoenixframework/phoenix on GitHub
3. Project website
4. README
5. Releases