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

📦 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

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

💡 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

🎨 How to Extend

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

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

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