CLAUDE.md · joemccann/dillinger

Sections

1. Quick Reference
2. Tech Stack
3. Architecture Overview
4. Code Conventions
5. Security Guidelines
6. Performance Best Practices
7. Common Patterns
8. Testing
9. Deployment
10. Troubleshooting
11. Key Files Reference
12. Design Context

First lines (shown under the repo's MIT license)

<claude-mem-context>
# Recent Activity

<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->

### Jan 19, 2026

| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #1873 | 2:32 PM | 🔵 | Next.js Migration Dependency Stack with Modern Equivalents | ~510 |
| #1861 | 2:25 PM | 🔵 | Next.js Config with Lucide-React Bundle Optimization | ~396 |
| #1850 | 2:24 PM | ✅ | Added Modal and Toast Z-Index Layers to Tailwind Configuration | ~354 |
| #1827 | 2:22 PM | 🔵 | Tailwind Configuration with Legacy Dillinger Design Tokens | ~463 |
</claude-mem-context>

# Dillinger Next.js - CLAUDE.md

> Cloud-enabled, mobile-ready, offline-storage-compatible Markdown editor built with Next.js 14.

## Quick Reference

```bash
npm run dev      # Start dev server (http://localhost:3000)
npm run build    # Production build
npm run start    # Start production server
npm run lint     # Run ESLint
```

## Tech Stack

| Category | Technology | Version |
|----------|------------|---------|
| Framework | Next.js (App Router) | 14.2.35 |
| Language | TypeScript (strict) | 5.x |
| UI | React | 18.x |
| Styling | Tailwind CSS | 3.4.1 |
| State | Zustand | 5.0.10 |
| Editor | Monaco Editor | 4.7.0 |
| Icons | Lucide React | 0.562.0 |
| Markdown | markdown-it + plugins | 14.1.0 |

## Architecture Overview

```
dillinger/
├── app/                    # Next.js App Router
│   ├── api/               # API route handlers
│   │   ├── github/        # GitHub OAuth + file ops
│   │   ├── dropbox/       # Dropbox integration
│   │   ├── google-drive/  # Google Drive integration
│   │   ├── onedrive/      # Microsoft OneDrive
│   │   ├── bitbucket/     # Bitbucket integration
│   │   ├── medium/        # Medium publishing
│   │   └── export/        # PDF/HTML export
│   ├── layout.tsx         # Root layout (providers)
│   ├── page.tsx           # Main editor page
│   ├── globals.css        # Global styles + Tailwind
│   ├── error.tsx          # Error boundary
│   └── not-found.tsx      # 404 page
├── components/
│   ├── editor/            # Monaco editor wrapper
│   ├── preview/           # Markdown preview pane
│   ├── navbar/            # Top navigation
│   ├── sidebar/           # Document list + integrations
│   ├── modals/            # OAuth dialogs (GitHub, Dropbox, etc.)
│   ├── providers/         # Context providers
│   └── ui/                # Reusable primitives (Toast, Skeleton)
├── hooks/                 # Custom React hooks
│   ├── useGitHub.ts
│   ├── useDropbox.ts
│   ├── useGoogleDrive.ts
│   ├── useOneDrive.ts
│   ├── useBitbucket.ts
│   └── useMedium.ts
├── stores/
│   └── store.ts           # Zustand store (documents, settings, UI)
├── lib/                   # Utilities and helpers
└── types/                 # TypeScript type definitions
```

## Code Conventions

### TypeScript

- **Strict mode enabled** - all code must pass strict type checking
- Use `interface` for object shapes, `type` for unions/intersections
- Prefer explicit return types on exported functions
- Use path alias `@/*` for imports from project root

```typescript
// Good
import { useAppStore } from '@/stores/store'
import { Document } from '@/types'

// Avoid
import { useAppStore } from '../../../stores/store'
```

### Components

- **Client Components**: Add `"use client"` directive at top for interactive components
- **Server Components**: Default for layouts and static content (no directive needed)
- **Naming**: PascalCase for components, camelCase for hooks/utilities
- **File naming**: Match component name (e.g., `EditorContainer.tsx` exports `EditorContainer`)

```typescript
// Client component pattern
"use client"

import { useState } from 'react'

interface Props {
  initialValue: string
  onChange: (value: string) => void
}

export function MyComponent({ initialValue, onChange }: Props) {
  const [value, setValue] = useState(initialValue)
  // ...
}
```

### Dynamic Imports

Use dynamic imports for:
- Components with browser-only APIs (Monaco, localStorage)
- Heavy components that aren't needed on initial load
- Components that cause hydration mismatches

```typescript
import dynamic from 'next/dynamic'

const Sidebar = dynamic(() => import('@/components/sidebar/Sidebar'), {
  ssr: false,  // Disable SSR for client-only components
})
```

### Styling with Tailwind

- Use design tokens from `tailwind.config.ts` (colors, spacing, z-index)
- Combine classes with `clsx` and `tailwind-merge` via the `cn()` utility
- Follow z-index scale: sidebar(1) < page(2) < editor(3) < preview(4) < overlay(5) < navbar(6) < settings(7) < modal(50) < toast(60)

```typescript
import { cn } from '@/lib/utils'

// Good - uses design tokens
<div className={cn(
  "bg-bg-sidebar text-text-primary",
  "w-sidebar p-gutter",
  isActive && "bg-bg-highlight"
)} />

// Avoid - hardcoded values
<div className="bg-[#2B2F36] w-[270px] p-8" />
```

### Zustand State Management

- Store lives in `/stores/store.ts`