vite-wp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andreas Ekström (https://github.com/didair)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# ViteWP
+
+ViteWP is an Astro-first WordPress development framework.
+
+A ViteWP project **is** the local WordPress site: Composer installs WordPress, PHP runs WordPress, Astro renders the frontend, and one local URL serves admin, REST, media, previews, and Astro pages.
+
+```txt
+http://localhost:3000
+```
+
+PHP and Astro still run internally, but you normally only use the unified ViteWP URL.
+
+## Requirements
+
+- Node.js 20+
+- PHP 8.2+
+- Composer
+- MySQL or MariaDB
+
+ViteWP is bring-your-own database. It does not start MySQL for you.
+
+## Get started
+
+```bash
+mkdir my-site
+cd my-site
+npm init -y
+npm install vitewp astro typescript @astrojs/check
+npx vitewp init
+cp .env.example .env
+npm run dev
+```
+
+Edit `.env` with your database credentials, then open:
+
+```txt
+http://localhost:3000
+```
+
+If the database is empty, go to `/wp-admin/` and complete the WordPress installer.
+
+## Commands
+
+```bash
+npm run dev      # Start the local ViteWP runtime
+npm run doctor   # Check PHP, Composer, WordPress, config, and environment
+npm run types    # Generate WordPress-derived TypeScript types
+npm run check    # Run Astro type checking
+```
+
+For internal runtime diagnostics:
+
+```bash
+npm run dev -- --verbose
+```
+
+## Folder structure
+
+```txt
+my-site/
+  astro.config.mjs
+  vitewp.config.ts
+  composer.json
+  .env
+
+  src/
+    live.config.ts
+    pages/
+      [...slug].astro
+    templates/
+      pages/
+        front-page.astro
+        default.astro
+      posts/
+        single.astro
+        archive.astro
+      taxonomies/
+        taxonomy-[taxonomy].astro
+      search.astro
+      404.astro
+    wordpress/
+      client.ts
+      templates.ts
+      menus.ts
+      generated-types.ts
+
+  wordpress/
+    public/              # Composer-installed WordPress core
+    content/
+      mu-plugins/
+      themes/
+      plugins/
+      uploads/
+```
+
+## Templates
+
+The catch-all Astro route asks WordPress what the current URL is, then renders the first matching template from `src/templates`.
+
+Examples:
+
+```txt
+src/templates/pages/front-page.astro
+src/templates/pages/page-about.astro
+src/templates/pages/default.astro
+src/templates/posts/single.astro
+src/templates/posts/archive.astro
+src/templates/taxonomies/category.astro
+src/templates/search.astro
+src/templates/404.astro
+```
+
+## WordPress data
+
+ViteWP uses Astro Live Collections for WordPress data:
+
+```ts
+import { getLiveCollection, getLiveEntry } from 'astro:content';
+
+const route = await getLiveEntry('routes', { path: '/' });
+const posts = await getLiveCollection('posts', { page: 1, perPage: 10 });
+const menu = await getLiveEntry('menus', { location: 'primary' });
+```
+
+After `npm run dev` or `npm run check`, collection names and filters should have TypeScript completion.
+
+## Notes
+
+- WordPress core is installed into `wordpress/public` by Composer.
+- Do not commit `wordpress/public`, `.env`, `.vitewp`, or uploads.
+- The tiny placeholder theme exists only to keep WordPress admin happy.
+- Docker is optional, not required.

package/dist/astro.d.ts

@@ -0,0 +1,5 @@
+import type { AstroIntegration } from 'astro';
+export interface ViteWpAstroOptions {
+    configFile?: string;
+}
+export default function vitewp(_options?: ViteWpAstroOptions): AstroIntegration;

package/dist/astro.js

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export default function vitewp(_options = {}) {
+    return {
+        name: 'vitewp',
+        hooks: {
+            'astro:config:setup': ({ command, addDevToolbarApp, logger }) => {
+                if (command === 'dev') {
+                    addDevToolbarApp({
+                        id: 'vitewp',
+                        name: 'ViteWP',
+                        icon: 'sitemap',
+                        entrypoint: getDevToolbarEntrypoint(),
+                    });
+                }
+                logger.info('ViteWP integration loaded.');
+            },
+        },
+    };
+}
+function getDevToolbarEntrypoint() {
+    const sourceEntrypoint = new URL('./dev-toolbar/vitewp-toolbar.ts', import.meta.url);
+    if (existsSync(fileURLToPath(sourceEntrypoint))) {
+        return sourceEntrypoint;
+    }
+    return new URL('./dev-toolbar/vitewp-toolbar.js', import.meta.url);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { runDev } from './commands/dev.js';
+import { runDoctor } from './commands/doctor.js';
+import { runSmoke } from './commands/smoke.js';
+import { runTypes } from './commands/types.js';
+import { runInit } from './commands/init.js';
+const command = process.argv[2] ?? 'help';
+switch (command) {
+    case 'dev':
+        await runDev();
+        break;
+    case 'doctor':
+        await runDoctor();
+        break;
+    case 'init':
+        runInit();
+        break;
+    case 'types':
+        await runTypes();
+        break;
+    case 'smoke':
+        await runSmoke();
+        break;
+    case 'help':
+    case '--help':
+    case '-h':
+        printHelp();
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exitCode = 1;
+}
+function printHelp() {
+    console.log(`vitewp\n\nUsage:\n  vitewp init      Copy starter project files into the current directory
+  vitewp dev       Start the local WordPress + Astro development runtime
+  vitewp doctor    Check the current project setup
+  vitewp types     Generate TypeScript types from WordPress metadata
+  vitewp smoke     Verify the running ViteWP dev runtime\n`);
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1 @@
+export declare function runDev(): Promise<void>;

package/dist/commands/dev.js

@@ -0,0 +1,62 @@
+import { loadViteWpConfig } from '../config.js';
+import { ensureComposerInstall } from '../runtime/composer.js';
+import { startAstroServer, stopAstroServer } from '../runtime/astro.js';
+import { startPhpServer } from '../runtime/php.js';
+import { waitForExit } from '../runtime/process.js';
+import { assertPortAvailable, resolveInternalPort } from '../runtime/ports.js';
+import { startUnifiedProxy } from '../runtime/proxy.js';
+import { phpServerUrl, writeWordPressConfig } from '../runtime/wp-config.js';
+import { runDoctorChecks } from './doctor.js';
+export async function runDev() {
+    const config = await loadViteWpConfig();
+    const verbose = isVerbose();
+    if (verbose) {
+        process.env.VITEWP_VERBOSE = '1';
+    }
+    console.log('ViteWP dev runtime');
+    console.log(`- local site: ${config.wordpress.url}`);
+    console.log(`- WordPress docroot: ${config.wordpress.docroot}`);
+    console.log(`- WordPress content: ${config.wordpress.contentDir}`);
+    console.log(`- templates: ${config.templates.directory}`);
+    console.log(`- database: ${config.database.driver}://${config.database.user}@${config.database.host}:${config.database.port}/${config.database.name}`);
+    console.log('');
+    const result = await runDoctorChecks(config);
+    if (result.errors > 0) {
+        console.log('');
+        console.log('Fix the errors above before starting the dev runtime.');
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        await ensureComposerInstall(config);
+        writeWordPressConfig(config);
+        await stopAstroServer(config);
+        config.dev.phpPort = await resolveInternalPort(config.dev.phpHost, config.dev.phpPort);
+        config.dev.astroPort = await resolveInternalPort(config.dev.astroHost, config.dev.astroPort);
+        const publicUrl = new URL(config.wordpress.url);
+        await assertPortAvailable(publicUrl.hostname, Number(publicUrl.port || 3000), 'ViteWP proxy');
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+        return;
+    }
+    process.env.VITEWP_PUBLIC_URL = config.wordpress.url;
+    process.env.VITEWP_PHP_URL = phpServerUrl(config);
+    console.log('');
+    if (verbose) {
+        console.log(`✓ WordPress/PHP internal server: ${phpServerUrl(config)}`);
+        console.log(`✓ Astro internal server: http://${config.dev.astroHost}:${config.dev.astroPort}`);
+    }
+    const php = startPhpServer(config);
+    const astro = await startAstroServer(config);
+    const proxy = await startUnifiedProxy(config);
+    console.log(`✓ ViteWP ready at ${proxy.url}`);
+    console.log('Press Ctrl+C to stop.');
+    console.log('');
+    await waitForExit([php, astro]);
+    await proxy.stop();
+}
+function isVerbose() {
+    return process.argv.includes('--verbose') || process.env.VITEWP_VERBOSE === '1';
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,6 @@
+import { type LoadedViteWpConfig } from '../config.js';
+export declare function runDoctor(): Promise<void>;
+export declare function runDoctorChecks(config: LoadedViteWpConfig): Promise<{
+    errors: number;
+    warnings: number;
+}>;

package/dist/commands/doctor.js

@@ -0,0 +1,139 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { loadViteWpConfig } from '../config.js';
+const execFileAsync = promisify(execFile);
+export async function runDoctor() {
+    const config = await loadViteWpConfig();
+    const result = await runDoctorChecks(config);
+    process.exitCode = result.errors > 0 ? 1 : 0;
+}
+export async function runDoctorChecks(config) {
+    const checks = [];
+    checks.push({
+        status: config.configFile ? 'pass' : 'warn',
+        label: 'ViteWP config',
+        detail: config.configFile ?? 'No vitewp.config.* file found; using defaults.',
+    });
+    checks.push(fileCheck(config.root, 'astro.config.mjs', 'Astro config'));
+    checks.push(fileCheck(config.root, 'composer.json', 'Composer manifest'));
+    checks.push(composerWordPressCheck(config.root, config.composer.wordpressPackage));
+    checks.push(fileCheck(config.root, 'composer.lock', 'Composer lockfile'));
+    checks.push(fileCheck(config.root, `${config.wordpress.docroot}/wp-settings.php`, 'Composer-installed WordPress core'));
+    checks.push(fileCheck(config.root, `${config.wordpress.docroot}/wp-config.php`, 'Generated wp-config.php'));
+    checks.push(fileCheck(config.root, `${config.wordpress.contentDir}/themes/vitewp/style.css`, 'ViteWP placeholder theme'));
+    checks.push(fileCheck(config.root, config.templates.directory, 'Template directory'));
+    checks.push(databaseConfigCheck(config));
+    checks.push(await commandCheck('php', ['-v'], 'PHP runtime'));
+    checks.push(await commandCheck('composer', ['--version'], 'Composer'));
+    checks.push(gitignoreCheck(config.root, config.wordpress.docroot));
+    printChecks(checks);
+    const errors = checks.filter((check) => check.status === 'fail').length;
+    const warnings = checks.filter((check) => check.status === 'warn').length;
+    console.log('');
+    console.log(`Doctor finished with ${errors} error(s) and ${warnings} warning(s).`);
+    return { errors, warnings };
+}
+function fileCheck(root, relativePath, label) {
+    const path = join(root, relativePath);
+    return existsSync(path)
+        ? { status: 'pass', label, detail: relativePath }
+        : { status: 'warn', label, detail: `${relativePath} does not exist yet.` };
+}
+async function commandCheck(command, args, label) {
+    try {
+        const { stdout, stderr } = await execFileAsync(command, args);
+        const firstLine = `${stdout}${stderr}`.split('\n').find(Boolean);
+        return { status: 'pass', label, detail: firstLine };
+    }
+    catch {
+        return { status: 'fail', label, detail: `${command} was not found on PATH.` };
+    }
+}
+function databaseConfigCheck(config) {
+    const database = config.database;
+    const missing = [
+        ['host', database.host],
+        ['name', database.name],
+        ['user', database.user],
+        ['tablePrefix', database.tablePrefix],
+    ].filter(([, value]) => !value);
+    if (missing.length > 0) {
+        return {
+            status: 'fail',
+            label: 'Database config',
+            detail: `Missing ${missing.map(([key]) => key).join(', ')}.`,
+        };
+    }
+    if (database.driver !== 'mysql' && database.driver !== 'mariadb') {
+        return {
+            status: 'fail',
+            label: 'Database config',
+            detail: `Unsupported driver: ${database.driver}.`,
+        };
+    }
+    return {
+        status: 'pass',
+        label: 'Database config',
+        detail: `${database.driver}://${database.user}@${database.host}:${database.port}/${database.name} (${database.tablePrefix})`,
+    };
+}
+function composerWordPressCheck(root, wordpressPackage) {
+    const composerPath = join(root, 'composer.json');
+    if (!existsSync(composerPath)) {
+        return {
+            status: 'warn',
+            label: 'Composer WordPress package',
+            detail: 'composer.json does not exist yet.',
+        };
+    }
+    try {
+        const composer = JSON.parse(readFileSync(composerPath, 'utf8'));
+        const version = composer.require?.[wordpressPackage];
+        if (!version) {
+            return {
+                status: 'fail',
+                label: 'Composer WordPress package',
+                detail: `${wordpressPackage} is not declared in composer.json.`,
+            };
+        }
+        const installDir = composer.extra?.['wordpress-install-dir'];
+        const installDetail = installDir ? ` -> ${installDir}` : '';
+        return {
+            status: 'pass',
+            label: 'Composer WordPress package',
+            detail: `${wordpressPackage}@${version}${installDetail}`,
+        };
+    }
+    catch (error) {
+        return {
+            status: 'fail',
+            label: 'Composer WordPress package',
+            detail: error instanceof Error ? error.message : 'Could not parse composer.json.',
+        };
+    }
+}
+function gitignoreCheck(root, docroot) {
+    const gitignorePath = join(root, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+        return { status: 'warn', label: 'Generated WordPress ignored', detail: '.gitignore is missing.' };
+    }
+    const gitignore = readFileSync(gitignorePath, 'utf8');
+    const normalizedDocroot = docroot.endsWith('/') ? docroot : `${docroot}/`;
+    return gitignore.includes(normalizedDocroot)
+        ? { status: 'pass', label: 'Generated WordPress ignored', detail: normalizedDocroot }
+        : {
+            status: 'warn',
+            label: 'Generated WordPress ignored',
+            detail: `Add ${normalizedDocroot} to .gitignore.`,
+        };
+}
+function printChecks(checks) {
+    console.log('ViteWP doctor');
+    console.log('');
+    for (const check of checks) {
+        const icon = check.status === 'pass' ? '✓' : check.status === 'warn' ? '!' : '✕';
+        console.log(`${icon} ${check.label}${check.detail ? ` — ${check.detail}` : ''}`);
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function runInit(): void;

package/dist/commands/init.js

@@ -0,0 +1,55 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function runInit() {
+    const target = resolve(process.cwd(), getTargetDirectory());
+    const force = process.argv.includes('--force');
+    const starter = resolve(dirname(fileURLToPath(import.meta.url)), '../../starter');
+    if (!existsSync(starter)) {
+        console.error('Could not find the ViteWP starter files in this package.');
+        process.exitCode = 1;
+        return;
+    }
+    mkdirSync(target, { recursive: true });
+    copyDirectory(starter, target, force);
+    updatePackageJson(target);
+    console.log(`ViteWP project files initialized in ${relative(process.cwd(), target) || '.'}.`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Copy .env.example to .env and set database credentials.');
+    console.log('  2. Run npm install if dependencies are not installed yet.');
+    console.log('  3. Run npm run dev.');
+}
+function getTargetDirectory() {
+    const positional = process.argv.slice(3).find((arg) => !arg.startsWith('-'));
+    return positional ?? '.';
+}
+function copyDirectory(from, to, force) {
+    for (const entry of readdirSync(from)) {
+        const source = join(from, entry);
+        const destination = join(to, entry);
+        const stats = statSync(source);
+        if (stats.isDirectory()) {
+            mkdirSync(destination, { recursive: true });
+            copyDirectory(source, destination, force);
+            continue;
+        }
+        if (existsSync(destination) && !force) {
+            continue;
+        }
+        cpSync(source, destination, { force: true });
+    }
+}
+function updatePackageJson(root) {
+    const file = join(root, 'package.json');
+    const packageJson = existsSync(file)
+        ? JSON.parse(readFileSync(file, 'utf8'))
+        : { private: true, type: 'module' };
+    packageJson.type ??= 'module';
+    packageJson.scripts ??= {};
+    packageJson.scripts.dev ??= 'vitewp dev';
+    packageJson.scripts.doctor ??= 'vitewp doctor';
+    packageJson.scripts.types ??= 'vitewp types';
+    packageJson.scripts.check ??= 'astro check';
+    writeFileSync(file, `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8');
+}

package/dist/commands/smoke.d.ts

@@ -0,0 +1 @@
+export declare function runSmoke(): Promise<void>;

package/dist/commands/smoke.js

@@ -0,0 +1,138 @@
+import { randomBytes } from 'node:crypto';
+import net from 'node:net';
+import { loadViteWpConfig } from '../config.js';
+export async function runSmoke() {
+    const config = await loadViteWpConfig();
+    const baseUrl = config.wordpress.url.replace(/\/$/, '');
+    const checks = [
+        {
+            label: 'Unified frontend route',
+            run: () => expectHttp(`${baseUrl}/`, [200]),
+        },
+        {
+            label: 'ViteWP dev route metadata',
+            run: () => expectBody(`${baseUrl}/`, 'window.__VITEWP_ROUTE_INFO__'),
+        },
+        {
+            label: 'WordPress admin route',
+            run: () => expectHttp(`${baseUrl}/wp-admin/`, [200, 302]),
+        },
+        {
+            label: 'Vite client through proxy',
+            run: () => expectHttp(`${baseUrl}/@vite/client`, [200], 'text/javascript'),
+        },
+        {
+            label: 'wp-content static asset',
+            run: () => expectHttp(`${baseUrl}/wp-content/themes/vitewp/style.css`, [200], 'text/css'),
+        },
+        {
+            label: 'ViteWP route bridge',
+            run: () => expectJson(`${baseUrl}/wp-json/vitewp/v1/resolve?path=/`, ['found', 'kind']),
+        },
+        {
+            label: 'ViteWP type metadata',
+            run: () => expectJson(`${baseUrl}/wp-json/vitewp/v1/types`, ['postTypes', 'taxonomies']),
+        },
+        {
+            label: 'Vite HMR websocket',
+            run: () => expectWebSocket(baseUrl),
+        },
+    ];
+    console.log('ViteWP smoke test');
+    console.log('');
+    let failures = 0;
+    for (const check of checks) {
+        try {
+            const detail = await check.run();
+            console.log(`✓ ${check.label}${detail ? ` — ${detail}` : ''}`);
+        }
+        catch (error) {
+            failures += 1;
+            console.log(`✕ ${check.label} — ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    console.log('');
+    console.log(`Smoke test finished with ${failures} failure(s).`);
+    process.exitCode = failures > 0 ? 1 : 0;
+}
+async function expectHttp(url, statuses, expectedContentType) {
+    const response = await fetchWithTimeout(url, { method: 'GET' });
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!statuses.includes(response.status)) {
+        throw new Error(`Expected ${statuses.join('/')} from ${url}, got ${response.status}.`);
+    }
+    if (expectedContentType && !contentType.includes(expectedContentType)) {
+        throw new Error(`Expected content-type ${expectedContentType}, got ${contentType || 'none'}.`);
+    }
+    await response.body?.cancel();
+    return `${response.status}${contentType ? ` ${contentType}` : ''}`;
+}
+async function expectJson(url, keys) {
+    const response = await fetchWithTimeout(url);
+    if (!response.ok) {
+        throw new Error(`Expected 2xx from ${url}, got ${response.status}.`);
+    }
+    const json = await response.json();
+    const missing = keys.filter((key) => !(key in json));
+    if (missing.length > 0) {
+        throw new Error(`Missing JSON key(s): ${missing.join(', ')}.`);
+    }
+    return `${response.status}`;
+}
+async function expectBody(url, needle) {
+    const response = await fetchWithTimeout(url);
+    const body = await response.text();
+    if (!response.ok) {
+        throw new Error(`Expected 2xx from ${url}, got ${response.status}.`);
+    }
+    if (!body.includes(needle)) {
+        throw new Error(`Expected response body to include ${needle}.`);
+    }
+    return `${response.status}`;
+}
+async function fetchWithTimeout(url, init = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal, redirect: 'manual' });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function expectWebSocket(baseUrl) {
+    const url = new URL(baseUrl);
+    const host = url.hostname;
+    const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
+    const key = randomBytes(16).toString('base64');
+    return new Promise((resolve, reject) => {
+        const socket = net.connect(port, host, () => {
+            socket.write([
+                'GET / HTTP/1.1',
+                `Host: ${url.host}`,
+                'Connection: Upgrade',
+                'Upgrade: websocket',
+                `Sec-WebSocket-Key: ${key}`,
+                'Sec-WebSocket-Version: 13',
+                'Sec-WebSocket-Protocol: vite-hmr',
+                '',
+                '',
+            ].join('\r\n'));
+        });
+        socket.setTimeout(5000);
+        socket.once('data', (data) => {
+            const firstLine = data.toString().split('\r\n')[0] ?? '';
+            socket.destroy();
+            if (!firstLine.includes('101')) {
+                reject(new Error(`Expected 101 Switching Protocols, got ${firstLine || 'no response'}.`));
+                return;
+            }
+            resolve('101 Switching Protocols');
+        });
+        socket.once('timeout', () => {
+            socket.destroy();
+            reject(new Error('Timed out waiting for websocket upgrade.'));
+        });
+        socket.once('error', reject);
+    });
+}

package/dist/commands/types.d.ts

@@ -0,0 +1 @@
+export declare function runTypes(): Promise<void>;