|
| 1 | +# Transcribo Frontend - Agent Coding Guidelines |
| 2 | + |
| 3 | +## Build & Development Commands |
| 4 | + |
| 5 | +```bash |
| 6 | +# Install dependencies (Bun required, not npm) |
| 7 | +bun install |
| 8 | + |
| 9 | +# Development server |
| 10 | +bun run dev |
| 11 | + |
| 12 | +# Build for production |
| 13 | +bun run build |
| 14 | + |
| 15 | +# Start production server |
| 16 | +bun run start |
| 17 | + |
| 18 | +# Generate static site |
| 19 | +bun run generate |
| 20 | + |
| 21 | +# Linting & Formatting |
| 22 | +bun run lint # Biome format --write |
| 23 | +bun run check # Biome check --fix |
| 24 | + |
| 25 | +# Docker |
| 26 | +bun run docker:dev # Start dev container |
| 27 | +bun run docker:dev:down # Stop dev container |
| 28 | +bun run docker:prod # Start production container |
| 29 | +bun run docker:prod:down # Stop production container |
| 30 | +``` |
| 31 | + |
| 32 | +## Package Manager |
| 33 | +**Use `bun` for all package operations, NOT npm.** |
| 34 | + |
| 35 | +## Code Style Guidelines |
| 36 | + |
| 37 | +### TypeScript & Vue |
| 38 | +- **Always use Composition API** (`<script setup lang="ts">`) |
| 39 | +- **Never use `any` type** - use `unknown` with validation or specific types |
| 40 | +- **Never use non-null assertion `!`** - structure code so TypeScript understands nullable values |
| 41 | +- **Always use semicolons** - terminate all statements |
| 42 | +- **Prefer undefined over null** - use `ref(undefined)` not `ref(null)` |
| 43 | +- **Non-null refs** - initialize refs with values, not null |
| 44 | +- **Explicit types** - function parameters and return types must be typed |
| 45 | +- **Function declarations** - use `function foo()` not `const foo = () => {}` |
| 46 | +- **Async/await** - prefer over promise chains |
| 47 | + |
| 48 | +### Naming Conventions |
| 49 | +- **Pages**: kebab-case (`user-profile.vue`) |
| 50 | +- **Components**: PascalCase (`UserProfileCard.vue`) |
| 51 | +- **Composables**: camelCase with `use` prefix (`useCounter.ts`) |
| 52 | +- **Server API**: kebab-case (`user-account.get.ts`) |
| 53 | +- **Utils/Services**: camelCase (`formatDate.ts`) |
| 54 | + |
| 55 | +### Import Aliases |
| 56 | +```typescript |
| 57 | +~/ // app/ directory |
| 58 | +~~/ // root directory |
| 59 | +~~/server // server directory |
| 60 | +``` |
| 61 | + |
| 62 | +### UI & Styling |
| 63 | +- **Use Nuxt UI components** instead of custom implementations |
| 64 | +- **Use Tailwind CSS** for styling (native, no custom CSS when possible) |
| 65 | +- **Use Lucide icons** (auto-imported via Nuxt UI) |
| 66 | +- **Use motion** for animations (auto-imported via `motion-v`) |
| 67 | + |
| 68 | +### Formatting (Biome) |
| 69 | +- 4 space indentation |
| 70 | +- Double quotes for strings |
| 71 | +- Semicolons required |
| 72 | +- `organizeImports` enabled |
| 73 | + |
| 74 | +## Key Conventions from Cursor/Copilot Rules |
| 75 | +- Use `===` and `!==` for equality |
| 76 | +- No `console` in production code |
| 77 | +- No `@ts-ignore` - always fix type errors |
| 78 | +- No TypeScript enums |
| 79 | +- No reassigning function parameters |
| 80 | +- No unused imports/variables (ignored in .vue files) |
| 81 | +- Use `for-of` instead of `forEach` |
| 82 | +- Use `Array.isArray()` instead of `instanceof Array` |
| 83 | +- Throw Error objects with messages |
| 84 | +- Handle async errors properly with try/catch |
| 85 | + |
| 86 | +## Project Structure |
| 87 | +``` |
| 88 | +app/ |
| 89 | + components/ # Vue components (PascalCase) |
| 90 | + composables/ # use* functions (camelCase) + other composables |
| 91 | + pages/ # Routes (kebab-case) |
| 92 | + utils/ # Framework-agnostic utilities |
| 93 | + services/ # API/business logic (e.g., indexDbService.ts) |
| 94 | + types/ # TypeScript definitions |
| 95 | + plugins/ # Nuxt plugins (e.g., api.ts, konvaPlugin.client.ts) |
| 96 | + layouts/ # Page layouts (default.vue, edit.vue) |
| 97 | + assets/ # Static assets (CSS, images, disclaimer.html) |
| 98 | +server/ |
| 99 | + api/ # API endpoints (kebab-case with HTTP method suffix) |
| 100 | + utils/ # Server utilities |
| 101 | + changelogs/ # Version changelog markdown files |
| 102 | + tsconfig.json # Server-specific TypeScript config |
| 103 | +public/ |
| 104 | + ios/ # PWA icons for iOS |
| 105 | + icons.json # PWA icon configuration |
| 106 | +``` |
| 107 | + |
| 108 | +## Key Dependencies |
| 109 | +- **Nuxt UI 4.x** - Component library |
| 110 | +- **@ffmpeg/ffmpeg** - Audio/video processing in browser |
| 111 | +- **dexie** - IndexedDB wrapper for local storage |
| 112 | +- **konva / vue-konva** - Canvas rendering for timeline editor |
| 113 | +- **ts-pattern** - Pattern matching |
| 114 | +- **zod** - Runtime type validation |
| 115 | +- **motion-v** - Vue animations |
| 116 | + |
| 117 | +## Nuxt Features |
| 118 | +- Auto-imports enabled for composables, utils, components |
| 119 | +- TypeScript strict mode enabled |
| 120 | +- Pinia for state management |
| 121 | +- Nuxt UI for components |
| 122 | +- i18n for internationalization (en, de) |
| 123 | +- PWA support via @vite-pwa/nuxt |
| 124 | +- Extends GitHub layers: backend_communication, health_check, feedback-control, logger |
| 125 | + |
| 126 | +## Testing |
| 127 | +- No test framework currently configured |
| 128 | +- Tests should be added when implementing new features |
| 129 | + |
| 130 | +## Before Committing |
| 131 | +1. Run `bun run check` - fix all linting issues |
| 132 | +2. Run `bun run build` - ensure production build works |
0 commit comments