README

A modern full-stack starter template combining Tempest PHP Framework for the backend API and Next.js for the frontend dashboard.

Tech Stack

Prerequisites

• Docker and Docker Compose
• PHP 8.4+ and Composer (for installation)
• (Optional for local development without Docker):
  • Node.js 24+ with pnpm

Quick Start

Option 1: Composer Create-Project (Recommended)

composer create-project luminarix/tempest-nextjs-starter my-project
cd my-project
docker compose up -d

Option 2: Clone from GitHub

git clone https://github.com/luminarix/tempest-nextjs-starter.git my-project
cd my-project

# Copy environment files
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

# Start with Docker
docker compose up -d

That's it! Your application is now running:

• Frontend: http://localhost:3000
• Backend API: http://localhost

Local Development (Without Docker)

Backend Setup

cd backend

# Install dependencies
composer install

# Generate application key
./tempest key:generate

# Start the development server
./tempest serve

The API will be available at http://localhost:8000

Frontend Setup

cd frontend

# Install dependencies
pnpm install

# Update .env for local backend
echo "API_URL=http://localhost:8000" > .env.local
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" >> .env.local

# Start development server
pnpm run dev

The frontend will be available at http://localhost:3000

Project Structure

.
├── backend/                 # Tempest PHP API
│   ├── app/
│   │   ├── Api/            # API Controllers
│   │   └── ResponseProcessors/  # Response processors (CORS, etc.)
│   ├── tests/              # PHPUnit tests
│   ├── composer.json
│   ├── phpunit.xml
│   ├── mago.toml           # PHP formatter config
│   └── tempest             # CLI entrypoint
│
├── frontend/               # Next.js Application
│   ├── src/
│   │   ├── app/           # Pages and layouts (App Router)
│   │   └── lib/           # Utilities, hooks, providers
│   ├── package.json
│   ├── biome.json         # Linter/formatter config
│   └── next.config.ts
│
├── docker-compose.yml      # Container orchestration
├── Backend.dockerfile
└── Frontend.dockerfile

Available Commands

Backend

Run from the tempest container:

Frontend

Run from the nextjs container:

Docker

Run from the project root:

Environment Configuration

Backend (backend/.env)

ENVIRONMENT=local          # local, staging, production
BASE_URI=http://localhost:8000
FRONTEND_URL=http://localhost:3000  # CORS allowed origin

Frontend (frontend/.env)

API_URL=http://tempest:8080           # Server-side (Docker internal, use localhost if you don't use Docker)
NEXT_PUBLIC_API_URL=http://localhost  # Client-side (browser)

Testing

Backend Tests

# Run all tests
docker compose exec tempest composer phpunit

# Run specific test file
docker compose exec tempest ./vendor/bin/phpunit tests/ApiTest.php

# Run specific test method
docker compose exec tempest ./vendor/bin/phpunit --filter testVersionEndpoint

Frontend Tests

# Run all tests
docker compose exec nextjs pnpm test

# Run tests in watch mode
docker compose exec nextjs pnpm test:watch

Code Quality

Both backend and frontend have pre-configured linting and formatting:

# Backend - run all quality checks (format, test, lint)
docker compose exec tempest composer qa

# Frontend - run all quality checks (lint, test, build)
docker compose exec nextjs pnpm qa

CORS Configuration

CORS is handled by CorsResponseProcessor in the backend. To modify allowed origins, update backend/.env:

FRONTEND_URL=http://localhost:3000

For multiple origins or more complex CORS rules, modify backend/app/ResponseProcessors/CorsResponseProcessor.php.