tostada

Makefile Reference

Complete guide to all development, testing, and deployment commands available via make.

The tostada Makefile is your primary interface for working with the project. It abstracts away the complexity of coordinating both Phoenix (Elixir) and SvelteKit (Node.js) toolchains.

Quick Start

# See all available commands
make help

# Install dependencies (both server and client)
make install

# Start development servers (requires tmux)
make dev

# Run tests
make test

# Build for production
make build

Installation Commands

make install

Install dependencies for both server and client.

What it does:

  • Runs mix deps.get in server/
  • Runs npm install in client/

When to use: First time setup, or after pulling changes that add dependencies.

make install

make install.server

Install server (Phoenix/Elixir) dependencies only.

What it does:

  • Runs mix deps.get in server/

When to use: When you’ve only modified mix.exs or need to update Elixir deps.

make install.server

make install.client

Install client (SvelteKit/Node.js) dependencies only.

What it does:

  • Runs npm install in client/

When to use: When you’ve only modified package.json or need to update npm packages.

make install.client

Development Commands

make dev

Recommended: Start both Phoenix and SvelteKit dev servers together.

What it does:

  • Requires tmux to be installed
  • Launches Phoenix server in one pane (logs to logs/server.log)
  • Launches Vite dev server in another pane (logs to logs/client.log)
  • Creates a split terminal view so you can see both servers

Ports:

  • Client dev server: http://localhost:5173 (with hot reload)
  • Phoenix server: http://localhost:4000 (API + WebSocket)

When to use: Normal development workflow. You’ll spend most of your time here.

make dev

No tmux? The command will print instructions to run servers in separate terminals:

make dev.server  # Terminal 1
make dev.client  # Terminal 2

make dev.server

Start Phoenix server only.

What it does:

  • Runs mix phx.server in server/
  • Logs output to logs/server.log (and stdout)
  • Starts HTTP server on port 4000
  • Enables hot code reloading for Elixir files

When to use: When you only need the backend running, or running servers in separate terminals.

make dev.server

Access: http://localhost:4000

make dev.client

Start SvelteKit dev server only (Vite).

What it does:

  • Runs npm run dev in client/
  • Starts Vite dev server on port 5173
  • Enables hot module replacement (HMR) for Svelte/TypeScript files
  • Proxies /api, /socket, /live, /users, /assets to Phoenix (localhost:4000)

When to use: When you only need the frontend running, or running servers in separate terminals.

make dev.client

Access: http://localhost:5173

make dev.logs

Tail the server log file in real-time.

What it does:

  • Runs tail -f logs/server.log

When to use: When running make dev in the background and you want to monitor Phoenix output.

make dev.logs

Press Ctrl+C to stop tailing.

make dev.logs.clear

Clear development log files.

What it does:

  • Removes logs/server.log and logs/client.log

When to use: When logs get too large or you want a fresh start.

make dev.logs.clear

Database Commands

All database commands run Ecto (Phoenix’s database toolkit) in the server/ directory.

make db.create

Create the database.

What it does:

  • Runs mix ecto.create
  • Creates PostgreSQL database specified in config/dev.exs (default: tostada_dev)

When to use: First time setup, or after make db.drop.

make db.create

Tip: Database must exist before running migrations or starting the server.

make db.drop

Drop (delete) the database.

What it does:

  • Runs mix ecto.drop
  • Permanently deletes the database and all data

When to use: When you want to completely reset the database (use make db.reset for a safer reset).

make db.drop

⚠️ Warning: This is destructive. All data will be lost.

make db.migrate

Run pending database migrations.

What it does:

  • Runs mix ecto.migrate
  • Applies migration files from server/priv/repo/migrations/ in timestamp order

When to use: After pulling changes that include new migrations, or after creating your own migrations.

make db.migrate

make db.rollback

Rollback the last migration.

What it does:

  • Runs mix ecto.rollback
  • Reverts the most recent migration (runs the down/0 function)

When to use: When you need to undo a migration (e.g., to fix a mistake before re-running it).

make db.rollback

# Rollback multiple migrations
cd server && mix ecto.rollback --step 3

make db.reset

Recommended: Reset database to clean state with seed data.

What it does:

  • Runs mix ecto.reset
  • Equivalent to: drop → create → migrate → seed
  • Loads seed data from server/priv/repo/seeds.exs

When to use: When you want a fresh database with sample data.

make db.reset

make db.setup

Setup database and load seeds (without dropping).

What it does:

  • Runs mix ecto.setup
  • Equivalent to: create → migrate → seed
  • Does not drop existing database

When to use: First time setup, when database doesn’t exist yet.

make db.setup

Testing Commands

make test

Run all tests (server + client).

What it does:

  • Runs mix test in server/ (ExUnit tests)
  • Runs npm run test in client/ (Vitest unit tests)

When to use: Before committing, before deploying, in CI pipelines.

make test

make test.server

Run Phoenix/Elixir tests only.

What it does:

  • Runs mix test in server/
  • Uses test database environment (configured in config/test.exs)

When to use: When you’ve only modified server-side code.

make test.server

Tip: Run specific test files:

cd server && mix test test/tostada_web/channels/game_channel_test.exs

make test.client

Run SvelteKit/TypeScript unit tests only.

What it does:

  • Runs npm run test in client/
  • Uses Vitest for unit testing

When to use: When you’ve only modified client-side code.

make test.client

Linting & Type Checking

make lint

Run linters on both server and client (check mode, does not fix).

What it does:

  • Runs mix format --check-formatted in server/
  • Runs npm run check in client/ (svelte-check + TypeScript)

When to use: In CI pipelines, before committing.

make lint

make lint.fix

Auto-fix linting issues.

What it does:

  • Runs mix format in server/ (formats Elixir code)
  • Runs npm run check in client/ (checks but doesn’t fix TypeScript/Svelte)

When to use: After writing a bunch of code, to format it automatically.

make lint.fix

Note: Client npm run check doesn’t auto-fix TypeScript errors, only reports them.

make typecheck

Run TypeScript type checking only (client).

What it does:

  • Runs npm run check in client/
  • Uses svelte-check to validate types in Svelte + TypeScript files

When to use: When you want to check types without running tests.

make typecheck

Build Commands

make build

Build for production (client + server assets).

What it does:

  1. Compiles Phoenix app: MIX_ENV=prod mix compile
  2. Runs client prebuild script: npm run prebuild (in client/)
  3. Builds SvelteKit static site: npm run build (in client/)
  4. Deploys Phoenix assets: MIX_ENV=prod mix assets.deploy

Output:

  • SvelteKit static site → server/priv/static/app/
  • Tailwind/esbuild assets → server/priv/static/assets/

When to use: Before deployment, to create production-ready assets.

make build

make build.client

Build SvelteKit client only.

What it does:

  • Runs npm run prebuild (cleanup/pre-build tasks)
  • Runs npm run build (builds static site to server/priv/static/app/)

When to use: When you’ve only modified client-side code and want to rebuild it.

make build.client

make build.server

Build Phoenix assets only.

What it does:

  • Runs MIX_ENV=prod mix assets.deploy
  • Compiles Tailwind CSS and esbuild for auth pages
  • Generates digested asset filenames (for cache busting)

When to use: Rarely needed (usually run as part of make build).

make build.server

make assets.deploy

Run Phoenix asset pipeline (Tailwind + esbuild + digest).

What it does:

  • Same as make build.server
  • Compiles and digests static assets for production
make assets.deploy

Model Pipeline Commands

Optional commands for the 3D model build pipeline (requires model_pipeline addon).

make models.build

Build GLTF/GLB models into Svelte components.

What it does:

  • Runs ./scripts/build-models.sh
  • Converts models from server/priv/static/obj/ into:
    • Svelte components in client/src/lib/models/generated/
    • Optimized GLB files in client/static/models/
    • Registry file for lazy loading

When to use: After adding or updating .gltf or .glb files in server/priv/static/obj/.

make models.build

Requirements: model_pipeline addon must be enabled (it is by default).

make models.clean

Remove generated model outputs.

What it does:

  • Deletes client/src/lib/models/generated/
  • Deletes client/src/lib/models/generated-registry.ts
  • Deletes client/static/models/

When to use: When you want to rebuild models from scratch.

make models.clean

Deployment Commands

Commands for deploying to production servers. These run scripts from server/scripts/deploy/.

make deploy.build

Build a production release tarball.

What it does:

  • Runs ./server/scripts/deploy/build.sh
  • Creates a self-contained release package
  • Outputs to server/_build/prod/rel/

Environment variables:

  • APP_NAME: Your app’s name (defaults to tostada)

When to use: On your build server, before deploying to production.

APP_NAME=my_game make deploy.build

make deploy.release

Run migrations and restart the production app.

What it does:

  • Runs ./server/scripts/deploy/deploy.sh
  • Runs pending database migrations
  • Restarts the systemd service

Environment variables:

  • APP_NAME: Your app’s name
  • APP_MODULE: Your app’s Elixir module (e.g., MyGame)

When to use: On your production server, after uploading a new release.

APP_NAME=my_game APP_MODULE=MyGame make deploy.release

make deploy.full

Full deployment: pull latest code + build + deploy.

What it does:

  • Runs ./server/scripts/deploy/full-deploy.sh
  • Runs git pull to get latest code
  • Builds release
  • Runs migrations
  • Restarts app

When to use: On your production server for a complete update cycle.

make deploy.full

⚠️ Warning: This assumes your code is tracked in Git and the production server has access to the repo.

Cleanup Commands

make clean

Clean build artifacts (both server and client).

What it does:

  • Runs mix clean in server/ (removes _build/ compiled files)
  • Removes client/.svelte-kit/ and client/build/

When to use: When you want a completely clean build (rare, usually not needed).

make clean

make clean.deps

Remove all dependencies (both server and client).

What it does:

  • Removes server/deps/ and server/_build/
  • Removes client/node_modules/

When to use: When you suspect corrupted dependencies, or want to free up disk space.

make clean.deps

# Then reinstall
make install

⚠️ Warning: You’ll need to run make install afterwards to reinstall everything.

Common Workflows

Starting a Fresh Project

make install          # Install dependencies
make db.setup         # Create database and run migrations
make dev              # Start development servers

Daily Development

make dev              # Start servers (leave running)
# Edit code in your editor
# Browser auto-reloads on changes

After Pulling Changes

git pull
make install          # If dependencies changed
make db.migrate       # If new migrations exist
make dev              # Restart servers

Before Committing

make lint             # Check formatting
make test             # Run all tests
git add .
git commit -m "..."

Deploying to Production

# On build server:
make build
APP_NAME=my_game make deploy.build

# On production server:
APP_NAME=my_game APP_MODULE=MyGame make deploy.release

Troubleshooting

“tmux not installed” Error

If make dev fails because tmux isn’t installed:

# Install tmux (macOS)
brew install tmux

# Or run servers separately
make dev.server  # Terminal 1
make dev.client  # Terminal 2

“Database does not exist” Error

make db.create
make db.migrate

“Mix dependencies not available” Error

make install.server

“node_modules not found” Error

make install.client

Ports Already in Use

If ports 4000 or 5173 are already in use:

# Find and kill processes using the ports
lsof -ti:4000 | xargs kill -9
lsof -ti:5173 | xargs kill -9

Next Steps

Run make help anytime to see the full command list!