Next.js Blog Development Assistant

Expert assistant for developing and maintaining a Next.js 15 blog with microCMS integration, featuring SSG optimization and hybrid rendering architecture.

Tech Stack

Commands

When working with this project, use these specific commands:

1. **Development**: Run `npm run dev-build` followed by `npm run dev-server` to test the application

2. **Production Build**: Run `npm run build` followed by `npm run start`

3. **Linting**: Run `npm run lint` to check code quality

**CRITICAL**: NEVER use `npm run dev` - this project requires the build-then-serve approach.

Environment Variables

Ensure these microCMS environment variables are configured:

Architecture Overview

Page Structure

The blog uses Next.js App Router with the following routes:

1. `/` - Homepage with latest articles

2. `/tag/[tagId]` - Tag-filtered article listing

3. `/article/[articleId]` - Individual article pages

4. Custom 404 pages for non-existent content

Key Components

Data Layer

API Routes

Content Processing Architecture

Hybrid Rendering Flow

```

Raw Content (microCMS)

↓ Server-Side (SSG)

├── ToC Generation

├── HTML Component Replacement

└── Image Optimization

↓

Static HTML Generated

↓ Client-Side (Runtime)

├── Prism Highlighting

└── Iframely Loading

↓

Final Rendered Content

```

Key Components

1. **ServerSideContentRenderer** - Processes content at build time

2. **ClientSideContentRenderer** - Processes content at runtime using hooks

3. **HtmlComponentRenderer** - Wrapper for articles with HTML components

4. **CodeHighlighter** - Wrapper for articles without HTML components

Development Guidelines

When Adding Features

1. **Check the architecture first**: Determine if the feature requires server-side (SSG) or client-side (CSR) processing

2. **Use TypeScript interfaces**: All microCMS types are defined in `src/types/microcms.ts`

3. **Follow the path alias convention**: Use `@/` for imports

4. **Maintain separation of concerns**: Keep server and client processing separate

When Modifying Content Processing

1. **Server-side changes**: Edit `ServerSideContentRenderer` for SSG-time processing

2. **Client-side changes**: Edit `ClientSideContentRenderer` for runtime processing

3. **Never mix the two**: Keep the hybrid architecture clean

When Working with microCMS

1. Use the API client functions in `src/lib/microcms.ts`

2. Always type responses using interfaces from `src/types/microcms.ts`

3. Handle API errors gracefully, especially in CSR components

SEO and Performance

1. **SEO**: Add proper meta tags and OGP to all pages

2. **Images**: Use Next.js Image optimization and lazy loading

3. **Accessibility**: Include alt attributes, ensure proper contrast, support keyboard navigation

4. **Mobile**: Ensure responsive design works on PC/tablet/mobile

Content Structure

Articles must include:

Testing Workflow

1. Make code changes

2. Run `npm run dev-build` to build the application

3. Run `npm run dev-server` to test the build

4. Verify changes in browser

5. Run `npm run lint` to check code quality

6. Before deployment, run `npm run build` to ensure production build succeeds

Common Tasks

Adding a New Page

1. Create the route in `src/app/[route]/page.tsx`

2. Add proper TypeScript types for params and searchParams

3. Implement server-side data fetching for SSG

4. Add SEO metadata

5. Test with both build commands

Adding a New API Route

1. Create the route in `src/app/api/[route]/route.ts`

2. Implement proper error handling

3. Type all responses

4. Consider rate limiting if needed

Modifying Content Rendering

1. Identify if the change is server-side or client-side

2. Edit the appropriate renderer component

3. Test with a full rebuild

4. Verify in browser that both SSG and CSR work correctly

Additional Documentation

Refer to `docs/dd.md` for detailed screen design specifications and component details.