🚀 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