🛠️ Editor Setup Guide¶

Optimized development environment configuration for VS Code and Zed editors.

📋 Table of Contents¶

VS Code Setup
Zed Setup
Common Configuration
Quick Actions & Tasks
Debugging Setup
Performance Tips
Troubleshooting

🆚 VS Code Setup¶

📦 Automatic Extension Installation¶

The workspace includes .vscode/extensions.json with recommended extensions. VS Code will prompt you to install them automatically.

Essential Extensions (Auto-installed):

TypeScript & React: ms-vscode.vscode-typescript-next, dsznajder.es7-react-js-snippets
Code Quality: esbenp.prettier-vscode, dbaeumer.vscode-eslint, usernamehw.errorlens
Testing: vitest.explorer
AI & Git: github.copilot, eamodio.gitlens
Styling: bradlc.vscode-tailwindcss

⚙️ Workspace Settings¶

Pre-configured settings in .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  },
  "typescript.preferences.quoteStyle": "double",
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

🎯 Quick Actions¶

Command Palette (Cmd/Ctrl + Shift + P):

Tasks: Run Task - Access all project tasks
TypeScript: Restart TS Server - Fix IntelliSense issues
Developer: Reload Window - Refresh workspace
Preferences: Open Workspace Settings (JSON) - Edit workspace config

Task Shortcuts:

Ctrl+Shift+P → Tasks: Run Task
🚀 Start Development Server
🧪 Run Unit Tests (Watch Mode)
🔧 Fix Code Issues (Format + Lint)
🚀 Deploy to Staging

🐛 Debugging Configuration¶

Pre-configured launch configurations in .vscode/launch.json:

Available Debug Configurations¶

🚀 Debug Next.js (Dev Server) - Full server debugging
🌐 Debug Next.js (Chrome) - Client-side debugging
🔗 Attach to Next.js - Attach to running process
🧪 Debug Unit Tests (Vitest) - Debug specific tests

Quick Debug Actions¶

# Start debugging session
F5                    # Start debugging
Ctrl+Shift+F5        # Restart debugging
Shift+F5             # Stop debugging
F9                   # Toggle breakpoint
F10                  # Step over
F11                  # Step into

📁 File Explorer Enhancements¶

File Nesting (Enabled):

package.json groups package-lock.json, yarn.lock
README.md groups CONTRIBUTING.md, LICENSE
next.config.* groups next-env.d.ts
tsconfig.json groups tsconfig.*.json

Explorer Context Menu:

Right-click folders → "Open in Integrated Terminal"
Right-click .test.ts files → "Debug Test File"

🔧 Integrated Terminal¶

Pre-configured terminals:

Main: Development server (npm run dev)
Test: Test runner (npm run test -- --watch)
Build: Build tasks (npm run build)

Terminal Shortcuts:

Ctrl+`               # Toggle terminal
Ctrl+Shift+`         # Create new terminal
Ctrl+Shift+5         # Split terminal

⚡ Zed Setup¶

🎨 Project Configuration¶

Zed uses .zed/settings.json for project-specific configuration:

{
  "tab_size": 2,
  "format_on_save": "on",
  "code_actions_on_format": {
    "source.organizeImports": true,
    "source.fixAll.eslint": true
  },
  "languages": {
    "TypeScript": {
      "formatter": "prettier"
    },
    "TSX": {
      "formatter": "prettier"
    }
  }
}

🚀 Built-in Tasks¶

Pre-configured tasks in .zed/settings.json:

Available Tasks:

🚀 Start Development Server (npm run dev)
🔨 Build for Production (npm run build)
🧪 Run Tests (npm run test)
🔍 Lint Code (npm run lint)
💅 Format Code (npm run format)
📚 Start Storybook (npm run storybook)
🚀 Deploy to Staging (./scripts/deployment/deploy-staging.sh)

⌨️ Keyboard Shortcuts¶

Task Execution:

Cmd+Shift+P          # Command palette
Cmd+Shift+R          # Run task
Cmd+T                # File finder
Cmd+Shift+F          # Project-wide search
Cmd+J                # Toggle terminal

🤖 AI Assistant Integration¶

Zed AI Features:

Copilot Integration: Built-in GitHub Copilot support
Assistant Panel: Right-side AI chat (if configured)
Inline Suggestions: Real-time code completions

🎯 Language Server Features¶

TypeScript LSP:

Auto-imports with correct relative paths
Real-time type checking
Intelligent refactoring suggestions
Go-to-definition across files

Tailwind CSS LSP:

Class name completions
Hover documentation
CSS-in-JS support (cva, cx functions)

📊 Performance Optimizations¶

File Scanning:

Excludes node_modules, .next, coverage
Optimized for large projects
Fast file search and navigation

🔧 Common Configuration¶

📝 EditorConfig¶

Project includes .editorconfig:

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

🎨 Prettier Configuration¶

Consistent formatting via prettier.config.js:

module.exports = {
  semi: true,
  trailingComma: "es5",
  singleQuote: false,
  printWidth: 80,
  tabWidth: 2,
  useTabs: false,
  plugins: ["prettier-plugin-tailwindcss"],
};

📋 ESLint Configuration¶

Type-safe linting via eslint.config.mjs:

import { fixupConfigRules } from "@eslint/compat";
import nextConfig from "eslint-config-next";

export default [
  ...fixupConfigRules(nextConfig),
  {
    rules: {
      "@typescript-eslint/no-unused-vars": "error",
      "@typescript-eslint/no-explicit-any": "error",
      "react-hooks/exhaustive-deps": "warn",
    },
  },
];

🎮 Quick Actions & Tasks¶

🚀 Development Workflow¶

Start Development:

# VS Code: Ctrl+Shift+P → "Tasks: Run Task" → "🚀 Start Development Server"
# Zed: Cmd+Shift+P → "task: start development server"
# Terminal: npm run dev

Run Tests:

# Unit tests (watch mode)
npm run test -- --watch

# Coverage report
npm run test:coverage

Code Quality:

# Fix formatting and linting
# VS Code: Task "🔧 Fix Code Issues"
npm run format && npm run lint

# Type checking
npm run type-check

# Full quality check
# VS Code: Task "✅ Full Quality Check"

🔄 Git Workflow Integration¶

Pre-commit Hooks (Husky):

Automatic linting and formatting
Type checking before commits
Test validation

GitLens (VS Code) Features:

Inline blame annotations
File history and comparisons
Branch and stash management

🚀 Deployment¶

Quick Deploy:

# VS Code: Task "🚀 Deploy to Staging"
# Terminal:
cd scripts/deployment
./deploy-staging.sh

🐛 Debugging Setup¶

🔍 Debugging Next.js Applications¶

Server-Side Debugging¶

Start Debug Session:
VS Code: F5 → Select "🚀 Debug Next.js (Dev Server)"
Zed: Use integrated terminal with --inspect flag
Set Breakpoints:
API routes: src/app/api/**/*.ts
Server components: src/app/**/*.tsx
Services: src/lib/services/**/*.ts
Debug Console:
Inspect variables
Evaluate expressions
Call stack navigation

Client-Side Debugging¶

Chrome DevTools Integration:
VS Code: F5 → Select "🌐 Debug Next.js (Chrome)"
Automatic source map resolution
React DevTools extension
Common Debug Points:
React components: src/components/**
Custom hooks: src/lib/hooks/**
Client-side utilities: src/lib/utils/**

🧪 Testing & Debugging¶

Unit Test Debugging¶

VS Code:

Open test file
F5 → Select "🎯 Debug Current Test File"
Set breakpoints in test or source code

Zed:

Use terminal: npm run test -- --inspect-brk <file>
Attach debugger to process

⚡ Performance Tips¶

🚀 Editor Performance¶

VS Code Optimizations¶

Disable Unused Extensions:

{
  "extensions.autoUpdate": false,
  "extensions.ignoreRecommendations": true
}

Optimize TypeScript:

{
  "typescript.disableAutomaticTypeAcquisition": true,
  "typescript.preferences.includePackageJsonAutoImports": "off"
}

File Watching:

{
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/node_modules/**": true,
    "**/.next/**": true
  }
}

Zed Optimizations¶

File Scanning: Pre-configured exclusions
LSP Settings: Optimized for large projects
UI Responsiveness: Native performance benefits

🔧 Development Server Performance¶

Turbopack Configuration:

# Already enabled in package.json
npm run dev  # Uses --turbopack flag
npm run build  # Uses --turbopack flag

Memory Usage:

VS Code: Monitor via Task Manager
Zed: Generally lower memory footprint
Node.js: Use --max-old-space-size=4096 if needed

🔧 Troubleshooting¶

🚨 Common Issues¶

TypeScript Issues¶

Problem: IntelliSense not working

# VS Code
Cmd+Shift+P → "TypeScript: Restart TS Server"

# Zed
Restart language server via command palette

Problem: Import suggestions not working

// Add to settings.json
{
  "typescript.suggest.autoImports": true,
  "typescript.preferences.importModuleSpecifier": "relative"
}

ESLint Issues¶

Problem: Linting not working on save

{
  "eslint.format.enable": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

Prettier Issues¶

Problem: Formatting not consistent

# Check configuration
npx prettier --check .

# Fix all files
npx prettier --write .

🧪 Test Issues¶

Vitest Issues¶

Problem: Tests not running in VS Code

Install Vitest extension
Configure test runner: Cmd+Shift+P → "Test: Configure"

🚀 Deployment Issues¶

Problem: Build failures

# Clean build
rm -rf .next
npm run build

# Check environment variables
npm run type-check

📱 Extension Conflicts¶

VS Code Extension Issues:

Disable all extensions
Enable one by one to identify conflicts
Check extension compatibility

Recommended Extension Combination:

Keep core language extensions
Use official Microsoft extensions
Avoid duplicate functionality

🎯 Best Practices¶

📁 Workspace Organization¶

Use Workspace Folders: Organize large projects
Configure File Nesting: Reduce clutter
Set Up Tasks: Automate common operations
Configure Debugging: Set up launch configurations

🔄 Workflow Integration¶

Git Integration: Use built-in Git features
Task Automation: Leverage editor tasks
Testing Integration: Use test explorers
AI Assistance: Configure Copilot/Assistant

🎨 Code Quality¶

Format on Save: Consistent formatting
Lint on Save: Catch issues early
Auto Imports: Organize imports
Type Checking: Enable strict mode

📚 Additional Resources¶

📖 Documentation¶

VS Code: Official Documentation
Zed: Editor Guide
TypeScript: VS Code TypeScript

🎓 Learning Resources¶

VS Code Tips: VS Code Can Do That
Zed Features: Zed Blog
Debugging Guide: Next.js Debugging

🤖 AI Integration¶

GitHub Copilot: Documentation
Zed Assistant: Configuration Guide

Happy coding! 🚀

This guide is regularly updated to reflect the latest editor features and project requirements.