Execute Code Playground Development
Develop features and fix bugs for Execute, a web-based code playground with dual editing modes: a classic HTML/CSS/JavaScript split-pane editor and a full React development environment.
Context
Execute is built with React 19, TypeScript, Vite, TailwindCSS 4.x, CodeMirror 6, Sandpack, and Convex for real-time database sync. It provides live preview capabilities and persistent project storage.
Step-by-Step Instructions
1. Understand the Project Structure
Read the key files to understand the architecture:
`src/main.tsx` - Router setup with mode switching via `?mode=react` query param`src/App.tsx` - Classic editor mode (HTML/CSS/JS panes with CodeMirror)`src/ReactEditor.tsx` - React mode using Sandpack from CodeSandbox`src/components/HomePage.tsx` - Landing page with project creation`convex/schema.ts` - Database schema for projects table`convex/projects.ts` - CRUD mutations and queries2. Set Up Development Environment
```bash
Install dependencies if needed
npm install
Start development server
npm run dev
Opens at http://localhost:5173
In parallel, ensure Convex is running
npx convex dev
```
3. Identify the Feature or Bug
Determine whether the task involves:
**Classic mode** (HTML/CSS/JS editor) - modify `src/App.tsx`**React mode** (Sandpack) - modify `src/ReactEditor.tsx`**Database/persistence** - modify `convex/schema.ts` or `convex/projects.ts`**UI components** - check `src/components/ui/` (shadcn/ui)**Routing** - modify `src/main.tsx`**Theme/styling** - edit `src/index.css` (TailwindCSS 4.x with `@theme inline`)4. Make Code Changes
**For CodeMirror editor features:**
Extend editor extensions in `App.tsx`Available extensions: vim mode, Emmet, language support (HTML/CSS/JS/JSX)Custom vim commands use `CodeMirror.commands`**For preview generation (classic mode):**
Modify iframe HTML generation logic in `App.tsx`Structure: `<!DOCTYPE html>` with head (CSS, optional Tailwind CDN) and body (HTML + script tag for JS)**For React mode:**
Configure Sandpack in `ReactEditor.tsx`Manage `reactFiles` structure in Convex database**For database changes:**
Update schema in `convex/schema.ts`Add/modify mutations and queries in `convex/projects.ts`Schema uses Convex validators (`v.string()`, `v.number()`, etc.)5. Test the Changes
```bash
Run linter
npm run lint
Build to check TypeScript errors
npm run build
Test in browser
npm run dev
```
**Testing checklist:**
Verify editor functionality in both modesTest keyboard shortcuts (Ctrl/Cmd+S, Alt+1/2/3, vim `:w`)Check live preview updatesVerify project save/load from ConvexTest theme switching (light/dark)Validate localStorage preferences persist6. Handle TailwindCSS 4.x Specifics
TailwindCSS 4.x uses native CSS (no PostCSS config):
```css
@import "tailwindcss";
@theme inline {
/* Custom theme values here */
}
```
Do NOT create `tailwind.config.js` or `postcss.config.js`.
7. Follow TypeScript Conventions
Strict mode is enabledUse path alias `@/*` for imports from `./src/*`Type all props and state explicitlyCheck types with `npm run build` before committing8. Implement New Features
**Example: Adding a new keyboard shortcut**
1. Add key handler in `App.tsx` or `ReactEditor.tsx`
2. Update keyboard shortcuts documentation
3. Store preference in localStorage if user-configurable
**Example: Adding a new editor language**
1. Import language extension from `@codemirror/lang-*`
2. Add to CodeMirror extensions array
3. Update UI to show new language option
**Example: Adding a database field**
1. Update schema in `convex/schema.ts`
2. Add mutation/query in `convex/projects.ts`
3. Update TypeScript types
4. Modify UI components to use new field
9. Important Implementation Constraints
**Data persistence**: Use Convex mutations, not direct database writes**Preview updates**: Classic mode uses iframe src refresh; React mode uses Sandpack hot reload**Theme colors**: Use OKLCH color space with CSS custom properties**Routing**: Projects accessible at `/:projectId` URLs**User preferences**: Store in localStorage (vim mode, theme, Tailwind toggle)10. Production Build
```bash
Create optimized build
npm run build
Preview production build
npm run preview
```
Key Technical Details
**Data Flow:**
1. User edits code → local React state buffers
2. User saves (Ctrl+S or vim `:w`) → Convex mutation
3. Preview updates automatically (iframe refresh or Sandpack)
4. Projects persist with unique IDs
**CodeMirror Configuration:**
Extensions: language support, vim mode, Emmet, themesCustom vim `:w` command mapped to save functionTab key handling for proper indentation**Convex Schema:**
```typescript
projects: defineTable({
html: v.string(),
css: v.string(),
js: v.string(),
reactFiles: v.optional(v.any()),
createdAt: v.number(),
})
```
Common Tasks
**Add editor feature**: Extend CodeMirror extensions in `App.tsx`**Modify preview**: Update iframe generation logic in `App.tsx`**Change database**: Update `convex/schema.ts` and run `npx convex dev`**Customize theme**: Edit CSS variables in `src/index.css`**Configure React mode**: Modify Sandpack setup in `ReactEditor.tsx`Constraints
Never create PostCSS or Tailwind config files (TailwindCSS 4.x uses native CSS)Always validate TypeScript types with build commandTest both editor modes when making changesPreserve vim mode and Emmet functionalityMaintain keyboard shortcut compatibility