Sample Elixir + Phoenix + Vite + React Application

This repo contains a starter setup, including authentication via Clerk, for a monolith stack for a development environment. This setup could also be extended to support other environments for deployment (e.g. staging and production). Stubs for production have been created but are not built out and will not work without additional configuration and setup.

Stack/Tools

Below are the technologies & tools that make up the stack.

Backend

• Elixir - The Elixir programming language
• Erlang - Elixir runs on the Erlang VM
• Phoenix - A web framework for Elixir
• PostgreSQL - The database
• Docker - Runs the containerized version of the application
• OpenAPI Spex - Leverage OpenAPI Spec 3 - Required to produce an API schema that can be used to generate TypeScript typings for the frontend
• Ecto - Data mapping toolkit (maps data from PostgreSQL into Elixir structs)
• Credo - Static code analysis tool for Elixir

Frontend

• React.js - The library used to create frontend (UI) components
• TypeScript - Type-safe JavaScript
• Vite - Frontend build tool
• Vitest - Vite-native testing framework
• React Testing Library - React DOM testing utilities
• Playwright - End-to-end tests
• Tanstack Router - Type-safe routing for React
• Tanstack Query - Async state management and data fetching
• React Hook Form - Performant forms with easy validation
• Clerk - Auth and user management
• Mantine - React components library
• Lucide - Icon library
• Zod - Validation
• ESLint - Static code analysis tool JavaScript & JSX
• Prettier - Opinionated code formatter
• OpenAPI TypeScript - Converts OpenAPI 3 schemas to TypeScript types enabling type-safe fetching
• Pnpm - Package manager

Setup

Local Development

1. Install ASDF

   brew install asdf

   # Add ASDF shims (tool version manager) to PATH env
   export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

2. Install NodeJS

   asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
   asdf install nodejs 24.8.0

3. Install Erlang

   asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
   asdf install erlang 27.3.4.2

4. Install Elixir

   asdf plugin add elixir https://github.com/asdf-vm/asdf-elixir.git
   asdf install elixir 1.18.4

5. Install & Start PostgreSQL

   # Install Postgres DB
   brew install postgresql@18

   # Install "psql" Postgres client (MacOS)
   brew install libpq

   # Start PostgreSQL service
   brew services start postgresql@18

   # Connect to Postgres server
   > psql postgres
   
   # Add "postgres" user
   CREATE USER postgres WITH PASSWORD 'postgres';
   
   # Give user necessary privileges
   ALTER USER postgres WITH SUPERUSER CREATEDB CREATEROLE;

6. Install pnpm

   # Install pnpm package manager for frontend
   brew install pnpm

7. Set Environment Variables

   # Generate Clerk test secrets
   ./scripts/gen_clerk_test_secrets.sh

   # Create secrets/clerk_public_jwks_key.pem
   touch secrets/clerk_public_jwks_key.pem
   
   # !!! IMPORTANT !!!
   # Copy the JWKS Public Key to this new empty file.
   # The key can be found inside the Clerk dashboard located at Configure > API Keys

   # Copy the ".env_sample" file to ".env"
   scp .env_sample .env
   
   # Copy the "frontend/.env_sample" file to "frontend/.env"
   scp frontend/.env_sample frontend/.env
   
   # !!! IMPORTANT !!!
   # Replace values in ".env" with appropriate ones and remove all comments in ".env" files

   # Export environment variables in ".env" and autofill "frontend/.env"
   source ./scripts/export_env.sh

8. Setup Application

   # Install and set up dependencies
   mix setup

   There are two ways to run the application on your local machine.

   1. In "production" mode on local machine. This just means the frontend needs to be built and served from Phoenix.

      # Build the frontend (optional since "mix setup" should perform this step for you)
      # However, if changes are made to the frontend, then this will need to be run again.
      mix webapp
      
      # Start Phoenix server
      mix phx.server

      After the server starts, visit localhost:4000.

   2. In "development" mode on local machine. This means the frontend will be served up by Vite on port 5173 with Hot Module Replacement (HMR).

      # Start dev build with HMR using Vite
      cd frontend
      pnpm dev
      
      # Start Phoenix server
      # The Phoenix server still needs to be available for backend services (auth, api)
      mix phx.server

      After the server starts, visit localhost:5173.

Using Docker (Recommended)

Development Environment

1. Start the development environment:

   ./docker/dev.sh up

2. Access the application:

   • Web app: http://localhost:4000
   • PostgreSQL: localhost:5432

3. Run database migrations:

   ./docker/dev.sh migrate

Docker Commands

Development

• ./docker/dev.sh up - Start development environment
• ./docker/dev.sh down - Stop development environment
• ./docker/dev.sh logs - Show application logs
• ./docker/dev.sh shell - Open shell in web container
• ./docker/dev.sh migrate - Run database migrations
• ./docker/dev.sh test - Run tests
• ./docker/dev.sh deps - Install dependencies
• ./docker/dev.sh psql - Connect to PostgreSQL database
• ./docker/dev.sh clean - Clean up containers and volumes

Environment Variables

Required for Production (WIP)

• SECRET_KEY_BASE - Secret key for Phoenix (generate with mix phx.gen.secret)
• DATABASE_URL - PostgreSQL connection string

Optional (WIP)

• PORT - Port to run the application on (default: 4000)
• MIX_ENV - Environment (dev/prod)
• PHX_SERVER - Enable Phoenix server (true/false)

Services

• Phoenix Web App - Port 4000
• PostgreSQL Database - Port 5432 (PostgreSQL 18)

Learn more

• Official website: https://www.phoenixframework.org/
• Guides: https://hexdocs.pm/phoenix/overview.html
• Docs: https://hexdocs.pm/phoenix
• Forum: https://elixirforum.com/c/phoenix-forum
• Source: https://github.com/phoenixframework/phoenix