A production-ready Phoenix + Inertia.js (React, SSR) starter — authentication, real-time, i18n, theming, testing, CI, and Docker, already wired and tested.
I want to build web apps using Phoenix. LiveView is great, but I'm familiar with and prefer the rich React ecosystem. In the past, I would have reached for a frontend framework (e.g. Next.js), with an Elixir backend API. This has numerous downsides, including having to manage and sync deployments, migrations, versions, additional infrastructure etc. all of which compound complexity exponentially. Inertia.js provides a way of acting as the glue between Phoenix and React (or Vue or Svelte), so you don't have to deal with the complexities of separate repos.
This template project serves as a starting point for a lot of my web applications, so that I don't have to duplicate a lot of the setup work. It's fully featured (see Features below). Feel free to use it however you want or submit a PR if you find some way of improving it.
It's provided as-is, with no guarantees or warranties of any kind — use it at your own risk.
- Authentication — email + password with link-based confirmation and password reset, Argon2 hashing, sliding sessions, account management, and no email enumeration.
- Real-time — token-authenticated Phoenix Channels with React hooks that survive Inertia navigation.
- Internationalization — gettext on the server and react-i18next on the client; English + Spanish with locale detection.
- Theming — light / dark / system with no flash of the wrong theme.
- Accessibility — Radix UI primitives, Biome a11y linting in CI, and axe-core auditing in dev.
- Email — Swoosh (HTML + text) via Mailjet in production, with an in-browser mailbox in dev.
- Security — rate-limited auth endpoints, a strict nonce-based Content-Security-Policy, Secure cookies, CSRF protection, and HTTPS/HSTS in production.
- Background jobs — Oban, configured and ready.
- Testing — ExUnit with a coverage gate, ex_machina factories, and a Playwright E2E suite.
- Tooling & CI — mise-pinned toolchain, Biome / Credo / Dialyzer, and GitHub Actions.
- Deployment — multi-stage Docker release with server-side rendering.
- Documentation — ex_doc guides and module reference.
- Backend — Elixir · Phoenix (Bandit) · Ecto + PostgreSQL · Oban · Swoosh · gettext
- Frontend — Inertia.js · React (SSR) · Tailwind CSS · Radix UI · esbuild · TypeScript · Biome
- Tooling — mise · Credo · Dialyzer · ex_doc · ExUnit + ex_machina · Playwright · GitHub Actions · Docker
Prerequisites: mise (pins the toolchain) and a running PostgreSQL.
Starting a new project from this template? Rename it to your own name first:
scripts/rename_project.sh YourAppName # PascalCaseIt rewrites every module, the OTP app name, file/directory paths, and configs (both
PascalCaseandsnake_caseforms), then rebuilds and runsmix precommitto verify. Use--dry-runto preview the changes first.
# 1. Install the pinned Erlang, Elixir, and Node (versions live in mise.toml)
mise trust && mise install
# 2. Install deps, create + migrate the database, build assets
mix setup
# 3. Start the server
mix phx.server # or: iex -S mix phx.serverVisit localhost:4000. With shell activation enabled
(eval "$(mise activate zsh)" in ~/.zshrc), mise switches to the project's
toolchain automatically when you cd in.
Each branch can have a worktree of its own, a separate checkout made with
Worktrunk (wt, pinned in mise.toml), so several people or
agents can work at once without stopping :4000 or getting in each other's way:
wt switch --create andre/123-some-fix --base origin/main # a new worktree and branch
mise trust # once, in the new worktree
wt serve andre/123-some-fix # look at it in the browser, beside :4000 (Ctrl+C stops it)
mix test # unit tests, on the worktree's own test database
scripts/e2e login # browser specs, on the worktree's own server
wt remove andre/123-some-fix # when done: the worktree and its databasesmix test in a linked worktree uses a test database named after the
worktree's directory (the main checkout keeps elixir_react_starter_test),
so test runs in several worktrees, the pre-commit hook's included, never see
each other's rows. wt remove drops that database and the worktree's E2E
one through the post-remove hook in .config/wt.toml, which Worktrunk asks
you to approve once.
Where worktrees go is up to your own Worktrunk config
(~/.config/worktrunk/config.toml). To keep them out of the project
directory and prune merged ones whenever you start a new one:
worktree-path = "~/.worktrees/{{ repo }}/{{ branch | sanitize }}"
post-start = "git fetch -q origin && wt step prune"To see a worktree in the browser without stopping the server on :4000, serve it beside it:
wt serve # pick the worktree from a list
wt serve andre/some-branch # a branch's worktree
wt serve 957 # the worktree of PR #957
scripts/preview # or this, from inside the worktreewt serve is defined in the repo's Worktrunk config (.config/wt.toml), so
Worktrunk asks you once to approve it. It runs the main checkout's copy of
scripts/preview, and your shell stays where it is.
The preview prints its address, the same for a branch every time (between
4100 and 4899). It uses the same dev database as :4000, so log in as usual.
Its background jobs run inline on its own code and stay out of :4000's
queue, so its emails land in its own /dev/mailbox. It never runs database
migrations: a branch that adds some shows the pending-migrations page until
you run mix ecto.migrate yourself.
To see which worktree is being served where, add a Preview column to your own
Worktrunk config (~/.config/worktrunk/config.toml; Worktrunk reads columns
only from there). It shows in wt list and the wt serve picker:
[projects."github.com/andreogle/ElixirReactStarter".list.custom-columns.Preview]
template = "{{ git.branch.previewurl }}"mix test # unit + integration, with coverage gate (mix test --cover)
mix precommit # format, credo, biome, i18n, tests — run before every commit
scripts/e2e login # Playwright specs for one flow, on a server of their ownscripts/e2e runs the specs you name against a server of the worktree's
own, then stops it. The server gets a free port and a database of its own,
elixir_react_starter_e2e_<branch>, which the script creates and migrates,
so it never needs the dev database to be up to date and never changes it,
and several worktrees can run specs at once. Any Playwright arguments pass
through (scripts/e2e login -g "bad"). CI runs the whole suite on every
pull request.
See the End-to-End Testing guide for the Playwright setup.
Searchable developer guides and the full module reference are generated with ex_doc:
mix docsIn development they're also served at
/dev/docs. Topic guides live in
docs/ — e.g. the End-to-End Testing guide and
Frontend Pages: SSR vs. Client.
SECRET_KEY_BASE must be generated once and kept stable across restarts — a
changing value invalidates every session and signed cookie. Generate it a single
time with mix phx.gen.secret and store it in your secrets manager or host config,
then build and run the release image (reading the stored values from the environment):
docker build -t elixir_react_starter .
docker run -p 4000:4000 \
-e DATABASE_URL="ecto://USER:PASS@HOST/DB" \
-e MAILJET_API_KEY="$MAILJET_API_KEY" \
-e MAILJET_SECRET="$MAILJET_SECRET" \
-e PHX_HOST="example.com" \
-e SECRET_KEY_BASE="$SECRET_KEY_BASE" \
elixir_react_starterconfig/runtime.exs requires DATABASE_URL, MAILJET_API_KEY, MAILJET_SECRET,
and SECRET_KEY_BASE and will refuse to boot without them. PHX_HOST defaults to
example.com but should always be set in production (it's used for absolute URLs
in emails). PORT (default 4000), POOL_SIZE, ECTO_IPV6,
DNS_CLUSTER_QUERY, TRUST_PROXY_HEADERS, TRUSTED_PROXIES,
CLIENT_IP_HEADERS, SSR_POOL_SIZE
(number of Inertia SSR Node workers, default 2), and NODE_OPTIONS (set in the
Dockerfile to --max-old-space-size=160, caps each SSR worker's V8 heap) are
optional. The last two are the main levers on the Node-side memory the SSR pool
uses — see Frontend Pages: SSR vs. Client. The
Dockerfile also sets NODE_ENV=production; don't override it — without it each
SSR worker reloads the bundle on every render, leaking heap until it aborts.
Sentry is opt-in through SENTRY_DSN and SENTRY_DSN_FRONTEND.
SSR uses SENTRY_DSN_SSR, falling back to the frontend DSN. Errors include
the signed-in user's ID, without copying their email or other profile fields.
Browser identity follows Inertia navigation and clears on logout; SSR identity
is attached per error so pooled workers do not share users.
The JavaScript SDKs explicitly disable automatic user/IP, cookie, header, body, query-parameter, database payload, AI input/output, queue argument, GraphQL document/variable and stack-variable collection. Tracing and replay remain unconfigured. Backend events retain only user ID and request method/URL, with query strings, fragments and URL credentials removed. Error messages, stack traces and breadcrumbs still provide diagnostics; do not put personal data or secrets in custom error messages or context.
If traffic reaches the app through a load balancer or CDN — Render, Fly, an ALB,
a Kubernetes ingress, Cloudflare — set TRUST_PROXY_HEADERS=true. Without it
conn.remote_ip is the balancer's address, so the IP-keyed auth rate limits
collapse into a single shared bucket for every client (the email-keyed limits
still work).
It's off by default on purpose: forwarding headers are only trustworthy when
something in front of the app rewrites them on every request. Honouring them on
a directly-exposed server would let any caller spoof X-Forwarded-For and get a
fresh rate-limit bucket per request.
Proxies that reach the app from a private address need nothing further — private
and reserved ranges are always treated as proxies. For a proxy on a public
address, list its ranges in TRUSTED_PROXIES (comma-separated CIDRs), or it will
be mistaken for the client.
Behind Cloudflare, also set CLIENT_IP_HEADERS=cf-connecting-ip. Cloudflare's
edge terminates on a public address, so the default x-forwarded-for walk stops
there and reports the edge as the caller — every visitor arriving through the
same edge shares one rate-limit bucket. That is better than the single global
bucket, and still not per-caller. cf-connecting-ip holds the address Cloudflare
already resolved, so there is no chain to walk. Listing Cloudflare's published
ranges in TRUSTED_PROXIES works too, but that list has to be kept current.
Whichever header is trusted, a request that reaches the origin directly — bypassing the proxy — can forge it and pick its own rate-limit bucket. Closing that off means restricting origin access to the proxy (IP allowlisting, a tunnel, or authenticated origin pulls). The exposure is limited to rate limiting, not authorization, but it is worth deciding deliberately rather than by default.
Database migrations run via the release: bin/migrate. See Phoenix's
deployment guides for hosting specifics.
GET /health returns {"status":"ok"} — cheap, no database calls, no external
lookups. The image's HEALTHCHECK polls it via the embedded Node binary, and
it's a sensible target for Kubernetes liveness/readiness probes too.
Runtime versions are pinned in two places that must agree: mise.toml (dev
and CI toolchain, via mise) and the ARG declarations
at the top of the Dockerfile (release build). mix precommit runs
scripts/check-tool-versions.sh as its first step and will fail if those drift —
so when bumping a runtime version, update both files in the same commit.
Project architecture, invariants, and coding conventions are documented in
CLAUDE.md — start there before making changes.
Released under the WTFPL (see the LICENSE file) — do what the fuck you want.
