Skip to content

AGENTS.md

Latest commit

 

History

History
248 lines (171 loc) · 7.81 KB

AGENTS.md

File metadata and controls

248 lines (171 loc) · 7.81 KB

AI Agent Guidelines for chanhdai.com

This guide provides essential information for AI agents working with the chanhdai.com codebase - a Next.js dev portfolio, blog, and component registry website.

Project Overview

Next.js portfolio, blog, and component registry website with:

  • Component registry using shadcn/ui system
  • Blog with MDX content
  • Custom React components

Tech Stack

  • Framework: Next.js 16 (App Router)
  • Styling: Tailwind CSS v4
  • UI Components: shadcn/ui + custom components
  • Package Manager: pnpm
  • Language: TypeScript
  • Content: MDX for blog posts
  • Deployment: Vercel

Project Structure

Key Directories

  • src/app/ - Next.js App Router pages (routes, layouts, API routes)
  • src/components/ - Shared UI components
  • src/registry/ - Component registry source (components, hooks, blocks, examples)
  • src/__registry__/ - Auto-generated registry files (DO NOT EDIT)
  • src/features/ - Feature-based modules (blog, portfolio, sponsors)
  • src/config/ - Site and registry configuration
  • src/hooks/ - Custom React hooks
  • src/lib/ - Utility libraries and helpers
  • src/styles/ - Global styles and CSS
  • src/assets/ - Static assets (fonts, metadata)
  • src/scripts/ - Build and utility scripts
  • src/types/ - TypeScript type definitions
  • src/utils/ - Utility functions

Important Files

  • src/config/site.ts - Site configuration and navigation
  • src/config/registry.ts - Registry configuration
  • src/features/portfolio/data/user.ts - User portfolio data
  • src/registry/index.ts - Registry entry point
  • components.json - shadcn/ui configuration

Component Registry System

The project features a custom component registry built on top of shadcn/ui:

Registry Structure

  • Components (src/registry/registry-components.ts) - UI components
  • Hooks (src/registry/registry-hook.ts) - Custom React hooks
  • Blocks (src/registry/registry-blocks.ts) - Pre-built blocks and sections
  • Examples (src/registry/registry-examples.ts) - Component demos
  • Lib (src/registry/registry-lib.ts) - Utility functions

Registry Types

  • registry:component - Reusable UI components (src/registry/registry-components.ts)
  • registry:hook - Custom React hooks (src/registry/registry-hook.ts)
  • registry:block - Pre-built blocks and sections (src/registry/registry-blocks.ts)
  • registry:example - Component examples/demos (src/registry/registry-examples.ts)
  • registry:lib - Utility libraries (src/registry/registry-lib.ts)

Registry Build Process

# Build registry internally
pnpm registry:internal:build

# Build shadcn registry
pnpm registry:build

Auto-generated files (DO NOT EDIT):

  • src/__registry__/index.tsx
  • src/__registry__/registry.autogenerated.json
  • public/r/*.json

Development Guidelines

Getting Started

# Install dependencies
pnpm install

# Start development server
pnpm dev  # Runs on port 1408

# Build for production
pnpm build

Code Standards

  • TypeScript: Strict mode enabled
  • ESLint: Next.js configuration
  • Prettier: Code formatting
  • File naming: kebab-case for files and component files

Coding Guidelines

When writing code for this project, follow these principles:

  • Write type-safe TypeScript code with explicit types when necessary
  • Use descriptive variable and function names that make code self-documenting
  • Add comments only for complex logic or non-obvious behavior (focus on "why" not "what")
  • No emojis in code, comments, or commit messages
  • Use JSDoc for public APIs when the signature alone isn't clear
  • Follow SOLID principles: keep functions small, focused, and easy to understand

Component Development

  1. Create component in src/registry/[component-name]/
  2. Add to appropriate registry file (registry-components.ts, etc.)
  3. Create examples in src/registry/examples/
  4. Run registry build commands
  5. Update documentation

Working with Content

Blog Posts

  • Location: src/features/blog/content/
  • Format: MDX files
  • Supports: Custom components, code blocks, metadata

User Portfolio

Portfolio Data Files (src/features/portfolio/data/):

  • user.ts - Core personal information, bio, contact details, job history
  • experiences.ts - Detailed work experience, education, company information
  • projects.ts - Portfolio projects with descriptions, links, skills, logos
  • tech-stack.ts - Technology stack, programming languages, tools, frameworks
  • awards.ts - Competition awards, prizes, academic achievements, certificates
  • certifications.ts - Professional certifications, course completions, credentials
  • social-links.ts - Social media profiles, professional networks, contact links
  • testimonials.ts - Professional recommendations, endorsements from colleagues and clients

Environment & Configuration

Environment Variables

See .env.example for required variables:

Core Application:

  • APP_URL - Application base URL (e.g., https://acme.com)

Registry Configuration:

  • REGISTRY_NAMESPACE - Namespace identifier for shadcn CLI (e.g., @acme)
  • REGISTRY_NAMESPACE_URL - URL pattern for component resolution (e.g., https://acme.com/r/{name}.json)

External Services:

  • GITHUB_API_TOKEN - GitHub Personal Access Token for API calls (Get token)
  • NEXT_PUBLIC_DMCA_URL - DMCA Protection badge URL (DMCA ProtectionPro)

Analytics & Tracking:

  • NEXT_PUBLIC_POSTHOG_KEY - PostHog project API key for analytics (Get key)
  • NEXT_PUBLIC_POSTHOG_HOST - PostHog API host URL (e.g., https://ph.acme.com)
  • NEXT_PUBLIC_POSTHOG_UI_HOST - PostHog UI host URL (e.g., https://us.i.posthog.com)

Analytics Events

The project uses PostHog for analytics tracking. Events are defined in src/lib/events.ts with Zod schema validation. PostHog is initialized in src/instrumentation-client.ts (production only) with consent management via @c15t/nextjs package.

Site Configuration

  • Navigation: MAIN_NAV in src/config/site.ts
  • Theme colors: META_THEME_COLORS
  • GitHub repo: SOURCE_CODE_GITHUB_REPO

Common Tasks

Adding a New Component

  1. Create component directory: src/registry/[name]/
  2. Implement component with proper TypeScript types
  3. Add to src/registry/registry-components.ts
  4. Create example in src/registry/examples/
  5. Build registry: pnpm registry:build

Updating User Information

Edit src/features/portfolio/data/user.ts with new:

  • Personal information
  • Job details
  • Project descriptions
  • Contact information

Adding Blog Posts

  1. Create MDX file in src/features/blog/content/
  2. Include frontmatter metadata
  3. Use custom components for enhanced content

Styling Guidelines

  • Use Tailwind CSS v4 syntax
  • Follow existing color scheme (zinc-based)
  • Support dark/light modes
  • Use CSS variables for theme colors

Important Notes

Registry Dependencies

  • Components may depend on external packages

Auto-generated Files

NEVER EDIT these files directly:

  • src/__registry__/index.tsx
  • src/__registry__/registry.autogenerated.json
  • Files in public/r/

Performance Considerations

  • Components use React.lazy() for code splitting
  • Images optimized with Next.js Image component
  • MDX content is statically generated

Personal Information

When adapting this codebase, ensure ALL personal information is replaced. See User Portfolio section above for data file locations. Also update src/config/site.ts, blog posts, and asset URLs throughout the codebase.

Build Commands

pnpm build          # Production build
pnpm start          # Start production server
pnpm preview        # Build and preview locally
pnpm lint           # Run ESLint
pnpm format:write   # Format code with Prettier
pnpm check-types    # TypeScript type checking