@primer/doctocat-nextjs 0.6.0 → 0.7.0-rc.b4901f1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @primer/doctocat-nextjs
 
+## 0.7.0
+
+### Minor Changes
+
+- [#65](https://github.com/primer/doctocat-nextjs/pull/65) [`dc680ec`](https://github.com/primer/doctocat-nextjs/commit/dc680ec51605bd7a40dedc71cd3bb107632035dd) Thanks [@rezrah](https://github.com/rezrah)! - Updated Next.js compatibility to v15.5.x, Nextra to v4, and fix React code block rendering
+
+  - **Next.js v15.5.2**: Upgraded to latest stable version across all workspaces
+  - **Nextra v4 compatibility**: Updated type definitions for `ReactNode` titles
+  - **Fixed code block rendering**: Added client-side rendering for interactive code examples to handle React lazy components properly
+
+    Next.js v15.4+ changed how lazy components render on the server, breaking interactive code blocks. This update uses client-side code snippet extraction to convert lazy components to clean code strings for the live editor, preventing hydration mismatches and preserving existing behavior.
+
+  - **Improved 404 page experience**: New 404 page to replace default Next.js version. Also removed stray 0 in top-left.
+
 ## 0.6.0
 
 ### Minor Changes

package/components/layout/code-block/CodeBlock.tsx

@@ -1,8 +1,31 @@
 'use client'
 import React, {PropsWithChildren} from 'react'
+import dynamic from 'next/dynamic'
+import {renderToStaticMarkup} from 'react-dom/server'
 
-import {ReactCodeBlock} from './ReactCodeBlock'
 import {Pre} from 'nextra/components'
+import {Box, Stack, Text} from '@primer/react-brand'
+import {Spinner} from '@primer/react'
+
+// We need to load this on the client to avoid a hydration mismatch.
+const ReactCodeBlock = dynamic(
+  async () => {
+    const module = await import('./ReactCodeBlock')
+    return {default: module.ReactCodeBlock}
+  },
+  {
+    ssr: false,
+    loading: () => (
+      <Box borderStyle="solid" borderWidth="thin" borderColor="default" borderRadius="medium" marginBlockEnd="normal">
+        <Stack style={{minHeight: 340}} alignItems="center" justifyContent="center">
+          <Text>
+            <Spinner />
+          </Text>
+        </Stack>
+      </Box>
+    ),
+  },
+)
 
 type CodeBlockProps = {
   'data-language': string
@@ -11,6 +34,42 @@ type CodeBlockProps = {
 
 export function CodeBlock(props: CodeBlockProps) {
   if (['tsx', 'jsx'].includes(props['data-language'])) {
+    // Next.js v15.4+ will lazy render components on the server, which prevents us from
+    // sending usable React nodes to the ReactCodeBlock component.
+    // Workaround is to convert the code snippets to string on the client and pass to react-live.
+
+    // suppresses compilation warnings
+    if (typeof window !== 'undefined') {
+      try {
+        const childrenAsString = renderToStaticMarkup(<>{props.children}</>)
+
+        // Extract text content using browser's HTML parser (immune to regex bypass attacks)
+        const cleanHtmlTag = (str: string): string => {
+          const parser = new DOMParser()
+          const doc = parser.parseFromString(str, 'text/html')
+          return doc.body.textContent || doc.body.innerText || ''
+        }
+
+        const textContent = cleanHtmlTag(childrenAsString)
+
+        // Restore escaped chars
+        const decodedText = textContent
+          .replace(/&lt;/g, '<')
+          .replace(/&gt;/g, '>')
+          .replace(/&quot;/g, '"')
+          .replace(/&#x27;/g, "'")
+          .replace(/&amp;/g, '&')
+
+        return <ReactCodeBlock {...props} code={decodedText} />
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.log('Error extracting code snippet. Forwarding children directly:', error)
+        // Fallback to original children-based approach
+        return <ReactCodeBlock {...props} />
+      }
+    }
+
+    // During SSR/build, use children-based approach
     return <ReactCodeBlock {...props} />
   }
 

package/components/layout/code-block/ReactCodeBlock.tsx

@@ -18,6 +18,7 @@ const COLLAPSE_HEIGHT = 400 // TODO: Hoist this to config to make user customiza
 type ReactCodeBlockProps = {
   'data-language': string
   'data-filename'?: string
+  code?: string
   jsxScope: Record<string, unknown>
 } & PropsWithChildren<HTMLElement>
 
@@ -34,7 +35,7 @@ export function ReactCodeBlock(props: ReactCodeBlockProps) {
   const uniqueId = useId()
   const {colorMode, setColorMode} = useColorMode()
   const {basePath} = useConfig()
-  const initialCode = getCodeFromChildren(props.children)
+  const initialCode = props.code || getCodeFromChildren(props.children)
   const [code, setCode] = useState(initialCode)
   const rootRef = useRef<HTMLDivElement>(null)
   const [isCodePaneCollapsed, setIsCodePaneCollapsed] = useState<boolean | null>(null)

package/components/layout/related-content-links/getRelatedPages.tsx

@@ -1,5 +1,6 @@
 import {DocsItem, FrontMatter} from '../../../types'
 import {RelatedContentLink} from './RelatedContentLinks'
+import React from 'react'
 
 type GetRelatedPages = (
   route: string,
@@ -28,7 +29,10 @@ export const getRelatedPages: GetRelatedPages = (route, activeMetadata, flatDocs
     const intersection = pageKeywords.filter(keyword => currentPageKeywords.includes(keyword))
 
     if (intersection.length) {
-      matches.push(page)
+      matches.push({
+        ...page,
+        title: titleToString(page.title), // Convert ReactNode to string
+      })
     }
   }
 
@@ -36,14 +40,12 @@ export const getRelatedPages: GetRelatedPages = (route, activeMetadata, flatDocs
   for (const link of relatedLinks) {
     if (!link.title || !link.href || link.href === route) continue
     if (link.href.startsWith('/')) {
-      const page = flatDocsDirectories.find(localPage => localPage.route === link.href) as
-        | RelatedContentLink
-        | undefined
+      const page = flatDocsDirectories.find(localPage => localPage.route === link.href)
 
       if (page) {
         const entry = {
           ...page,
-          title: link.title || page.title,
+          title: link.title || titleToString(page.title),
           route: link.href || page.route,
         }
         matches.push(entry)
@@ -55,3 +57,19 @@ export const getRelatedPages: GetRelatedPages = (route, activeMetadata, flatDocs
 
   return matches
 }
+
+function titleToString(title: React.ReactNode): string {
+  const children = React.Children.toArray(title)
+
+  return children
+    .map(child => {
+      if (typeof child === 'string' || typeof child === 'number') {
+        return child.toString()
+      }
+      if (React.isValidElement(child) && child.props.children) {
+        return titleToString(child.props.children)
+      }
+      return ''
+    })
+    .join('')
+}

package/components/layout/root-layout/Theme.tsx

@@ -149,7 +149,7 @@ export function Theme({pageMap, children}: ThemeProps) {
                       <Stack direction="vertical" padding="none" gap="spacious">
                         {!isHomePage && (
                           <>
-                            {activePath.length && (
+                            {activePath.length > 0 && (
                               <Breadcrumbs>
                                 {(activeHeaderLink || siteTitle) && (
                                   <Breadcrumbs.Item

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.6.0",
+  "version": "0.7.0-rc.b4901f1",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",
@@ -21,15 +21,15 @@
     "react-dom": ">=18.0.0 <20.0.0"
   },
   "dependencies": {
-    "@next/mdx": "15.3.5",
+    "@next/mdx": "15.5.2",
     "@primer/octicons-react": "19.15.1",
     "@primer/react": "^37.11.0",
     "@types/lodash.debounce": "^4.0.9",
     "framer-motion": "12.4.0",
     "lodash.debounce": "^4.0.8",
-    "nextra": "4.2.17",
-    "react": "18.3.1",
-    "react-dom": "18.3.1",
+    "nextra": "4.4.0",
+    "react": ">=18.0.0 <20.0.0",
+    "react-dom": ">=18.0.0 <20.0.0",
     "react-focus-on": "3.9.4",
     "react-live": "^4.1.8"
   },
@@ -47,7 +47,7 @@
     "@vitest/ui": "^3.2.4",
     "clsx": "2.1.1",
     "jsdom": "^26.0.1",
-    "next": "15.3.5",
+    "next": "15.5.2",
     "styled-components": "5.3.11",
     "vitest": "^3.2.4"
   },

package/types.ts

@@ -1,4 +1,5 @@
 import {Folder, PageMapItem, MdxFile} from 'nextra'
+import {ReactNode} from 'react'
 
 export type ThemeConfig = {
   docsRepositoryBase: string
@@ -19,7 +20,7 @@ export type ExtendedPageItem = PageMapItem & {
 export type FolderWithoutChildren = Omit<Folder, 'children'>
 
 export type DocsItem = MdxFile & {
-  title: string
+  title: ReactNode
   type: string
   children?: DocsItem[]
   firstChildRoute?: string