/start-viewer

Start component viewer for: $ARGUMENTS

Start CODITECT Component Viewer from any frontend directory. Automatically discovers React/Vue/Svelte components in the current folder, registers them with the viewer, and launches the development server.

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

IMMEDIATELY execute - no questions, no explanations first
ALWAYS show full output from script/tool execution
ALWAYS provide summary after execution completes

DO NOT:

Say "I don't need to take action" - you ALWAYS execute when invoked
Ask for confirmation unless requires_confirmation: true in frontmatter
Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Arguments

$ARGUMENTS - Viewer Configuration (optional)

Specify viewer startup options:

Auto-discovery: No arguments - discovers all components in current folder
Specific component: "MyComponent.jsx" or "Button.tsx"
With port: "--port 3000" or "port 8080"
Watch mode: "--watch" for auto-reload on new components
No browser: "--no-open" to skip browser launch

Default Behavior

If no arguments:

Auto-discovers all React/Vue/Svelte components
Starts viewer on default port (3000)
Opens browser automatically
Watches for new components

Usage

# Start viewer with auto-discovery
/start-viewer

# Start viewer for specific component
/start-viewer MyComponent.jsx

# Start viewer with custom port
/start-viewer --port 3000

# Start viewer without auto-opening browser
/start-viewer --no-open

# Start viewer in watch mode (auto-add new components)
/start-viewer --watch

How It Works

Component Discovery:
- Scans current directory recursively
- Finds all .jsx, .tsx, .vue, .svelte files
- Excludes node_modules, dist, build directories
- Filters out test files (*.test.*, *.spec.*)
Component Registration:
- Copies discovered components to viewer's components/ directory
- Updates registry.json with component metadata
- Preserves directory structure for organization
Viewer Launch:
- Installs dependencies if needed (first run)
- Starts Vite dev server
- Opens browser to http://localhost:5173
- Enables hot module replacement
Watch Mode (Optional):
- Monitors directory for new components
- Automatically registers new files
- Updates viewer in real-time

Examples

Example 1: Start from React Project

# Navigate to your React project
cd ~/projects/my-react-app/src/components

# Start viewer (discovers all components)
/start-viewer

# Output:
# 🔍 Discovering components in /Users/you/projects/my-react-app/src/components...
# ✅ Found 12 components
# 📝 Registering components with viewer...
# 📦 Installing dependencies...
# 🚀 Starting CODITECT Component Viewer...
#
# ➜ Local:   http://localhost:5173/
# ➜ Components registered:
#    - UserCard
#    - ProductList
#    - SearchBar
#    ... (9 more)

Example 2: View Single Component

# From component directory
cd ~/projects/my-app/src/components

# View specific component
/start-viewer UserProfile.jsx

# Output:
# ✅ Registered UserProfile
# 🚀 Starting viewer on http://localhost:5173/

Example 3: Custom Configuration

# Start with custom port and watch mode
/start-viewer --port 3001 --watch

# Output:
# 👀 Watch mode enabled - monitoring for new components
# 🚀 Starting viewer on http://localhost:3001/
# ✅ 15 components registered

Command Options

Option	Alias	Description	Default
`--port <number>`	`-p`	Custom port for dev server	5173
`--no-open`		Don't open browser automatically	false
`--watch`	`-w`	Watch for new components	false
`--pattern <glob>`		Custom file pattern	`*/.{jsx,tsx,vue,svelte}`
`--exclude <pattern>`		Exclude files matching pattern	`node_modules,dist,build`
`--help`	`-h`	Show help message

Configuration File

Create .coditect/viewer.config.json in your project root:

{
  "port": 5173,
  "autoOpen": true,
  "watch": false,
  "patterns": [
    "src/**/*.jsx",
    "src/**/*.tsx",
    "components/**/*.jsx"
  ],
  "exclude": [
    "**/*.test.*",
    "**/*.spec.*",
    "**/node_modules/**",
    "**/dist/**"
  ],
  "viewer": {
    "title": "My Project Components",
    "theme": "light",
    "layout": "grid"
  }
}

Integration with CODITECT Agents

The viewer automatically integrates with CODITECT's agent system:

# Agent can invoke viewer
Task(
    subagent_type="frontend-development-agent",
    prompt="Start component viewer for current directory"
)

# Agent discovers and tests components
Task(
    subagent_type="frontend-development-agent",
    prompt="""
    1. Discover all components in src/components
    2. Start viewer
    3. Generate Playwright tests for each component
    4. Run accessibility audits
    5. Report results
    """
)

Environment Variables

# Custom viewer location
export CODITECT_VIEWER_PATH=/custom/path/to/viewer

# Custom port
export VIEWER_PORT=3000

# Disable auto-open
export VIEWER_OPEN=false

# Enable verbose logging
export VIEWER_DEBUG=true

Troubleshooting

Components Not Discovered

Problem: /start-viewer doesn't find components

Solution:

# Check file patterns
/start-viewer --pattern "**/*.jsx" --verbose

# Verify file extensions
ls -la *.jsx *.tsx

# Check exclude patterns
cat .coditect/viewer.config.json

Port Already in Use

Problem: Port 5173 is already taken

Solution:

# Use different port
/start-viewer --port 3000

# Or kill existing process
lsof -ti:5173 | xargs kill -9

Dependencies Not Installed

Problem: Viewer fails to start (missing deps)

Solution:

# Install viewer dependencies
cd $CODITECT_CORE/tools/component-viewer
npm install

# Then retry
/start-viewer

Components Not Hot Reloading

Problem: Changes don't reflect in viewer

Solution:

# Use watch mode
/start-viewer --watch

# Or restart viewer
# Ctrl+C to stop, then
/start-viewer

Behind the Scenes

When you run /start-viewer, this script executes:

#!/bin/bash
# Simplified version of what happens

# 1. Find coditect-core
CODITECT_CORE=$(find ~/.coditect -name "coditect-core" | head -1)
VIEWER_PATH="$CODITECT_CORE/tools/component-viewer"

# 2. Discover components in current directory
find . -name "*.jsx" -not -path "*/node_modules/*" > /tmp/components.txt

# 3. Copy components to viewer
while read component; do
  cp "$component" "$VIEWER_PATH/components/"
  # Update registry.json
done < /tmp/components.txt

# 4. Start viewer
cd "$VIEWER_PATH"
npm run dev

Advanced Usage

Custom Component Discovery

// .coditect/viewer-discover.js
module.exports = {
  // Custom component filter
  filter: (filePath) => {
    return filePath.endsWith('.jsx') &&
           !filePath.includes('.test.') &&
           !filePath.includes('__mocks__');
  },

  // Extract component metadata
  metadata: (filePath, content) => {
    // Parse component for props, name, etc.
    return {
      name: extractComponentName(content),
      props: extractProps(content),
      hasTests: existsSync(filePath.replace('.jsx', '.test.jsx'))
    };
  }
};

Integration with Build Tools

# Add to package.json scripts
{
  "scripts": {
    "dev": "vite",
    "view": "/start-viewer --watch",
    "test:visual": "/start-viewer && npm run playwright"
  }
}

# Then run
npm run view

CI/CD Integration

# .github/workflows/visual-tests.yml
name: Visual Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Start Viewer
        run: /start-viewer --no-open --port 3000 &
      - name: Wait for Viewer
        run: npx wait-on http://localhost:3000
      - name: Run Visual Tests
        run: npm run test:visual

/test-component - Run Playwright tests on viewer
/view - Alias for /start-viewer
/stop-viewer - Stop running viewer instance
/list-components - List all registered components

Performance Tips

Limit Discovery Scope:

# Instead of scanning entire project
cd src/components
/start-viewer

Use Specific Patterns:

# Only discover specific directories
/start-viewer --pattern "src/components/**/*.jsx"

Exclude Large Directories:

# Exclude slow directories
/start-viewer --exclude "node_modules,dist,build,coverage"

Security Considerations

Viewer only runs on localhost (not exposed externally)
Component paths are validated before copying
No external network calls during discovery
Git-ignored sensitive files are excluded automatically

Future Enhancements

Storybook integration
Component search and filtering
Props playground (interactive prop editor)
Dark mode support
Component templates
Remote collaboration (share viewer URL)
Component dependency graph
Performance profiling per component

Success Output

When component viewer starts:

✅ COMMAND COMPLETE: /start-viewer
Components: N discovered
Port: XXXX
URL: http://localhost:XXXX
Watch: enabled|disabled
Browser: opened|skipped

Completion Checklist

Before marking complete:

Failure Indicators

This command has FAILED if:

❌ No components found
❌ Port already in use
❌ Dependencies missing
❌ Server failed to start

When NOT to Use

Do NOT use when:

No frontend components exist
Backend-only project
Components are binary/compiled

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Scan entire project	Slow discovery	Limit to component directories
Skip node_modules	Include unnecessary files	Use default exclusions
No watch mode	Miss new components	Use --watch for development

Principles

This command embodies:

#3 Complete Execution - Full discovery and launch
#1 Recycle → Extend - Reuses existing viewer

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Status: Production Ready Last Updated: 2025-12-02 Maintainer: CODITECT Core Team Related: frontend-development-agent, component-viewer skill

System Prompt​

Arguments​

$ARGUMENTS - Viewer Configuration (optional)​

Default Behavior​

Usage​

How It Works​

Examples​

Example 1: Start from React Project​

Example 2: View Single Component​

Example 3: Custom Configuration​

Command Options​

Configuration File​

Integration with CODITECT Agents​

Environment Variables​

Troubleshooting​

Components Not Discovered​

Port Already in Use​

Dependencies Not Installed​

Components Not Hot Reloading​

Behind the Scenes​

Advanced Usage​

Custom Component Discovery​

Integration with Build Tools​

CI/CD Integration​

Related Commands​

Performance Tips​

Security Considerations​

Future Enhancements​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

System Prompt

Arguments

$ARGUMENTS - Viewer Configuration (optional)

Default Behavior

Usage

How It Works

Examples

Example 1: Start from React Project

Example 2: View Single Component

Example 3: Custom Configuration

Command Options

Configuration File

Integration with CODITECT Agents

Environment Variables

Troubleshooting

Components Not Discovered

Port Already in Use

Dependencies Not Installed

Components Not Hot Reloading

Behind the Scenes

Advanced Usage

Custom Component Discovery

Integration with Build Tools

CI/CD Integration

Related Commands

Performance Tips

Security Considerations

Future Enhancements

Success Output

Completion Checklist

Failure Indicators

When NOT to Use

Anti-Patterns (Avoid)

Principles