Feat: Add support for dynamic import of templates

[moonmeister]

Tasks

• I have signed a Contributor License Agreement (CLA) with WP Engine.
• If a code change, I have written testing instructions that the whole team & outside contributors can understand.
• I have written and included a comprehensive changeset to properly document the changes I've made.

Description

Adds support for dynamically imported templates. This resolves bundling issues with Faust. No longer are all templates and their components in the initial bundle. Now they can be broken out and initial page load size reduced. See example site bundling improvements:

Static Imports:

Dynamic imports:

27Kb improvement for shared bundles + ~9Kb per route! 🥳 🏃🏻 💨

Testing

I've tested manually but haven't looked at writing any tests. More testing with named exports especially should probably be done to confirm things are working.

Documentation Changes

Updated the Basic Setup Doc. The tutorial should possibly be updated too.

[changeset-bot]

🦋 Changeset detected

Latest commit: 14a144b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@faustwp/core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[ahuseyn]

Thanks @moonmeister for the PR. I've pulled it and tested the example, but it returned some type errors. Could you take a look when you get a chance?

[cjs] src/components/WordPressTemplate.tsx:69:27 - error TS2339: Property 'queries' does not exist on type 'WordPressTemplate | DynamicComponent<WordPressTemplate>'.
[cjs]   Property 'queries' does not exist on type 'DynamicComponent<WordPressTemplate>'.
[cjs] 
[cjs] 69  if (template && template.queries && template.query) {
[cjs]                              ~~~~~~~
[cjs] 
[cjs] src/components/WordPressTemplate.tsx:69:47 - error TS2339: Property 'query' does not exist on type 'WordPressTemplate | DynamicComponent<WordPressTemplate>'.
[cjs]   Property 'query' does not exist on type 'DynamicComponent<WordPressTemplate>'.
[cjs] 
[cjs] 69  if (template && template.queries && template.query) {
[cjs]                                                  ~~~~~
[cjs] 
[cjs] src/components/WordPressTemplate.tsx:86:17 - error TS2339: Property 'query' does not exist on type 'WordPressTemplate | DynamicComponent<WordPressTemplate>'.
[cjs]   Property 'query' does not exist on type 'DynamicComponent<WordPressTemplate>'.
...

[github-actions]

📦 Next.js Bundle Analysis for @faustwp/getting-started-example

This analysis was generated by the Next.js Bundle Analysis action. 🤖

🎉 Global Bundle Size Decreased

Page	Size (compressed)
global	233.18 KB (🟢 -35.15 KB)

Details

The global bundle is the javascript bundle that loads alongside every page. It is in its own category because its impact is much higher - an increase to its size means that every page on your website loads slower, and a decrease means every page loads faster.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

If you want further insight into what is behind the changes, give @next/bundle-analyzer a try!

One Page Changed Size

The following page changed size from the code in this PR compared to its base branch:

Page	Size (compressed)	First Load	% of Budget (350 KB)
/example	38.26 KB	271.44 KB	77.55% (🟡 +10.71%)

Details

Only the gzipped size is provided here based on an expert tip.

First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If next/link is used, subsequent page loads would only need to download that page's bundle (the number in the "Size" column), since the global bundle has already been downloaded.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

The "Budget %" column shows what percentage of your performance budget the First Load total takes up. For example, if your budget was 100kb, and a given page's first load size was 10kb, it would be 10% of your budget. You can also see how much this has increased or decreased compared to the base branch of your PR. If this percentage has increased by 20% or more, there will be a red status indicator applied, indicating that special attention should be given to this. If you see "+/- <0.01%" it means that there was a change in bundle size, but it is a trivial enough amount that it can be ignored.

[moonmeister]

@ahuseyn I believe I've resolved all TS errors.

[ahuseyn]

Looks good to me

[Copilot]

Pull request overview

This PR adds support for dynamically importing templates using Next.js's next/dynamic to reduce initial bundle sizes. The feature is backwards compatible with static imports, allowing templates to be loaded on-demand per route rather than bundled together.

Changes:

• Core functionality to detect and load dynamic components (checking for render.preload structure)
• Server-side dynamic component loading in getWordPressProps
• Client-side dynamic component loading in WordPressTemplate component with useEffect hooks
• Updated examples and documentation to demonstrate dynamic import usage

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
packages/faustwp-core/src/getWordPressProps.tsx	Adds server-side dynamic component detection and loading logic
packages/faustwp-core/src/getTemplate.ts	Defines DynamicComponent type and utility functions (isDynamicComponent, loadDynamicComponent)
packages/faustwp-core/src/components/WordPressTemplate.tsx	Implements client-side dynamic component loading in useEffect hooks
examples/next/faustwp-getting-started/wp-templates/index.js	Demonstrates dynamic import pattern with next/dynamic
examples/next/faustwp-getting-started/components/FeaturedImage/FeaturedImage.js	Unrelated changes: switches to next/legacy/image and includes debug console.log
docs/how-to/basic-setup/index.md	Updates documentation with dynamic import example (contains critical bug)
.changeset/funny-ravens-run.md	Documents the feature change with migration guide

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.