Next.js Blog Developer

An expert assistant for working with the Next.js 14 static blog template built with Velite, Tailwind, Shadcn/UI, and MDX.

What This Skill Does

This skill helps you work effectively with a feature-based Next.js blog architecture, following modern 2025 best practices. It understands the project's content standards, debugging protocols, and component organization patterns.

Key Capabilities

Content Management

Architecture Understanding

Debugging Protocols

Instructions

When Working with Blog Content

1. **Tag Validation**

- Check all tags exist in `/lib/content/tags.json`

- Limit to maximum 4 tags per post

- Apply priority order: Language (if >50% content) → Main concept → Secondary concept/tool (if >20% content) → Industry context

- Reference full guidelines in `/lib/content/standards.md`

2. **Tag Selection Examples**

- Algorithm posts: `["JavaScript", "Data Structures", "Algorithms", "Best Practices"]`

- Framework tutorials: `["JavaScript", "React", "API", "Tutorial"]`

- Performance guides: `["React", "Performance", "Best Practices"]`

When Fixing Navigation/Linking Bugs

1. **Discovery Phase**

- Use `grep -r "ComponentName" .` to find ALL instances of the component

- Never fix only some instances - patterns must be applied consistently

2. **Analysis Phase**

- Debug data structures with console.log or temporary debug pages

- Verify assumptions about data structure before making changes

3. **Fix Phase**

- Apply fixes to ALL instances simultaneously

- For PostItem components, ALWAYS use `post.slugAsParams` (not `post.slug`)

- Reason: `post.slug` includes "blog/" prefix, creating double-prefixed URLs

4. **Validation Phase**

- Test ALL affected pages: homepage, blog listing, tag pages

- Verify URLs are `/blog/post-slug` (not `/blog/blog/post-slug`)

5. **Documentation Phase**

- Record the reasoning for future reference

When Debugging Production-Only Crashes

**Phase 1: Environment Analysis**

**Phase 2: Systematic Investigation**

**Phase 3: Root Cause Categories**

**Phase 4: Fix Implementation**

MDX Component Safety Protocol

Always follow this pattern when working with MDX components:

```tsx

const safeRender = (content: string) => {

try {

// Unsafe operation

const result = new Function(content);

return result({ ...runtime }).default;

} catch (error) {

console.error("Render failed:", error);

// Always return fallback component

return () => (

<div className="error-fallback">

Content temporarily unavailable

</div>

);

}

};

```

**Rules:**

When Adding New Components

Follow feature-based organization:

1. **Components**: Place in appropriate feature directory

- Blog functionality → `components/features/blog/`

- Search functionality → `components/features/search/`

- Navigation → `components/features/navigation/`

- MDX content → `components/features/mdx/`

- Pure UI components → `components/ui/`

2. **Hooks**: Organize by domain

- Search hooks → `hooks/features/search/`

- UI hooks → `hooks/ui/`

- General hooks → `hooks/`

3. **Utilities**: Use organized structure

- UI utilities → `lib/utils/ui.ts`

- Formatting → `lib/utils/formatting.ts`

- Blog-specific → `lib/utils/blog.ts`

- Export via `lib/utils/index.ts`

4. **Imports**: Use clean patterns

- Features: `@/components/features/blog`

- Hooks: `@/hooks/features/search`

- Utils: `@/lib/utils/ui` or `@/lib/utils` (backward compatible)

Red Flags to Avoid

Constraints

Example Usage

**Fixing a navigation bug:**

1. Search: `grep -r "PostItem" .`

2. Find all instances (homepage, blog page, tag pages)

3. Verify all use `post.slugAsParams` (not `post.slug`)

4. Test all affected pages

5. Document the fix

**Adding a new blog feature:**

1. Create component in `components/features/blog/`

2. Add hooks in `hooks/features/blog/` if needed

3. Export via barrel file (`index.ts`)

4. Import using `@/components/features/blog`

**Debugging a production crash:**

1. Check error boundary location

2. Review component for client/server mismatches

3. Inspect MDX rendering code for unsafe operations

4. Add error boundaries and fallbacks

5. Test in production-like environment