# Development

Learn how to develop and work with the codebase.



Learn how to develop and work with the codebase.

## Development Workflow [#development-workflow]

### Starting the Dev Server [#starting-the-dev-server]

```bash
bun run dev
```

Features in development mode:

* Hot module replacement
* Fast refresh
* Error overlay
* Source maps

### Previewing the Documentation Site [#previewing-the-documentation-site]

The separate Next.js/Fumadocs documentation app lives in `docs/`. From the repository root:

```bash
flox activate
bun install --cwd docs --frozen-lockfile
bun run docs:dev
```

Open [the local docs site](http://localhost:3000/docs).
Author Markdown in `docs/src/` and update `docs/navigation.json` for new pages.
Regenerate MDX after edits with `bun run --cwd docs generate:content`.
The preview reloads when generated content changes. Run `bun run docs:check`
inside Flox to validate the full docs application. The root `AGENTS.md` requires
relevant documentation updates alongside code changes.

The docs app uses the actual set-me-up-docs shell and components with portfolio
branding. See [documentation architecture](/docs/architecture/documentation) for
content generation and deployment responsibilities.

### Available Scripts [#available-scripts]

#### Development [#development]

```bash
bun run dev              # Start dev server
bun run build            # Build for production
bun run start            # Start production server
```

#### Code Quality [#code-quality]

```bash
bun run lint             # Run ESLint
bun run format           # Format with Prettier
bun run format:check     # Check formatting
```

#### Testing [#testing]

```bash
bun run test             # Run tests (watch mode)
bun run test:run         # Run tests once
bun run test:watch       # Watch mode
bun run test:coverage    # Generate coverage report
```

#### Build Scripts [#build-scripts]

```bash
bun run download:images:unsplash # Download Unsplash images
bun run prepare-chatbot-data     # Prepare chatbot training data
```

## Code Organization [#code-organization]

### Components [#components]

Components are organized by domain:

* `chat/` - Chatbot widget and dynamic loader
* `gallery/` - VSCO and featured gallery
* `home/` - Homepage sections (bio, social, Gumroad)
* `layout/` - SiteNav, BottomNav, CommandPalette, SmoothScroll
* `mdx/` - Table, YouTubeEmbed for MDX content
* `notes/` - Article pages, note list, related articles
* `projects/` - Project list, filter bar, open source
* `ui/` - Shared primitives (ImagePreview, UniversalImage)

### Hooks [#hooks]

Custom hooks in `src/hooks/`:

* `use-views.ts` - Page view tracking
* `use-gumroad-products.ts` - Gumroad product fetching
* `use-vsco-gallery.ts` - VSCO gallery data
* `use-infinite-vsco-gallery.ts` - Paginated VSCO gallery

### Lib [#lib]

Library code grouped by feature:

* `animation/` - Framer Motion variants and config
* `content/` - MDX parsing with gray-matter
* `image/` - Unsplash image resolution and attribution
* `projects/` - Project config and icon components
* `og.ts` - OG image URL generation
* `vsco-local.ts` - Local VSCO export reader

## Best Practices [#best-practices]

### Code Style [#code-style]

* Use TypeScript for all new code
* Follow existing patterns in the codebase
* Use kebab-case for file names
* Export named functions/components

### Performance [#performance]

* Use React Server Components where possible
* Implement proper loading states
* Optimize images with Next.js Image
* Use dynamic imports for heavy components

### Testing [#testing-1]

* Write tests for new features
* Maintain test coverage above 80%
* Test edge cases and error states
* Use Testing Library best practices

## Next Steps [#next-steps]

* [Environment Variables →](/docs/getting-started/environment)
* [Architecture Overview →](/docs/architecture/overview)
* [Contributing Guidelines →](/docs/contributing/guidelines)