Bellog File Organization

This skill defines the file structure, naming conventions, and organization patterns for the Bellog blog project.

Project Structure

/Users/castle_bell/Projects/bellog/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── layout.tsx          # Root layout with fonts & metadata
│   │   ├── page.tsx            # Home page
│   │   ├── template.tsx        # Page transition wrapper
│   │   ├── providers.tsx       # Client-side providers
│   │   ├── posts/
│   │   │   ├── page.tsx        # All posts page
│   │   │   └── [slug]/
│   │   │       └── page.tsx    # Individual post
│   │   ├── api/
│   │   │   └── revalidate/
│   │   │       └── route.ts    # Cache revalidation endpoint
│   │   ├── robots.ts           # SEO robots.txt
│   │   └── sitemap.ts          # Dynamic sitemap
│   │
│   ├── components/
│   │   ├── common/             # App-wide shared components
│   │   │   ├── Navbar.tsx
│   │   │   ├── Footer.tsx
│   │   │   ├── Intro.tsx
│   │   │   ├── Header.tsx
│   │   │   └── ...
│   │   ├── posts/              # Post-specific components
│   │   │   ├── PostCard.tsx
│   │   │   ├── PostList.tsx
│   │   │   ├── PostRenderer.tsx
│   │   │   ├── NotionToc.tsx
│   │   │   └── ...
│   │   └── ui/                 # Low-level UI primitives
│   │       ├── Tag.tsx
│   │       ├── ThemeToggle.tsx
│   │       ├── switch.tsx
│   │       └── ...
│   │
│   ├── hooks/                  # Custom React hooks
│   │   ├── useScrollSpy.ts
│   │   ├── useTocObserver.ts
│   │   └── useHeadings.ts
│   │
│   ├── lib/                    # Business logic & utilities
│   │   ├── notion.ts           # Notion API client
│   │   ├── posts.ts            # Post data fetching
│   │   ├── tags.ts             # Tag utilities
│   │   └── utils.ts            # General utilities
│   │
│   ├── constants/              # Shared constants
│   │   └── ui.ts               # UI-related constants
│   │
│   ├── types/                  # TypeScript types
│   │   └── index.d.ts          # Global type definitions
│   │
│   └── styles/                 # Global styles
│       └── global.css          # Theme variables + Tailwind
│
├── public/                     # Static assets
├── .claude/                    # Claude Code configuration
│   ├── agents/                 # Custom sub-agents
│   └── skills/                 # Custom skills
├── .github/                    # GitHub configuration
│   └── PULL_REQUEST_TEMPLATE.md
├── .husky/                     # Git hooks
├── tailwind.config.ts          # Tailwind configuration
├── tsconfig.json               # TypeScript configuration
├── next.config.ts              # Next.js configuration
├── package.json                # Dependencies & scripts
├── commitlint.config.ts        # Commit message linting
├── CLAUDE.md                   # Project guide
└── README.md                   # Project documentation

Naming Conventions

Components

Rule: PascalCase

✅ Correct:
PostCard.tsx
NotionToc.tsx
ScrollToTop.tsx
ThemeToggle.tsx

❌ Wrong:
postCard.tsx
notion-toc.tsx
scroll_to_top.tsx

Hooks

Rule: camelCase with use prefix

✅ Correct:
useScrollSpy.ts
useTocObserver.ts
useHeadings.ts
useScrollPosition.ts

❌ Wrong:
UseScrollSpy.ts
scroll-spy-hook.ts
scrollSpy.ts (missing use prefix)

Utilities & Libraries

Rule: camelCase

✅ Correct:
notion.ts
posts.ts
tags.ts
utils.ts

❌ Wrong:
Notion.ts
Posts.ts
tag-utils.ts

Types

Rule: camelCase file, PascalCase exports

✅ Correct:
File: index.d.ts
Export: interface Post { }
Export: type PostStatus = 'published' | 'draft';

❌ Wrong:
File: Post.d.ts
Export: interface post { }

Constants

Rule: SCREAMING_SNAKE_CASE for values, camelCase for file

✅ Correct:
File: ui.ts
Exports:
  export const HEADER_OFFSET = 80;
  export const SCROLL_SPY_OFFSET = 100;

❌ Wrong:
export const headerOffset = 80;
export const header-offset = 80;

API Routes

Rule: camelCase folder, route.ts file

✅ Correct:
app/api/revalidate/route.ts

❌ Wrong:
app/api/Revalidate/route.ts
app/api/revalidate/revalidate.ts

Where to Place Files

Decision Tree

Q: Is it a React component?

• Yes → /src/components/
  • App-wide (Navbar, Footer) → /src/components/common/
  • Post-specific (PostCard, NotionToc) → /src/components/posts/
  • Reusable UI primitive (Tag, Button) → /src/components/ui/

Q: Is it a custom hook?

• Yes → /src/hooks/use[Name].ts

Q: Is it business logic or data fetching?

• Yes → /src/lib/
  • Notion API → /src/lib/notion.ts
  • Post data → /src/lib/posts.ts
  • Utility functions → /src/lib/utils.ts

Q: Is it a constant value?

• Yes → /src/constants/
  • UI-related → /src/constants/ui.ts
  • API-related → /src/constants/api.ts

Q: Is it a TypeScript type?

• Yes → /src/types/index.d.ts

Q: Is it a page or route?

• Yes → /src/app/[route]/page.tsx

Q: Is it an API endpoint?

• Yes → /src/app/api/[endpoint]/route.ts

Component Organization

Common Components (/src/components/common/)

Components used across multiple pages:

• Layout components (Navbar, Footer)
• Page sections (Intro, Header)
• Shared widgets (ProgressBar)

Examples:

• Navbar.tsx - Site navigation
• Footer.tsx - Site footer
• Intro.tsx - Hero section with animations
• ProgressBar.tsx - Scroll progress indicator
• Header.tsx - Page headers

Post Components (/src/components/posts/)

Components specific to blog posts:

• Post rendering (PostRenderer)
• Post navigation (NotionToc, PostNavigation)
• Post lists (PostList, PostCard)

Examples:

• PostCard.tsx - Individual post preview
• PostList.tsx - Grid of post cards
• PostRenderer.tsx - Notion content renderer
• NotionToc.tsx - Table of contents
• PostNavigation.tsx - Previous/Next navigation
• GiscusComments.tsx - Comment system

UI Components (/src/components/ui/)

Low-level, reusable UI primitives:

• Buttons, inputs, switches
• Tags, badges
• Shadcn/ui components

Examples:

• Tag.tsx - Tag display
• TagList.tsx - Tag filtering
• ThemeToggle.tsx - Dark/light mode toggle
• switch.tsx - Radix UI switch (shadcn/ui)

File Templates

Component Template

// For interactive components
"use client";

import { useState } from 'react';
import { motion } from 'framer-motion';

interface ComponentNameProps {
  // Props
}

export function ComponentName({ }: ComponentNameProps) {
  // Logic

  return (
    <div>
      {/* JSX */}
    </div>
  );
}

Hook Template

import { useState, useEffect } from 'react';

/**
 * Brief description of what this hook does
 *
 * @example
 * const value = useHookName();
 */
export function useHookName() {
  // Hook logic

  return value;
}

Utility Template

/**
 * Brief description of utility function
 *
 * @param paramName - Description
 * @returns Description
 */
export function utilityName(paramName: Type): ReturnType {
  // Implementation
}

Type Definition Template

// /src/types/index.d.ts

export interface Post {
  id: string;
  title: string;
  slug: string;
  date: string;
  description: string;
  tags: string[];
  status: PostStatus;
}

export type PostStatus = 'published' | 'draft' | 'archived';

Import Organization

Order

// 1. React & Next.js
import { useState } from 'react';
import Link from 'next/link';

// 2. Third-party libraries
import { motion } from 'framer-motion';
import { Search } from 'lucide-react';

// 3. Internal imports (@/...)
import { Button } from '@/components/ui/button';
import { getAllPosts } from '@/lib/posts';
import { HEADER_OFFSET } from '@/constants/ui';

// 4. Relative imports
import { helperFunction } from '../utils';

// 5. Type imports (separate)
import type { Post } from '@/types';

Path Aliases

Bellog uses @/ for root imports:

// ✅ Correct
import { PostCard } from '@/components/posts/PostCard';
import { getAllPosts } from '@/lib/posts';
import { HEADER_OFFSET } from '@/constants/ui';

// ❌ Wrong (no relative paths from root)
import { PostCard } from '../../components/posts/PostCard';

Code Organization Patterns

Single Responsibility

// ✅ Good - Each file has one clear purpose
// /src/lib/notion.ts - Notion API calls
// /src/lib/posts.ts - Post data transformation
// /src/lib/tags.ts - Tag utilities

// ❌ Bad - Everything in one file
// /src/lib/everything.ts

Group Related Code

// ✅ Good - Related components together
/src/components/posts/
  PostCard.tsx
  PostList.tsx
  PostNavigation.tsx

// ❌ Bad - All components flat
/src/components/
  PostCard.tsx
  Navbar.tsx
  PostList.tsx
  Footer.tsx

Constants Extraction

// ✅ Good - Constants in separate file
// /src/constants/ui.ts
export const HEADER_OFFSET = 80;
export const SCROLL_SPY_OFFSET = 100;

// Component uses constants
import { HEADER_OFFSET } from '@/constants/ui';

// ❌ Bad - Magic numbers in component
const offset = 80; // What is this?

File Size Guidelines

Components: < 200 lines

• If larger, consider splitting into smaller components

Hooks: < 100 lines

• If larger, consider extracting helper functions

Utils: < 50 lines per function

• If larger, break into smaller functions

Types: No limit

• Types can be long, that's okay

Barrel Exports (Avoid)

// ❌ Avoid barrel exports (index.ts files)
// /src/components/index.ts
export { PostCard } from './PostCard';
export { PostList } from './PostList';

// ✅ Prefer direct imports
import { PostCard } from '@/components/posts/PostCard';
import { PostList } from '@/components/posts/PostList';

Why: Barrel exports slow down builds and complicate tree-shaking.

Environment Files

.env.local          # Local development secrets (gitignored)
.env.example        # Template (committed to git)

Never commit:

• .env.local
• .env
• Any file with actual secrets

Git Ignore Patterns

Ensure these are in .gitignore:

# Dependencies
node_modules/
.pnp
.pnp.js

# Next.js
.next/
out/

# Environment
.env.local
.env

# IDE
.vscode/
.idea/

# OS
.DS_Store

Documentation Structure

/                           # Root
├── README.md              # Project overview & setup
├── CLAUDE.md              # Development guide (for AI)
└── docs/                  # Detailed documentation (if needed)
    ├── architecture.md
    └── deployment.md

Quick Reference

Components:     PascalCase.tsx      /src/components/{common,posts,ui}/
Hooks:          useName.ts          /src/hooks/
Utilities:      name.ts             /src/lib/
Constants:      NAME                /src/constants/
Types:          name.d.ts           /src/types/
Pages:          page.tsx            /src/app/[route]/
API:            route.ts            /src/app/api/[endpoint]/

Checklist for New Files

• File in correct directory
• Naming convention followed (PascalCase / camelCase)
• Imports organized by category
• Using @ alias for imports (not relative from root)
• TypeScript types defined
• No magic numbers (use constants)
• Single responsibility (one clear purpose)
• File size reasonable (< 200 lines for components)

Remember: Organization is about findability. When someone looks for a file, it should be obvious where it is.