Difficulty: 🟠 - Not hard once I got my head around it, but there were some false starts.

The existing file structure looked like this:

app/ <--  nb. this is Remix's default 'src' directory, it has nothing to do with Next's app router. 
   routes/ 
      posts/ 
         a_blog_post.mdx
         another_post.mdx
      test/ 
         test_post.mdx
      drafts/ 
         draft_post.mdx
          

(Test posts are ones I run cypress tests against, and draft posts are where I put my posts while I'm working on them, and then I move them to posts when I 'publish' them)

Now I could (and in fact I did go down this path until I realised it wouldn't work for me) go down the path of doing Next's file based MDX routing and have a structure like this:

src/ 
   app/ 
      posts/
        a_blog_post/ 
            page.mdx
        another_post/ 
            page.mdx
      test/
        test_post/ 
            page.mdx
      drafts/
        draft_post/ 
            page.mdx

but:

File based MDX routing doesn't work for me

This all comes down to the frontmatter metadata I have included in my MDX files.

I make use of Frontmatter to provide metadata in this posts like the title and description, but also to create the blog series sections, create the list of blog posts, etc.

The difficulty is, each blog post needs to be wrapped in what I'm calling a BlogPostFrame - this contains the standard layout, the 'edit with github', the comments section, as well as that series box at the top, if the post is part of the series.

That sounds like a NextJS layout component right?

Maybe we do something like this?

src/ 
   app/ 
      posts/
        layout.tsx <-- Put the BlogPostFrame here 
        a_blog_post/ 
            page.mdx
        another_post/ 
            page.mdx

The problem is - this layout.tsx has no way of knowing what page we're on, or what the metadata is supposed to be.

My Approach: Compile the MDX myself + Use dynamic routes

The folder structure I use looks like this:

src/ 
   app/ 
      posts/
        [slug]/
           page.mdx
      test/
        [slug]/
           page.mdx
      drafts/
        [slug]/
           page.mdx
   routes/ <-- This is the existing Remix routes folder, but there is no file based routing occurring here any more, these files will be compiled at build time
      posts/ 
         a_blog_post.mdx
         another_post.mdx
      test/ 
         test_post.mdx
      drafts/ 
         draft_post.mdx

I then have build-time scripts that run to compile the mdx files into a structure that looks like this:

src/
   app/
       generated/
           mdx/ 
               posts/
                  a_blog_post.mjs   <-- MDX Compiled into plain React JavaScript
                  another_post.mjs
               test/
                  test_post.mjs
               drafts/
                  draft_post.mjs
           frontmatter/
               posts/
                  a_blog_post.json <--  Frontmatter extracted to JSON format
                  another_post.json
               test/
                  test_post.json
               drafts/
                  draft_post.json

The generation of the frontmatter json files is something I did in my Remix solution, you can read about this here.

The plain rendering of my page then just uses dynamic import to retrieve the javascript it needs and renders that:

13
14export default async function PageLayout(props: PropsWithChildren<{
15    params: {
16        slug: string
17    }
18}>) {
19
20    const data = await import(`../../../generated/mdx/posts/${props.params.slug}`)
21    return <BlogPostFrame pathname={`/posts/${props.params.slug}`}>
22        {data.default()}
23    </BlogPostFrame>
24
25}

The metadata rendering is done in a similar fashion, I export a NextJS generateMetatdata function. This function is what causes our meta tags etc to put in the HTML head. The generateMetadata function asynchronously fetches the metadata based on the slug.

6export async function generateMetadata({ params }: {
7    params: {
8        slug: string
9    }
10}) {
11    return getMetadata(`/posts/${params.slug}`);
12}

Difficulty: 🟢 - Easy.

NextJS by default uses @/ aliases, whereas my Remix config had ~/ as an alias, so use find replace to update these.

Difficulty: 🟢 - Easy.

I copy paste over my app/components folder, which has various miscellaneous components, like the info boxes.

The main things to be done where:

1. Links - Change Remix links to NextJS links
2. Images - Remix image imports resolve as a string, whereas NextJS image imports resolve as a {src: string, height: number, width: number} and so my use of images are changed to: <img src ={image.src}/>.

Difficulty: 🟢 - Easy.

Because I'm using NextJS's app router any of my components that have a useEffect etc in them, need to be prefixed with "use client".

Difficulty: 🟢 - Easy with a twist.

I maintain a package react-github-permalink to display the codeblocks here. Pages with the codeblocks error with:

Error: Super expression must either be null or a function

which appears to relate to client components running in a RSC.

To fix, I updated react-github-permalink to add a "use client" directive everywhere.

The plan is to eventually have react-github-permalink behave as a RSC but for now client component will do.

One little gnarl I ran into is this error:

"Unsupported Server Component type: undefined"

According to this Stack Overflow answer not only do we need to add the "use client" directive to the components, but if doing an export * from we also need to add the directive to that.

1"use client"
2export * from "./GithubPermalink/GithubPermalink"; 
3export * from "./GithubIssueLink/GithubIssueLink";
4export * from "./GithubPermalinkContext";

Difficulty: 🟢 - Easy.

At this point I'm just checking that the pages are rendering without error.

I copy my CSS file (I'm writing just vanilla CSS) and that all works fine.

Difficulty: 🟢 - Easy.

Here I take the logic from my Remix root.tsx and put it in src/app/layout.tsx

The Remix style LinksFunction objects

55export const links: LinksFunction = () => [
56  ...(cssBundleHref ? [{ rel: "stylesheet", href: cssBundleHref }] : []),
57
58  { rel: "stylesheet", href: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css", media: "(prefers-color-scheme: dark)" },
59  { rel: "stylesheet", href: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css", media:"(prefers-color-scheme: light)" },
60
61  {
62    rel: "stylesheet", href: ourStyles,
63  },
64  { rel: "stylesheet", href: githubPermalinkStyle },
65  {
66    rel: "stylesheet",
67    href: 'https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap'
68  },
69  {
70    rel: "stylesheet",
71    href: "https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200"
72  }
73];

are converted to plain HTML rendering:

25        <link rel="preconnect" href="https://www.googletagmanager.com" />
26        <link rel="preconnect" href="https://www.google-analytics.com" />
27        <link rel="preconnect" href="https://fonts.googleapis.com" />
28
29        <meta charSet="utf-8" />
30        <meta name="viewport" content="width=device-width,initial-scale=1" />
31        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css" media="(prefers-color-scheme: dark)" />
32        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css" media="(prefers-color-scheme: light)" />
33        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,300;1,400;1,500;1,600;1,700;1,800&display=swap" />
34        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" />
35

Difficulty: 🟢 - Easy.

In Remix these files can be handled with a [sitemap.xml].tsx file - which is pretty convenient.

NextJS is a bit simpler - as part of the build process - I generate the files and put them in my public folder directly.

This is a fairly manual process, I need to remove all the Remix dependencies and add the NextJS dependencies.

I also add a convenience generate:all script which run all of my build steps except the main application build.

This is basically updates to everything in my src folder and utils folder (which is a badly named folder, it contains all of the build time scripts).

Removes remix.config.js, entry.client.tsx, entry.server.tsx, root.tsx etc.

Replaces the eslint config with the NextJS provided one.

Replaces the tsconfig with the NextJS provided one.

At time of writing I'm noticing that I neglected to copy across next.config.mjs and it appears to work fine 🤷‍♂️

The reason I did this was that I didn't want to keep babel around just so I can run my jest tests.

I feel like I had a better reason than this, but if I did, I didn't write it down in my notes.

Updating the tests themselves was pretty simple - it's just a matter of replacing references to jest with vitest, and some minor changes to how vitest types it's fn function.

Difficulty: 🟢 Easy.

One expected error is my tests that look like:

99    it ('custom social image works', () => {
100      cy.visit('/test/images'); 
101         
102      cy.get('meta[name="twitter:image"][content="https://blacksheepcode.com/build/_assets/bsc_dark-HMODRY4K.webp"]').should("exist");
103      cy.get('meta[property="og:image"][content="https://blacksheepcode.com/build/_assets/bsc_dark-HMODRY4K.webp"]').should("exist");
104   
105    }); 

That file path can obviously be expected to differ in the way the Remix and Next render it - so I go through and change those. Straight forward.

Difficulty: 🔴 - Difficult.

54    it("series - has the right content", () => {
55      cy.visit('/test/series1'); 
56
57      cy.findByText("I am series - post 1 content").should("exist"); 
58      cy.findByText('I am the series description').should("exist")
59
60
61      cy.findByRole("link", {name: "Series - Post 1"}).should("exist");
62      cy.findByRole("link", {name: "Series - Post 2"}).should("exist");
63
64      cy.findByRole("link", {name: "Next: Series - Post 2"}).should("exist").click(); 
65      cy.findByText("I am series - post 2 content").should("exist");
66      cy.findByRole("link", {name: "Next: Series - Post 2"}).should("not.exist");
67
68    }
69    )

This test is failing on line 65 - the link is clicked but the page doesn't redirect and the subsequent content isn't found.

This test fails consistently, but we can't reproduce the error manually.

This very helpful Stack Overflow helps us shed some light. The link element is found, and we click it, but by the time we click it the element is detached from the DOM and the click doesn't register.

As a workaround - we can add {force:true} to click command.

This is a thoroughly unsatisfying resolution though.

Difficulty: 🔴 - Difficult.

46    it("external component", () => {
47      cy.visit('/test/external_component'); 
48
49      // I'm not asserting on actual content it should encounter 
50      // Because we quickly hit the rate limit
51      cy.get(".react-github-permalink").should("exist");
52    })

In this test the Github Permalinks fail to render.

We see Minified React error #329, (Unknown root exit status) in the console.

This test fails consistently, but we can't reproduce the error manually.

This appears to be something to do with NextJS, but it's unclear what.

I don't have a resolution for this - I'm skipping those tests.

Note minified React errors only seem to occur when visiting the application via Cypress. This is an issue that I've encountered before with my tests against Remix as well , so that they exist doesn't especially concern me.

But it does concern me is that in NextJS these errors cause functional problems - in Remix the functionality of the application would continue to work.

Difficulty: 🔴 - Difficult.

98    it("comment blocks", () => {
99      cy.visit('test/basic_mdx?q=foo'); 
100
101      cy.get("iframe.utterances-frame").should("exist");
102    })

In this test the Utterances comment section iframe fails to appear.

This test fails sporadically. We are seeing a lot of minified React errors, and it could be something to do with that #329 error above.

It may be that this iframe is the offender for all of the issues. This comment in the above Cypress issue suggests wrapping scripts in a suspense boundary.

I wrapped one around my PostComments component and for a bit these issues did seem to be resolved, though they resurfaced.

13        <Suspense>
14            <PostComments />
15        </Suspense>