ViteWP

ViteWP is an Astro-first WordPress development framework.

One entrypoint for everything you need, no fuzz and no magic.

Requirements

• Node.js 20+
• PHP 8.2+
• Composer
• a MySQL or MariaDB server

Get started

mkdir my-site
cd my-site
npm init -y
npx vite-wp init
cp .env.example .env

vite-wp init creates the starter files, adds the needed package dependencies, and runs install.

Edit .env with your database credentials, run npm run dev, wait for the initial configuration and then open:

http://localhost:3000

If the database is empty, go to /wp-admin/ and complete the WordPress installer.

Commands

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
npx vite-wp composer install  # Run Composer in the project
npx vite-wp wp plugin list    # Run WP-CLI when installed

For internal runtime diagnostics:

npm run dev -- --verbose

Folder structure

my-site/
  astro.config.mjs
  vitewp.config.ts
  composer.json
  .env

  .vitewp/
    types.d.ts             # generated WordPress types

  src/
    live.config.ts
    templates/             # optional template overrides

  wordpress/
    public/              # Composer-installed WordPress core
    content/
      mu-plugins/        # ViteWP bridge is generated here
      themes/            # ViteWP placeholder theme is generated here
      plugins/
      uploads/

Templates

ViteWP ships default templates from the package. Create files in src/templates only when you want to override them.

Examples:

src/templates/pages/front-page.astro
src/templates/layouts/Base.astro
src/templates/pages/page-about.astro
src/templates/posts/single.astro
src/templates/posts/archive.astro
src/templates/taxonomies/category.astro
src/templates/search.astro
src/templates/404.astro

Template props are typed by importing the matching generated type as Astro's Props type:

---
import type { WpPageTemplateProps as Props } from 'wp-types';

const { title, content, item, route, Layout } = Astro.props;
---

<Layout {...Astro.props}>
  <h1>{title}</h1>
  <div set:html={content} />
</Layout>

Available generated types include WpPageTemplateProps, WpSingleTemplateProps, WpArchiveTemplateProps, WpSearchTemplateProps, and WpTaxonomyTemplateProps. Custom post types and taxonomies can be narrowed with a generic, such as WpSingleTemplateProps<'product'>.

npm run types writes these project-specific types to .vitewp/types.d.ts. ViteWP exposes that generated file through the wp-types alias.

WordPress data

ViteWP uses Astro Live Collections for WordPress data:

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.

Menus

Register WordPress menu positions in vitewp.config.ts:

export default defineConfig({
  wordpress: {
    menus: {
      primary: 'Primary menu',
      footer: 'Footer menu',
    },
  },
});

Then assign menus to those locations in WordPress admin and fetch them by location:

import { getMenuByLocation } from 'vite-wp/wordpress/menus';

const menu = await getMenuByLocation('primary');

WordPress hooks in Astro

Astro templates can ask the internal WordPress runtime to render real WordPress actions and filters during SSR:

---
import { createHooks } from 'vite-wp/wordpress/hooks';

const hooks = createHooks(Astro.props);
const head = await hooks.action('wp_head');
const content = await hooks.filter('the_content', Astro.props.content);
---

<Fragment set:html={head.rendered} />
<article set:html={content.value} />

Blocks and plugin assets

ViteWP discovers block metadata from src/blocks/**/block.json and bundles WordPress-side JS/TS and optional CSS.

src/blocks/hero/block.json
src/blocks/hero/edit.tsx
src/blocks/hero/style.css # optional