CRUSH.md#

Project Overview#

This is a personal portfolio website built with Bun, React, TypeScript, and Tailwind CSS. It uses the shadcn/ui component library and serves as both a portfolio and development environment for AT Protocol-related projects. The project demonstrates modern web development practices with a focus on decentralized technologies.

Development Commands#

Core Commands#

• bun install - Install dependencies
• bun dev - Start development server with hot reload and HMR
• bun start - Run production server
• bun run build.ts - Build for production (outputs to dist/)
• bun run build.ts --help - Show all build options

Build System#

The custom build script (build.ts) supports various options:

• --outdir <path> - Output directory (default: "dist")
• --minify - Enable minification
• --sourcemap <type> - Sourcemap type (none|linked|inline|external)
• --external <list> - External packages (comma separated)

The build automatically:

• Processes all HTML files in src/ as entrypoints
• Copies public/ folder to dist
• Uses Tailwind plugin for CSS processing
• Includes linked sourcemaps by default

Architecture#

Project Structure#

src/
├── components/
│   ├── ui/           # shadcn/ui components (Button, Card, Input, etc.)
│   ├── sections/     # Main page sections (Header, Work, Connect)
│   └── ...           # Other React components
├── data/
│   └── portfolio.ts  # Portfolio content and metadata
├── hooks/            # Custom React hooks
├── lib/              # Utility functions
└── styles/           # Global CSS and Tailwind config

Server Architecture#

• Uses Bun's built-in server (src/index.ts)
• Serves React SPA with API routes
• API routes use pattern matching (/api/hello/:name)
• CORS headers configured for cross-origin requests
• Development mode includes HMR and browser console echoing

Key Files#

• src/index.ts - Server entry point with API routes
• src/App.tsx - Main React component with intersection observer animations
• src/data/portfolio.ts - All portfolio content (personal info, work experience, skills)
• build.ts - Custom build script with extensive CLI options
• styles/globals.css - Tailwind imports, CSS variables, and custom animations

Code Conventions#

TypeScript Configuration#

• Strict mode enabled with noUncheckedIndexedAccess
• Path aliases: @/* maps to ./src/*
• JSX: react-jsx transform
• Module resolution: bundler mode
• Target: ESNext with DOM libraries

Component Patterns#

• Uses shadcn/ui component library with class-variance-authority
• Utility function cn() combines clsx and tailwind-merge
• Components follow Radix UI patterns for accessibility
• File exports: Named exports for components, default for main App

Styling#

• Tailwind CSS v4 with custom CSS variables
• Dark theme by default with light mode support
• Glassmorphism effects with custom utilities
• Custom animations: fade-in-up, bounce-slow
• Fira Code monospace font throughout

Import Aliases (from components.json)#

"@/components" → "./src/components"
"@/lib/utils" → "./src/lib/utils"  
"@/components/ui" → "./src/components/ui"
"@/lib" → "./src/lib"
"@/hooks" → "./src/hooks"

UI Components#

shadcn/ui Integration#

The project uses shadcn/ui with:

• Style variant: "new-york"
• Base color: "neutral"
• Icon library: Lucide React
• CSS variables enabled
• Custom CSS location: styles/globals.css

Available UI Components#

• Button (multiple variants: default, destructive, outline, secondary, ghost, link)
• Card
• Input
• Label
• Select
• Textarea

Custom Components#

• ThemeToggle (dark/light mode switching)
• SectionNav (navigation between portfolio sections)
• ProjectCard/WorkExperienceCard (portfolio item displays)
• SocialLink (social media links with icons)

Content Management#

Portfolio data is centralized in src/data/portfolio.ts:

• personalInfo - Name, title, description, availability, contact
• currentRole - Current employment status
• skills - Array of technical skills
• workExperience - Array of work history with projects
• socialLinks - Social media profiles
• sections - Page section identifiers

The description format supports rich text with bold styling and URLs:

type DescriptionPart = {
  text: string
  bold?: boolean
  url?: string
}

Deployment#

Netlify Configuration#

• Static site hosting
• CORS headers configured in public/netlify.toml
• AT Protocol DID file at public/.well-known/atproto-did

Build Output#

• Production builds output to dist/
• All HTML files in src/ become entrypoints
• Public assets copied automatically
• Source maps linked for debugging

Development Notes#

Hot Module Replacement#

• Development server includes HMR
• Browser console logs echoed to server
• Automatic reloading on file changes

Performance Features#

• Intersection Observer for scroll-triggered animations
• Code splitting support in build configuration
• Minification enabled by default in production
• Lazy loading with react imports

AT Protocol Integration#

• Project showcases AT Protocol-related work
• Uses atproto-ui component library
• Bluesky and Tangled integration in portfolio

Gotchas#

Build System#

• Custom build script requires Bun runtime (not Node.js)
• HTML files in src/ automatically become entrypoints
• Must use --external flag for libraries that shouldn't be bundled

Styling#

• Dark mode is default styling approach
• CSS variables are used extensively for theming
• Custom glassmorphism effects require SVG filters (defined in CSS)

Server Routes#

• API routes use Bun's pattern matching syntax
• All unmatched routes serve the main SPA (catch-all route)
• CORS headers pre-configured for API access

Content Structure#

• Portfolio content is TypeScript data, not markdown
• Rich text descriptions use specific object structure
• Projects support multiple links (live demo, GitHub, etc.)