ForgeWP

Static HTML & Custom Adapters

Export plain HTML/CSS sites into WordPress themes with the Static HTML adapter, or implement a custom FrameworkAdapter for another frontend framework.

In addition to Vite React ("react") and Next.js App Router ("nextjs"), ForgeWP ships with a lightweight Static HTML adapter ("html") and an open Framework Adapter interface so you can plug in custom build pipelines.


1. Static HTML Adapter (frameworkAdapter: "html")

The Static HTML adapter is designed for developers who have plain HTML, CSS, and vanilla JavaScript files — without React or Next.js — and still want ForgeWP to package them into a valid WordPress theme with style.css, functions.php, theme.json, asset optimization, and a .zip bundle.

Configure wp.config.ts (or wp.config.js)

wp.config.ts
1import { defineConfig } from "@forgewp/compiler/define-config"
2
3export default defineConfig({
4  themeName: "My Static Theme",
5  themeSlug: "my-static-theme",
6  frameworkAdapter: "html",
7})

When to Use It

  • Converting an existing static marketing site or landing page into an installable WordPress theme.
  • Prototyping WordPress theme structure with zero frontend framework overhead.
  • Teams that want Tailwind CSS + vanilla HTML without adopting React or Next.js.

2. Writing a Custom Framework Adapter

Under the hood, every built-in adapter (react, nextjs, html) implements the same FrameworkAdapter contract inside @forgewp/compiler.

If you want to integrate another frontend framework (for example, Astro, Vue, or a custom internal static site generator), you can pass an adapter object directly to frameworkAdapter in wp.config.ts / wp.config.js:

wp.config.ts
1import { defineConfig } from "@forgewp/compiler/define-config"
2
3export default defineConfig({
4  themeName: "Custom Adapter Theme",
5  themeSlug: "custom-adapter-theme",
6  frameworkAdapter: {
7    name: "my-custom-adapter",
8    async build(ctx) {
9      // 1. Run your framework's production build
10      // 2. Return the rendered HTML routes and asset manifest for ForgeWP to package
11    },
12    async renderRoute(ctx, route) {
13      // Return static HTML for each discovered route
14      return { html: "<main>Hello from custom adapter</main>" }
15    },
16  },
17})

What ForgeWP Still Handles for You

Even with a custom adapter, @forgewp/compiler automatically takes care of:

  • Generating style.css theme headers and theme.json design tokens
  • Writing WordPress functions.php asset enqueueing
  • Running strict theme validation and packaging .forgewp/<slug>.zip
  • Optional modules configured in wp.config.{ts,js} (Native Forms, SEO handoff, i18n extraction)
Need a starting point?

Inspect the built-in adapters in @forgewp/compiler (src/adapters/react-adapter.js, src/adapters/nextjs-adapter.js, and src/adapters/html-adapter.js) to see the full lifecycle hooks (validateProject, build, renderRoute, onMakePage, onMakeBlock, onMakeIsland, onMakeForm, onMakeLoop, onMakeShell).