Upgrade to Next.js 16 with Turbopack and Contentlayer2

- Upgraded Next.js to v16, React to v19
- Migrated from contentlayer to contentlayer2
- Migrated to Turbopack by decoupling Contentlayer from webpack
- Updated all page components to handle async params (Next.js 15+ breaking change)
- Changed package.json to type: module and renamed config files to .cjs
- Updated README with current tech stack and article creation instructions
- Fixed tag encoding issue (removed double encoding)
- All security vulnerabilities resolved (npm audit: 0 vulnerabilities)

README.md

@@ -1,15 +1,16 @@
 # Personal Blog (Next.js + Contentlayer)
 
-This is a personal blog built with **Next.js 13 (App Router)**, **Contentlayer**, and **Tailwind CSS**.
+This is a personal blog built with **Next.js 16 (App Router)**, **Contentlayer2**, and **Tailwind CSS**.
 Markdown content (posts & pages) lives in a separate repository and is consumed via a git submodule.
-Recent iterations focused on migrating every image to `next/image`, refreshing the typography scale for mixed Chinese/English copy, and layering an elegant scrolling timeline aesthetic onto the home + blog index.
+Recent updates include upgrading to Next.js 16 with Turbopack, migrating to Contentlayer2, and implementing React 19 features.
 
 ## Tech Stack
 
-- **Framework**: Next.js 13 (App Router)
+- **Framework**: Next.js 16 (App Router) with Turbopack
 - **Language**: TypeScript
+- **Runtime**: React 19
 - **Styling**: Tailwind CSS + Typography plugin
-- **Content**: Markdown via Contentlayer (`contentlayer/source-files`)
+- **Content**: Markdown via Contentlayer2 (`contentlayer2/source-files`)
 - **Theming**: `next-themes` (light/dark), env‑driven accent color system
 - **Content source**: Git submodule `content` → [`personal-blog`](https://gitea.gbanyan.net/gbanyan/personal-blog.git)
 
@@ -294,15 +295,70 @@ This ensures your `content` folder matches the commit referenced in `blog-nextjs
 
 ## Available npm Scripts
 
-- `npm run dev` – Start Next.js dev server (Contentlayer is integrated via `next-contentlayer`).
-- `npm run build` – Run `next build` for production.
+- `npm run dev` – Start Contentlayer and Next.js dev server concurrently (with Turbopack).
+- `npm run build` – Build content and production bundle (`contentlayer2 build && next build`).
 - `npm run start` – Start the production server (after `npm run build`).
 - `npm run lint` – Run Next.js / ESLint linting.
-- `npm run contentlayer` – Manually run `contentlayer build` (optional).
+- `npm run sync-assets` – Copy `content/assets` to `public/assets`.
+
+## Adding New Content
+
+### Creating a New Blog Post
+
+1. Navigate to the `content/posts` directory (inside the submodule):
+
+   ```bash
+   cd content/posts
+   ```
+
+2. Create a new markdown file (e.g., `my-new-post.md`):
+
+   ```markdown
+   ---
+   title: "My New Post Title"
+   published_at: "2025-01-15"
+   tags:
+     - "Technology"
+     - "Tutorial"
+   description: "A brief description of the post"
+   feature_image: "../assets/my-image.jpg"
+   ---
+
+   Your post content goes here...
+   ```
+
+3. If using images, place them in `content/assets/` and reference them with relative paths:
+
+   ```markdown
+   ![Image description](../assets/my-image.jpg)
+   ```
+
+4. Commit and push changes in the submodule:
+
+   ```bash
+   git add .
+   git commit -m "Add new post: My New Post Title"
+   git push
+   ```
+
+5. Update the parent repository to reference the new submodule commit:
+
+   ```bash
+   cd ../..
+   git add content
+   git commit -m "Update content submodule"
+   git push
+   ```
+
+6. The new post will appear automatically after rebuilding or restarting the dev server.
+
+### Creating a New Static Page
+
+Follow the same process as above, but create the file in `content/pages/` instead.
 
 ## Deployment Notes
 
-- This is a standard Next.js 13 App Router project and can be deployed to:
+- This is a Next.js 16 App Router project with Turbopack and can be deployed to:
   - Vercel
   - Any Node.js host running `npm run build && npm run start`
 - Make sure to:

app/blog/[slug]/page.tsx

@@ -2,7 +2,7 @@ import Link from 'next/link';
 import Image from 'next/image';
 import { notFound } from 'next/navigation';
 import type { Metadata } from 'next';
-import { allPosts } from 'contentlayer/generated';
+import { allPosts } from 'contentlayer2/generated';
 import { getPostBySlug, getRelatedPosts, getPostNeighbors } from '@/lib/posts';
 import { siteConfig } from '@/lib/config';
 import { ReadingProgress } from '@/components/reading-progress';
@@ -20,11 +20,11 @@ export function generateStaticParams() {
 }
 
 interface Props {
-  params: { slug: string };
+  params: Promise<{ slug: string }>;
 }
 
-export function generateMetadata({ params }: Props): Metadata {
-  const slug = params.slug;
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
   const post = getPostBySlug(slug);
   if (!post) return {};
 
@@ -34,8 +34,8 @@ export function generateMetadata({ params }: Props): Metadata {
   };
 }
 
-export default function BlogPostPage({ params }: Props) {
-  const slug = params.slug;
+export default async function BlogPostPage({ params }: Props) {
+  const { slug } = await params;
   const post = getPostBySlug(slug);
 
   if (!post) return notFound();

app/pages/[slug]/page.tsx

@@ -2,7 +2,7 @@ import Link from 'next/link';
 import Image from 'next/image';
 import { notFound } from 'next/navigation';
 import type { Metadata } from 'next';
-import { allPages } from 'contentlayer/generated';
+import { allPages } from 'contentlayer2/generated';
 import { getPageBySlug } from '@/lib/posts';
 import { siteConfig } from '@/lib/config';
 import { ReadingProgress } from '@/components/reading-progress';
@@ -17,11 +17,11 @@ export function generateStaticParams() {
 }
 
 interface Props {
-  params: { slug: string };
+  params: Promise<{ slug: string }>;
 }
 
-export function generateMetadata({ params }: Props): Metadata {
-  const slug = params.slug;
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
   const page = getPageBySlug(slug);
   if (!page) return {};
 
@@ -31,8 +31,8 @@ export function generateMetadata({ params }: Props): Metadata {
   };
 }
 
-export default function StaticPage({ params }: Props) {
-  const slug = params.slug;
+export default async function StaticPage({ params }: Props) {
+  const { slug } = await params;
   const page = getPageBySlug(slug);
 
   if (!page) return notFound();

app/tags/[tag]/page.tsx

@@ -1,5 +1,5 @@
 import type { Metadata } from 'next';
-import { allPosts } from 'contentlayer/generated';
+import { allPosts } from 'contentlayer2/generated';
 import { PostListWithControls } from '@/components/post-list-with-controls';
 import { getTagSlug } from '@/lib/posts';
 import { SidebarLayout } from '@/components/sidebar-layout';
@@ -22,11 +22,11 @@ export function generateStaticParams() {
 }
 
 interface Props {
-  params: { tag: string };
+  params: Promise<{ tag: string }>;
 }
 
-export function generateMetadata({ params }: Props): Metadata {
-  const slug = params.tag;
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { tag: slug } = await params;
   // Find original tag label by slug
   const tag = allPosts
     .flatMap((post) => post.tags ?? [])
@@ -37,15 +37,15 @@ export function generateMetadata({ params }: Props): Metadata {
   };
 }
 
-export default function TagPage({ params }: Props) {
-  const slug = params.tag;
+export default async function TagPage({ params }: Props) {
+  const { tag: slug } = await params;
 
   const posts = allPosts.filter(
     (post) => post.tags && post.tags.some((t) => getTagSlug(t) === slug)
   );
 
   const tagLabel =
-    posts[0]?.tags?.find((t) => getTagSlug(t) === slug) ?? params.tag;
+    posts[0]?.tags?.find((t) => getTagSlug(t) === slug) ?? slug;
 
   return (
     <SidebarLayout>

components/post-card.tsx

@@ -1,6 +1,6 @@
 import Link from 'next/link';
 import Image from 'next/image';
-import type { Post } from 'contentlayer/generated';
+import type { Post } from 'contentlayer2/generated';
 import { siteConfig } from '@/lib/config';
 import { faCalendarDays, faTags } from '@fortawesome/free-solid-svg-icons';
 import { MetaItem } from './meta-item';

components/post-layout.tsx

@@ -31,7 +31,7 @@ export function PostLayout({ children, hasToc = true }: { children: React.ReactN
                     </motion.div>
                 </div>
 
-                {/* Sidebar (TOC) */}
+                {/* Desktop Sidebar (TOC) */}
                 <aside className="hidden lg:block">
                     <div className="sticky top-24 h-[calc(100vh-6rem)] overflow-hidden">
                         <AnimatePresence mode="wait">
@@ -51,14 +51,32 @@ export function PostLayout({ children, hasToc = true }: { children: React.ReactN
                 </aside>
             </div>
 
+            {/* Mobile TOC Overlay */}
+            <AnimatePresence>
+                {isTocOpen && hasToc && (
+                    <motion.div
+                        initial={{ opacity: 0, y: 20 }}
+                        animate={{ opacity: 1, y: 0 }}
+                        exit={{ opacity: 0, y: 20 }}
+                        transition={{ duration: 0.2 }}
+                        className="fixed bottom-24 right-4 z-40 w-72 rounded-2xl border border-white/20 bg-white/90 p-6 shadow-2xl backdrop-blur-xl dark:border-white/10 dark:bg-slate-900/90 lg:hidden"
+                    >
+                        <div className="max-h-[60vh] overflow-y-auto">
+                            <PostToc onLinkClick={() => setIsTocOpen(false)} />
+                        </div>
+                    </motion.div>
+                )}
+            </AnimatePresence>
+
             {/* Toggle Button (Glassmorphism Pill) */}
             {hasToc && (
                 <motion.button
                     layout
                     onClick={() => setIsTocOpen(!isTocOpen)}
                     className={cn(
-                        "fixed bottom-8 right-20 z-50 flex items-center gap-2 rounded-full border border-white/20 bg-white/80 px-4 py-2.5 shadow-lg backdrop-blur-md transition-all hover:bg-white hover:scale-105 dark:border-white/10 dark:bg-slate-900/80 dark:hover:bg-slate-900",
-                        "text-sm font-medium text-slate-600 dark:text-slate-300"
+                        "fixed bottom-8 right-8 z-50 flex items-center gap-2 rounded-full border border-white/20 bg-white/80 px-4 py-2.5 shadow-lg backdrop-blur-md transition-all hover:bg-white hover:scale-105 dark:border-white/10 dark:bg-slate-900/80 dark:hover:bg-slate-900",
+                        "text-sm font-medium text-slate-600 dark:text-slate-300",
+                        "lg:right-20" // Adjust position for desktop
                     )}
                     whileTap={{ scale: 0.95 }}
                     aria-label="Toggle Table of Contents"

components/post-list-item.tsx

@@ -1,6 +1,6 @@
 import Link from 'next/link';
 import Image from 'next/image';
-import type { Post } from 'contentlayer/generated';
+import { Post } from 'contentlayer2/generated';
 import { siteConfig } from '@/lib/config';
 import { faCalendarDays, faTags } from '@fortawesome/free-solid-svg-icons';
 import { MetaItem } from './meta-item';

components/post-list-with-controls.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useMemo, useState } from 'react';
-import type { Post } from 'contentlayer/generated';
+import { Post, Page } from 'contentlayer2/generated';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import {
   faArrowDownWideShort,
@@ -88,8 +88,7 @@ export function PostListWithControls({ posts, pageSize }: Props) {
           <button
             type="button"
             onClick={() => handleChangeSort('new')}
-            className={`inline-flex items-center gap-1 rounded-full px-2 py-0.5 transition duration-180 ease-snappy ${
-              sortOrder === 'new'
+            className={`inline-flex items-center gap-1 rounded-full px-2 py-0.5 transition duration-180 ease-snappy ${sortOrder === 'new'
               ? 'bg-blue-600 text-white dark:bg-blue-500'
               : 'bg-white text-slate-600 hover:bg-slate-200 dark:bg-slate-900 dark:text-slate-300 dark:hover:bg-slate-700'
               }`}
@@ -100,8 +99,7 @@ export function PostListWithControls({ posts, pageSize }: Props) {
           <button
             type="button"
             onClick={() => handleChangeSort('old')}
-            className={`inline-flex items-center gap-1 rounded-full px-2 py-0.5 transition duration-180 ease-snappy ${
-              sortOrder === 'old'
+            className={`inline-flex items-center gap-1 rounded-full px-2 py-0.5 transition duration-180 ease-snappy ${sortOrder === 'old'
               ? 'bg-blue-600 text-white dark:bg-blue-500'
               : 'bg-white text-slate-600 hover:bg-slate-200 dark:bg-slate-900 dark:text-slate-300 dark:hover:bg-slate-700'
               }`}
@@ -178,8 +176,7 @@ export function PostListWithControls({ posts, pageSize }: Props) {
                   key={p}
                   type="button"
                   onClick={() => goToPage(p)}
-                  className={`h-7 w-7 rounded text-xs ${
-                    isActive
+                  className={`h-7 w-7 rounded text-xs ${isActive
                     ? 'bg-blue-600 text-white dark:bg-blue-500'
                     : 'hover:bg-slate-100 dark:hover:bg-slate-800'
                     }`}

components/post-storyline-nav.tsx

@@ -1,5 +1,5 @@
 import Link from 'next/link';
-import type { Post } from 'contentlayer/generated';
+import { Post } from 'contentlayer2/generated';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import { faArrowLeftLong, faArrowRightLong } from '@fortawesome/free-solid-svg-icons';
 
@@ -94,8 +94,7 @@ function Station({ station }: { station: StationConfig }) {
         {post.title}
       </p>
       <span
-        className={`mt-2 h-0.5 w-16 rounded-full bg-slate-200 transition group-hover:w-24 group-hover:bg-blue-400 dark:bg-slate-700 ${
-          align === 'end' ? 'self-end' : 'self-start'
+        className={`mt-2 h-0.5 w-16 rounded-full bg-slate-200 transition group-hover:w-24 group-hover:bg-blue-400 dark:bg-slate-700 ${align === 'end' ? 'self-end' : 'self-start'
           }`}
       />
     </Link>

components/post-toc.tsx

@@ -10,7 +10,7 @@ interface TocItem {
   depth: number;
 }
 
-export function PostToc() {
+export function PostToc({ onLinkClick }: { onLinkClick?: () => void }) {
   const [items, setItems] = useState<TocItem[]>([]);
   const [activeId, setActiveId] = useState<string | null>(null);
   const listRef = useRef<HTMLDivElement | null>(null);
@@ -87,6 +87,11 @@ export function PostToc() {
       url.hash = id;
       history.replaceState(null, '', url.toString());
     }
+
+    // Trigger callback if provided (e.g. to close mobile menu)
+    if (onLinkClick) {
+      onLinkClick();
+    }
   };
 
   if (items.length === 0) return null;

components/right-sidebar.tsx

@@ -5,7 +5,7 @@ import { faGithub, faMastodon, faLinkedin } from '@fortawesome/free-brands-svg-i
 import { faFire, faArrowRight } from '@fortawesome/free-solid-svg-icons';
 import { siteConfig } from '@/lib/config';
 import { getAllTagsWithCount } from '@/lib/posts';
-import { allPages } from 'contentlayer/generated';
+import { allPages } from 'contentlayer2/generated';
 
 export function RightSidebar() {
   const tags = getAllTagsWithCount().slice(0, 5);

components/site-header.tsx

@@ -2,7 +2,7 @@ import Link from 'next/link';
 import { ThemeToggle } from './theme-toggle';
 import { NavMenu, NavLinkItem, IconKey } from './nav-menu';
 import { siteConfig } from '@/lib/config';
-import { allPages } from 'contentlayer/generated';
+import { allPages } from 'contentlayer2/generated';
 
 export function SiteHeader() {
   const pages = allPages

contentlayer.config.ts

@@ -1,4 +1,4 @@
-import { defineDocumentType, makeSource } from 'contentlayer/source-files';
+import { defineDocumentType, makeSource } from 'contentlayer2/source-files';
 import { visit } from 'unist-util-visit';
 import rehypeSlug from 'rehype-slug';
 import rehypeAutolinkHeadings from 'rehype-autolink-headings';

lib/posts.ts

@@ -1,4 +1,4 @@
-import { allPosts, allPages, Post, Page } from 'contentlayer/generated';
+import { allPosts, allPages, Post, Page } from 'contentlayer2/generated';
 
 export function getAllPostsSorted(): Post[] {
   return [...allPosts].sort((a, b) => {
@@ -27,7 +27,7 @@ export function getPageBySlug(slug: string): Page | undefined {
 }
 
 export function getTagSlug(tag: string): string {
-  return encodeURIComponent(tag.toLowerCase().replace(/\s+/g, '-'));
+  return tag.toLowerCase().replace(/\s+/g, '-');
 }
 
 export function getAllTagsWithCount(): { tag: string; slug: string; count: number }[] {

next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

next.config.mjs

@@ -1,20 +1,9 @@
-import { withContentlayer } from 'next-contentlayer';
-
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   images: {
     remotePatterns: []
   },
-  webpack: (config) => {
-    config.ignoreWarnings = [
-      ...(config.ignoreWarnings || []),
-      // Contentlayer dynamic import / cache analysis warnings
-      /@contentlayer\/core[\\/]dist[\\/]dynamic-build\.js/,
-      /@contentlayer\/core[\\/]dist[\\/]getConfig[\\/]index\.js/,
-      /@contentlayer\/core[\\/]dist[\\/]generation[\\/]generate-dotpkg\.js/
-    ];
-    return config;
-  }
+
 };
 
-export default withContentlayer(nextConfig);
+export default nextConfig;

package.json

@@ -4,9 +4,9 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "dev": "next dev",
+    "dev": "concurrently \"contentlayer2 dev\" \"next dev\"",
     "sync-assets": "node scripts/sync-assets.mjs",
-    "build": "npm run sync-assets && next build",
+    "build": "npm run sync-assets && contentlayer2 build && next build",
     "start": "next start",
     "lint": "next lint",
     "contentlayer": "contentlayer build"
@@ -14,21 +14,23 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
-  "type": "commonjs",
+  "type": "module",
   "dependencies": {
+    "@emotion/is-prop-valid": "^1.4.0",
+    "@fortawesome/fontawesome-svg-core": "^7.1.0",
     "@fortawesome/free-brands-svg-icons": "^7.1.0",
     "@fortawesome/free-solid-svg-icons": "^7.1.0",
     "@fortawesome/react-fontawesome": "^3.1.0",
     "clsx": "^2.1.1",
-    "contentlayer": "^0.3.4",
+    "contentlayer2": "^0.5.8",
     "framer-motion": "^12.23.24",
     "gray-matter": "^4.0.3",
     "markdown-wasm": "^1.2.0",
-    "next": "^13.5.11",
-    "next-contentlayer": "^0.3.4",
+    "next": "^16.0.3",
+    "next-contentlayer2": "^0.5.8",
     "next-themes": "^0.4.6",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.1",
@@ -40,8 +42,9 @@
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.5",
     "autoprefixer": "^10.4.22",
+    "concurrently": "^9.2.1",
     "eslint": "^8.57.1",
-    "eslint-config-next": "^13.5.11",
+    "eslint-config-next": "^16.0.3",
     "postcss": "^8.5.6",
     "tailwindcss": "^3.4.18",
     "typescript": "^5.9.3"

tsconfig.json

@@ -15,7 +15,7 @@
     "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "incremental": true,
     "types": [
       "node"
@@ -25,7 +25,7 @@
       "@/*": [
         "./*"
       ],
-      "contentlayer/generated": [
+      "contentlayer2/generated": [
         "./.contentlayer/generated"
       ]
     },
@@ -40,7 +40,8 @@
     "**/*.ts",
     "**/*.tsx",
     ".contentlayer/generated",
-    ".next/types/**/*.ts"
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
   ],
   "exclude": [
     "node_modules"