@primer/doctocat-nextjs 0.0.0-20250716161640 → 0.0.0-20250904115752

package/CHANGELOG.md

@@ -1,16 +1,28 @@
 # @primer/doctocat-nextjs
 
-## 0.0.0-20250716161640
+## 0.0.0-20250904115752
 
 ### Patch Changes
 
 - Fake entry to force publishing
 
-## 0.0.0-20250716161638
+## 0.0.0-20250904115750
 
 ### Minor Changes
 
-- [#63](https://github.com/primer/doctocat-nextjs/pull/63) [`45ebb5b`](https://github.com/primer/doctocat-nextjs/commit/45ebb5b1ceb165e2eaed7563558b52c52c1c1c59) Thanks [@rezrah](https://github.com/rezrah)! - Moves `@primer/react-brand` to a peer-dependency.
+- [`84ff648`](https://github.com/primer/doctocat-nextjs/commit/84ff648a8248712d61e13a7e6432ab2ab8e07435) 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.
+
+## 0.6.0
+
+### Minor Changes
+
+- [#63](https://github.com/primer/doctocat-nextjs/pull/63) [`9a090ee`](https://github.com/primer/doctocat-nextjs/commit/9a090eec47c64dc46f8eac14ec00548d421e8019) Thanks [@rezrah](https://github.com/rezrah)! - Moves `@primer/react-brand` to a peer-dependency.
 
   This change prevents a mismatch of versions between Doctocat and the project using it. Going forward, the latter will be preferred.
 

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,7 +34,29 @@ type CodeBlockProps = {
 
 export function CodeBlock(props: CodeBlockProps) {
   if (['tsx', 'jsx'].includes(props['data-language'])) {
-    return <ReactCodeBlock {...props} />
+    // 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.
+    try {
+      const childrenAsString = renderToStaticMarkup(<>{props.children}</>)
+
+      const textContent = childrenAsString.replace(/<[^>]*>/g, '')
+
+      // 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} />
+    }
   }
 
   return <Pre>{props.children}</Pre>

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

@@ -28,7 +28,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 +39,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 +56,9 @@ export const getRelatedPages: GetRelatedPages = (route, activeMetadata, flatDocs
 
   return matches
 }
+
+function titleToString(title: React.ReactNode): string {
+  if (typeof title === 'string') return title
+  if (typeof title === 'number') return title.toString()
+  return ''
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/doctocat-nextjs",
-  "version": "0.0.0-20250716161640",
+  "version": "0.0.0-20250904115752",
   "description": "A Next.js theme for building Primer documentation sites",
   "main": "index.js",
   "type": "module",
@@ -21,17 +21,16 @@
     "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",
-    "react-focus-on": "3.9.4",
-    "react-live": "^4.1.8"
+    "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"
   },
   "devDependencies": {
     "@github/prettier-config": "^0.0.6",
@@ -47,7 +46,9 @@
     "@vitest/ui": "^3.2.4",
     "clsx": "2.1.1",
     "jsdom": "^26.0.1",
-    "next": "15.3.5",
+    "next": "15.5.2",
+    "react-live": "^4.1.8",
+    "react-live-runner": "^1.0.7",
     "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