App Router Support

[nicholasio]

Summary

This is the main issue for implementing App Router Support and it will describe the current plan.

What needs to happen

Preview Give feedback

1. [App Router] Data Fetching in Server Components #788
   App Router Data Fetching +2
2. [App Router] Make BlocksRenderer compatible with Server Components #789
   App Router +1
3. [App Router] Update the next.js handlers (revalidateHandlers and previewHandler) to support Route Handlers. #791
   App Router +1
4. [App Router] Config Loading #792
   App Router +1
5. [App Router] Multisite #793
   App Router Multisite +2
6. [App Router] SEO Handling: Provide utilities for generating SEO metadata #790
   App Router +1
7. Polylang/Locale Support #808
   +0
8. Fix cache settings #822
   +0
9. Look into why Next.js is defaulting to dynamic mode #803
   App Router +1
10. Link handling/replacing #839
    +0
11. ImageBlock #841
    +0
12. Allow overriding fetch strategy #840
    +0
13. Update starting projects

Goals

• Support both Pages Router and App Router so being able to reuse code between the two is important.
• Default to "server-first" approach but still allow the client-side useSwr-powered hooks to be useable inside Client Components

Implementation Brief

The sections below describes the technical plan at a high-level.

Data Fetching

• Create a version of useFetch that isn't a hook but an async function: fetchStrategy()
• Create a fetchPosts, fetchPosts, fetchSearch, fetchSearchNative that uses the fetchStrategy function that executes the strategy.
• The fetch* functions should accept the params from a pre-defined catch-all argument (e.g [...path].ts) so that it automatically extract params from the URL. However, this will need to be passed explicitly instead of automagically as in the pages router.
• Since all of this is just a regular function, it can stay in the @headstartwp/core export.
• Additionally, these methods could easily be reused with other frameworks such as Astro if we ever attempt to support other frameworks that aren't Next.js

By keeping the current Fetch Strategies as is we can reuse all of the logic between Pages Router, App Router and Client-side data-fetching.

We can look for opportunities to streamline fetch strategies. However, I don't foresee a need for utilizing the "fetch strategy way" of doing things for custom/third-party endpoints. In the Pages Router the fetch strategy was useful for allowing "isomorphic data-fetching", with the app router most of data fetching will be server side so there's no need for that. Therefore we should treat "fetch strategies" as an internal concept.

SEO Handling

With the App Router we mostly just need a utility function to extract the yoastSeo metadata out of the API.

BlocksRenderer

This is essentially completed in the PoC. The main thing to note is that it will no longer automatically load the config from the App's Context Provider since that is not avaliable in Server Components, instead, the config should be passed to it if necessary.

The example below show what will be possible using the BlocksRender and Server Components. Any custom block can fetch additional data right in the component, for instance, it can fetch a list of posts from the blocks attribute ids.

With Suspense & Streaming we can make it so that it doesn't block rendering the rest of the page and with Partial Pre-rendering we can still ship a static shell of the page while the rest of the blocks finish loading.

const MyCustomBlockSkeleton = ({domNode}) => {
 return ( 
      <Suspense fallback={<BlockSkeleton />}>
          <MyCustomBlock domNode={domNode} />
       </Suspense>
  );
}
const MyCustomBlock = async ({domNode}) => {
    const attributes = getBlockAttributes(domNode);
    
    // no need to inject the whole list of post data into the markup
    const posts = await fetchPosts({ include: attributes.ids });

    return /* render posts*/;
}

const RenderBlocks = () => {
   return (
      <BlocksRenderer html={post.content.rendered}>
	      <MyCustomBlockSkeleton test={(node) => isBlockByName(node) } />
      </BlocksRenderer>
   );
};

We currently have a few hooks that gets the attribute we should probably convert those into regular functions since they don't need to be hooks anyway.

Additionally we could look into having BlocksRenderer automatically pass attributes as props to avoid needing block components to read the attributes themselves from domNode.

const MyCustomBlock = async ({attributes}) => {
    const posts = await fetchPosts({ include: attributes.ids });

    return /* render posts*/;
}

Config Loading

Need to look into the better way to load the config with the App Router. We could keep injecitng it at build time or we could simply provide an async function that would support loading the config in server components.

const MyCustomBlock = async ({attributes}) => {
    const config = await loadHeadstartWPConfig();
    const posts = await fetchPosts({ include: attributes.ids });

    return /* render posts*/;
}

This is important because of how we support multisite today.

Multisite

Multisite will work mostly the same way.

Next.js Handlers

We'd want to move the core logic of revalidateHandler and previewHandle to a separate function to make it able to work with the Next.js specific Request/Response objects of the Pages rotuer and the Web-compatible Request/Response objects of the App Router.

The previewHandle will need some rework though as the way draft mode works is a bit different and doesn't support previewData object which we currently need.

Internationalization and Polylang Support

We'll need to add this to middleware.

https://nextjs.org/docs/app/building-your-application/routing/internationalization

[nicholasio]

App router is now stable https://nextjs.org/blog/next-13-4

[nicholasio]

Update: we are feature complete for App Router.

Next steps:

• Documentation
• Finish porting the pages router scaffold to the app router variants
• e2e testing

[ghostintranslation]

Hey there, seeing no update here for a while, is this going anywhere? I'm interested in being able to use the app router with headstartwp.

[nicholasio]

Hey there, seeing no update here for a while, is this going anywhere? I'm interested in being able to use the app router with headstartwp.

The work itself to make HeadstartWP compatible with App Router is complete. There has been quite a few releases to the next release channel as we iterate on that front. The only reason it hasn't been fully released is documentation haven't been updated yet.

You can try it out today using the latest next npm tag. There's a project that can serve as a starting point https://github.com/10up/headstartwp/tree/develop/projects/wp-nextjs-app