ForgeWP is a development and export tool. You author a theme in React, preview it with Vite, and export files that run inside WordPress. This page helps you choose an editing model and prepare your theme for delivery.

Architecture and alternatives

Is the exported theme a block theme?

ForgeWP currently exports a PHP-backed hybrid theme: PHP templates, rendered HTML fragments, assets, registered Gutenberg blocks, and theme.json design settings. A hybrid theme combines PHP templates with block-editor features.

Manage the generated PHP layouts in source, and use WordPress fields and Gutenberg blocks for client editing. Full Site Editing uses a separate block-template model. See Classic, Hybrid, and Block Themes.

How does ForgeWP compare with other ways to build WordPress sites?

Choose the workflow that fits your team's authoring preferences and your client's editing needs.

Table · 4 columns


Option	Main authoring workflow	Typical editing experience	Plan for
ForgeWP	React/Tailwind source, followed by compilation and export	Declared fields, Gutenberg blocks, and content slots	Documented compiler patterns and WordPress verification
Native block theme	Block templates, patterns, styles, and optional custom blocks	Site Editor and post/page block editor, subject to permissions and locks	Bespoke blocks and editor controls may require additional development
Page builder such as Elementor	Builder widgets, containers, and templates	Visual controls for elements created in that builder	The builder and extensions used by the layout
Custom PHP theme with fields	PHP templates and content-field definitions	The fields and layout choices the developer exposes	Direct integration code and explicit layout controls
Headless WordPress	A separate frontend that reads WordPress data	WordPress manages content; frontend previews need integration	Hosting, previews, and plugin behavior depend on the frontend architecture

ForgeWP brings React authoring, WordPress bindings, and theme export into one workflow. Choose it when that combination fits your development process and delivery needs.

How do I bring an existing React application into ForgeWP?

Reuse components for rendered markup, and connect live content through ForgeWP's WordPress hooks and primitives. Supported interactive components can become browser-side islands: individual areas where JavaScript enables interaction.

Map framework-specific features such as Next.js server components, API routes, and middleware to the appropriate WordPress integrations. Keep browser-dependent behavior in interactive components. Migrate and verify one route or component at a time. Start with Translation Rules.

What clients can edit

How do I make text and images editable in WordPress?

Connect values to page fields or block attributes, then expose the controls editors will use. Keep source-owned text directly in JSX.

Table · 3 columns


Requirement	ForgeWP feature	What remains controlled by the developer
Edit a page heading or image using named fields	`defineEditable()` and `useWpMeta()`	The surrounding template layout
Insert WordPress content inside a template	`<BlockArea />`	The JSX outside the slot
Insert and edit reusable sections	Registered Gutenberg blocks	Each block's internal layout unless additional controls are exposed
Compose a page from blocks	Default, when it renders the Page body, or ForgeWP Builder	The template wrapper and block implementations
Nest blocks inside a section	`defineBlock()` with `innerBlocks`	Shell styling, allowed children, and configured restrictions

WpEditable connects a selected block value to an editing control in the block canvas. Pair it with saved attributes or an editable schema to define both storage and inline editing. See Page Content Slots and Editable Fields.

Can editors move every element? Are elements locked?

Editors can reorder blocks where their permissions and block/template settings allow it. Use a single hero block to manage its heading, image, and button together, or nested blocks when editors should move those parts independently.

A parent shell can expose child blocks through innerBlocks. Its allowedBlocks limits which children can be inserted, and templateLock controls permitted structural changes. Setting templateLock: false removes that shell's template lock; other WordPress restrictions can still apply.

Decide whether clients should edit values, reorder whole sections, or compose nested blocks. Implement and test that specific editing experience.

Can I edit generated layouts with Elementor?

ForgeWP's native editing workflow uses Gutenberg blocks and WordPress fields. For Elementor-managed pages, create the content using Elementor's widgets and templates and verify the integration with your theme. The two editors use separate content structures.

Do page fields require ACF?

The compiler generates native post-meta registration and can generate field groups for ACF when ACF is available. The editing interface depends on the schema and active integrations. Choose the field interface that matches your schema, and check the ACF edition required for the field types you use. See ACF, Editable Schemas, and Exported Blocks.

Development and hosting

Do I need WordPress running while I design the theme?

The standard Vite preview uses data from cms/, so it does not require a local PHP server or database. Package installation, remote images, fonts, and optional services may need a network connection.

Use mock data to develop the design locally, then complete integration checks in WordPress for PHP templates, permissions, plugin blocks, forms, and live queries.

Does production need Node.js?

No Node.js server is required to serve the exported theme. Node.js is used on the development machine or build runner. The production site still needs WordPress, PHP, a database, and the plugins required by the features you use.

Use Requirements as the starting point and check the installation's actual dependencies. theme.json version 3 requires WordPress 6.6 or newer. Check feature requirements alongside the generated theme header when choosing your target WordPress version.

How do I integrate WordPress plugins and choose hosting?

The generated theme uses WordPress templates and integration points such as wp_head() and wp_footer(). Use these integration points together with the content slots, blocks, and APIs required by your plugins.

For plugin blocks, choose a template that renders saved post content. Verify the plugins, versions, and workflows used by the site on your chosen host. If you plan to submit the theme to the WordPress Theme Directory, include its review requirements in your release checklist.

Performance and updates

How do I tune frontend performance?

Keep static components as rendered markup, and use islands for interactive behavior. Include the hydrator, shared dependencies, plugin scripts, and analytics when measuring the full page's JavaScript payload.

Measure the exported site using the analyzer and browser Network panel. Hosting, queries, caching, media, fonts, plugins, and third-party services affect performance. Use those measurements to prioritize improvements for your actual pages and hosting environment.

How do I use the font and image pipelines?

The export pipeline can create local font files and WebP variants for eligible assets. Use export messages to inspect processed theme assets, and use WordPress's media workflow for dynamically uploaded attachments. The generated font loader can fall back to a remote stylesheet if local font files are unavailable.

Include local font files and fallback requests in your site's font-loading and privacy review. See Design Tokens and Fonts and Sharp Image Pipeline.

Can I use caching?

Server-rendered pages can be cached, but the policy must match the content. Public pages and personalized responses have different requirements. Test forms, nonces, dynamic endpoints, and cache invalidation on the deployed site. Configure cache exclusions for personalized or request-specific responses.

Will a theme update preserve client edits?

It can, provided the new version remains compatible with saved data. Keep block names, attribute names, meta keys, and value types stable, or write and test a migration when changing them.

Also review seeding. Generated seed routines can write to the database on activation or admin initialization when enabled. upsert can overwrite matching posts and metadata; forced seeding bypasses protections. Review those settings before deploying the new files.

Back up the site, test the release against existing content on staging, and keep a rollback package. These are normal WordPress maintenance practices. Follow Install and Verify.

Working with AI agents

How does ForgeWP support AI-assisted development?

ForgeWP gives agents a shared set of conventions, WordPress primitives, and export tools. An agent can author React and use established WordPress bindings rather than generating every integration independently.

Give the agent the documented patterns, the intended editing model, and clear acceptance checks. Review the exported result for editing quality, maintainability, and performance.

What should an agent verify before handing over a theme?

Identify which values come from source, WordPress fields, block attributes, or post content.
Read installed package APIs and project scripts before adding commands or configuration.
Typecheck and export with validation; explain unresolved warnings.
Install on WordPress and test both visitor and editor behavior.
Verify updates against saved content, including seed settings and renamed fields.
Report what was tested and what remains unverified. Include both local preview and WordPress integration checks in the handoff.

Keep the React source, configuration, and lockfile as the maintained project. Apply lasting changes in source and regenerate the theme so future exports include them.

Frequently Asked Questions