Skip to main content

Template Registry

Role​

The template registry maps WordPress route template names to lazy React components.

It gives the runtime a single place to resolve:

  • which React template should render a route
  • how that template should be lazy-loaded
  • how a project can override or add templates safely

Main Files​

  • src/themes/reactwp/js/inc/TemplateRegistry.js
  • src/themes/reactwp/js/inc/config/configureTemplateRegistry.js
  • src/themes/reactwp/js/inc/initializeTemplateRegistry.js

Defaults​

ReactWP registers these templates automatically:

  • Default
  • NotFound

Projects can then override those entries or add new ones.

Registered templates are rendered by the frontend runtime with the standard template props:

  • route
  • site
  • theme
  • system
  • navigation

Each registered entry is normalized into an object that contains:

  • Component
  • preload()

That is why the loader can preload a template chunk before the route is revealed.

Customization​

Use config/configureTemplateRegistry.js for project-level registration.

Example:

import { registerTemplate } from './TemplateRegistry';

export const configureTemplateRegistry = () => {
    registerTemplate('SingleService', () => import('../templates/SingleService'));
    registerTemplate('Archive', () => import('../templates/Archive'));
};

The import path is relative to the config file, not to TemplateRegistry.js.

You can also override an existing template name:

import { registerTemplate } from './TemplateRegistry';

export const configureTemplateRegistry = () => {
    registerTemplate('Default', () => import('../templates/MyCustomDefault'));
};

The registry resets its safe defaults before project registration runs, so template customization stays predictable.

Main Helpers​

The registry exposes a few important helpers:

  • registerTemplate(name, loader)
  • registerTemplates(entries)
  • resetTemplateRegistry()
  • resolveTemplateEntry(templateName)

In most projects, configureTemplateRegistry.js is the only file you should need to touch.