PHPackages                             luminarix/tempest-nextjs-starter - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. luminarix/tempest-nextjs-starter

ActiveProject[DevOps & Deployment](/categories/devops)

luminarix/tempest-nextjs-starter
================================

Full-stack starter with Tempest PHP backend and Next.js frontend

v1.0.0(4mo ago)07MITTypeScriptPHP ^8.4CI passing

Since Dec 14Pushed 4mo agoCompare

[ Source](https://github.com/luminarix/tempest-nextjs-starter)[ Packagist](https://packagist.org/packages/luminarix/tempest-nextjs-starter)[ RSS](/packages/luminarix-tempest-nextjs-starter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)DependenciesVersions (2)Used By (0)

Tempest + Next.js Starter Pack
==============================

[](#tempest--nextjs-starter-pack)

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

Tech Stack
----------

[](#tech-stack)

LayerTechnologyVersionBackend FrameworkTempest2.0PHPPHP8.4Frontend FrameworkNext.js16ReactReact19State ManagementTanStack Query5StylingTailwind CSS4PHP ToolingMago1.0 betaJS ToolingBiome2.2TestingPHPUnit12ContainerizationDocker-Prerequisites
-------------

[](#prerequisites)

- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
- PHP 8.4+ and Composer (for installation)
- (Optional for local development without Docker):
    - Node.js 24+ with pnpm

Quick Start
-----------

[](#quick-start)

### Option 1: Composer Create-Project (Recommended)

[](#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

[](#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**:
- **Backend API**:

Local Development (Without Docker)
----------------------------------

[](#local-development-without-docker)

### Backend Setup

[](#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

### Frontend Setup

[](#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

Project Structure
-----------------

[](#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
------------------

[](#available-commands)

### Backend

[](#backend)

Run from the `tempest` container:

CommandDescription`composer qa`Run all checks (format, test, lint)`composer phpunit`Run tests`composer fmt`Format code with Mago`composer lint`Lint code with Mago`./tempest`Tempest CLI (run with no args for help)`./tempest serve`Start development server`./tempest discovery:status`Check discovery cache status### Frontend

[](#frontend)

Run from the `nextjs` container:

CommandDescription`pnpm qa`Run all checks (lint, test, build)`pnpm test`Run tests with Vitest`pnpm dev`Start development server`pnpm build`Create production build`pnpm start`Run production server`pnpm lint`Lint with Biome`pnpm format`Format with Biome### Docker

[](#docker)

Run from the project root:

CommandDescription`docker compose up -d`Start all services`docker compose down`Stop all services`docker compose logs -f`View logs`docker compose exec tempest bash`Shell into backend container`docker compose exec nextjs sh`Shell into frontend containerEnvironment Configuration
-------------------------

[](#environment-configuration)

### Backend (`backend/.env`)

[](#backend-backendenv)

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

### Frontend (`frontend/.env`)

[](#frontend-frontendenv)

```
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
-------

[](#testing)

### Backend Tests

[](#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

[](#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
------------

[](#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-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`.

###  Health Score

37

—

LowBetter than 82% of packages

Maintenance78

Regular maintenance activity

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

146d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cb808569841214f1b6b59dca08b367015cdfbcf9826397f20db1efd3439e71bd?d=identicon)[xHeaven](/maintainers/xHeaven)

---

Top Contributors

[![xHeaven](https://avatars.githubusercontent.com/u/14284867?v=4)](https://github.com/xHeaven "xHeaven (8 commits)")

---

Tags

dockerstartertempestfullstacknext.js

### Embed Badge

![Health badge](/badges/luminarix-tempest-nextjs-starter/health.svg)

```
[![Health](https://phpackages.com/badges/luminarix-tempest-nextjs-starter/health.svg)](https://phpackages.com/packages/luminarix-tempest-nextjs-starter)
```

###  Alternatives

[spatie/docker

Run a docker container in your PHPUnit tests

478120.2k12](/packages/spatie-docker)[ryoluo/sail-ssl

Laravel Sail plugin to enable SSL (HTTPS) connection with Nginx.

188672.6k2](/packages/ryoluo-sail-ssl)[aschmelyun/fleet

Run multiple Laravel Sail websites on your local environment

33269.5k](/packages/aschmelyun-fleet)[testcontainers/testcontainers

Testcontainers implementation in PHP

199184.7k17](/packages/testcontainers-testcontainers)[contributte/bootstrap

Extra contrib to nette/boostrap

111.5M3](/packages/contributte-bootstrap)[phpexperts/dockerize

The quickest and easiest way to switch any PHP app/library to use Docker.

7116.9k21](/packages/phpexperts-dockerize)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)