README

🚀 PhpSPA + Vite Starter

A PhpSPA boilerplate that serves PhpSPA pages first, then hydrates navigation with Vite + TypeScript + Tailwind.

🌐 Live Preview • Documentation

✨ What You Get

🎯 Zero Config

PHP renders first request
PhpSPA handles client nav
Auto asset switching

⚡ Lightning Fast

Vite HMR < 50ms
Instant page transitions
Production optimized

🎨 Modern Stack

Tailwind v4 utilities
TypeScript ready
SEO-friendly meta tags

📦 Everything Included

Component system
State management
Syntax highlighting

📦 Installation

composer create-project phpspa/client my-project
cd my-project

🎯 Quick Start

Step 1: Start Development Servers

# Terminal 1 – Vite dev server with HMR
pnpm dev

# Terminal 2 – PHP built-in server
php -S localhost:8000 index.php

Open http://localhost:8000 in your browser.

⚠️ IMPORTANT: Development Script Tags

🔴 CRITICAL STEP – This starter supports a Vite-dev workflow by loading Vite’s HTML when the dev server is running.

To enable Vite HMR during development, add these two lines to index.html before </body>:

<script type="module" src="http://localhost:5173/@vite/client"></script>
<script type="module" src="http://localhost:5173/src/main.ts"></script>

What each script does:

Script	Purpose
`@vite/client`	🔥 Connects browser to Vite HMR server (port 5173) for instant hot module updates
`src/main.ts`	🎬 Your app entry point: imports styles, registers hooks, boots `@dconco/phpspa` runtime

💡 Pro tip: Leave these in during dev, remove them before deploying to production.

How the layout decides what to serve

In app/layout/layout.php we first try to fetch the Vite dev server (default http://localhost:5173).
If the dev server is reachable, we use its HTML (HMR works).
If it’s not reachable, we fall back to index.html and load the production assets from public/assets/.vite/manifest.json.

Changing the Vite dev server URL

If your Vite server is not http://localhost:5173 (different host/port), you must update both:

index.html (the two <script type="module"> URLs)
app/layout/layout.php ($viteDevOrigin)

🏗️ Production Build

Step 1: Build Assets

pnpm build

This generates optimized, hashed assets in public/assets/ and creates the Vite manifest.

Step 2: Deploy

php -S localhost:8000 index.php
# Or deploy to Apache/Nginx

When dev scripts are missing, app/layout/layout.php automatically loads manifest assets.

Production recommendation

Set APP_ENV=production in your environment.

This disables the dev-server probe entirely (no extra network call in production).
The layout always loads the manifest assets.

📜 Available Scripts

Command	Description
`pnpm dev`	🔧 Start Vite dev server with HMR on port 5173
`pnpm build`	📦 Production build to `public/assets/`
`pnpm preview`	👀 Preview production build served by Vite
`pnpm watch`	👁️ Continuous build mode for backend-only servers

🎨 How to Extend

Add New Pages

// app/pages/contact.php
return new Component(fn () => '<h1>Contact</h1>')
    ->route('/contact')
    ->title('Contact Us')

Then attach in index.php:

$app->attach(require 'app/pages/contact.php');

Add Client Hooks

// src/main.ts
import { useEffect, setState } from '@dconco/phpspa';

useEffect(() => {
    console.log('Page loaded!');
}, []);

🔎 SEO (Simple + Strong)

PhpSPA is PHP-first: every route returns real HTML on the first request (not an empty JS shell). That makes SEO straightforward:

Search bots see content immediately (server-rendered HTML response).
Dynamic SEO per route: set title, description, OpenGraph, etc. right on the route component.
Global defaults: set shared meta tags once in index.php.

Dynamic SEO per route (recommended)

Every route can define its own metadata:

// app/pages/HomePage.php
new Component($HomePage)
   ->route('/')
   ->title('PhpSPA Design System — Vite + Tailwind + PhpSPA')
   ->meta(name: 'description', content: 'Design-forward PhpSPA starter pairing PHP controllers with Vite, Tailwind, and typed state helpers for seamless SPA navigation.')
   ->meta(property: 'og:title', content: 'PhpSPA Design System — Vite + Tailwind + PhpSPA')
   ->meta(property: 'og:description', content: 'Explore PhpSPA component-driven PHP workflow, instant navigation, and production-ready Vite tooling.');

You can do the same for every page (see app/pages/AboutPage.php and app/pages/DocsPage.php).

Global SEO defaults

Set shared defaults once in index.php:

new App()
    ->meta(charset: 'UTF-8')
    ->meta(name: 'viewport', content: 'width=device-width, initial-scale=1.0');

Canonical URLs (production)

In production you should output a canonical link per request. This template includes a production-only canonical example in index.php.

🤝 Contributing

Issues and PRs welcome! Visit phpspa.tech for full documentation.

Built with ❤️ using PhpSPA + Vite

Documentation • GitHub • NPM Package

phpspa / client

Maintainers

Details