Skip to content
Public template

About

Production-ready Phoenix 1.8 starter: Inertia.js + React SSR frontend, email/password auth, realtime channels, i18n, and light/dark theming.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

ElixirReactStarter

ElixirReactStarter

A production-ready Phoenix + Inertia.js (React, SSR) starter — authentication, real-time, i18n, theming, testing, CI, and Docker, already wired and tested.

CI

Why this exists

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.

Features

  • 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.

Tech stack

Getting started

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   # PascalCase

It rewrites every module, the OTP app name, file/directory paths, and configs (both PascalCase and snake_case forms), then rebuilds and runs mix precommit to verify. Use --dry-run to 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.server

Visit localhost:4000. With shell activation enabled (eval "$(mise activate zsh)" in ~/.zshrc), mise switches to the project's toolchain automatically when you cd in.

Working in a worktree

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 databases

mix 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"

Previewing a worktree

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 worktree

wt 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 }}"

Testing

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 own

scripts/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.

Documentation

Searchable developer guides and the full module reference are generated with ex_doc:

mix docs

In 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.

Deployment

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_starter

config/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.

Error monitoring

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.

Behind a proxy

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.

Liveness probe

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.

Bumping Erlang / Elixir / Node

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.

Conventions

Project architecture, invariants, and coding conventions are documented in CLAUDE.md — start there before making changes.

License

Released under the WTFPL (see the LICENSE file) — do what the fuck you want.

About

Production-ready Phoenix 1.8 starter: Inertia.js + React SSR frontend, email/password auth, realtime channels, i18n, and light/dark theming.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages