Dev Command

Overview

The dev command starts your NitroStack server in development mode with hot reload, Studio testing environment, and widget development server.

Usage

nitrostack dev [options]

Options

Option	Description	Default
`--port <number>`	Studio port	3000
`--no-open`	Don't open browser	false

What It Does

When you run nitrostack dev, it:

Starts MCP Server
- Runs your server via stdio transport
- Watches for file changes
- Auto-reloads on changes
Starts Studio
- Next.js dev server on port 3000
- Visual testing environment
- AI chat integration
- Widget preview
Starts Widget Server
- Next.js dev server on port 3001
- Hot reload for widgets
- React Fast Refresh
Opens Browser
- Automatically opens Studio at http://localhost:3000

Architecture

┌─────────────────────────────────┐
│      Studio (port 3000)         │
│   - Chat interface              │
│   - Tool testing                │
│   - Resource browser            │
└────────────┬────────────────────┘
             │
             ├─── stdio ───────────┐
             │                     │
             │                ┌────▼─────┐
             │                │   MCP    │
             │                │  Server  │
             │                └────┬─────┘
             │                     │
             │                ┌────▼─────┐
             │                │ Database │
             │                └──────────┘
             │
        ┌────▼─────┐
        │ Widgets  │
        │ (3001)   │
        └──────────┘

Examples

Basic Usage

nitrostack dev

Opens Studio at http://localhost:3000

Custom Port

nitrostack dev --port 8080

Opens Studio at http://localhost:8080 Widgets at http://localhost:8081

Don't Open Browser

nitrostack dev --no-open

Manually navigate to http://localhost:3000

Features

Hot Reload

Changes to your code automatically reload the server:

Watched Files:

src/**/*.ts - TypeScript source
src/**/*.js - JavaScript source
.env - Environment variables

Not Watched:

node_modules/
dist/
logs/

Studio Integration

Studio provides:

🤖 AI chat (OpenAI GPT-4, Gemini 2.0 Flash)
🔧 Manual tool testing
📊 Resource browser
🎨 Widget preview
🌓 Dark/light theme

Widget Hot Reload

Widgets support React Fast Refresh:

Save changes to see updates instantly
State preserved during reload
Fast iteration cycle

Environment Variables

Configure dev mode via .env:

# Studio port
STUDIO_PORT=3000

# Widget port
WIDGET_PORT=3001

# Open browser
OPEN_BROWSER=true

# Log level
LOG_LEVEL=info

# Database
DATABASE_PATH=./data/dev.db

Development Workflow

Start Dev Mode
```
nitrostack dev
```
Make Changes
- Edit tools in src/modules/*/tools.ts
- Edit widgets in src/widgets/app/
- Edit services in src/services/
Test in Studio
- Use AI chat to test tools
- Execute tools manually
- Preview widgets
Iterate
- Changes auto-reload
- Test again
- Repeat

Troubleshooting

Port Already in Use

Error: listen EADDRINUSE: address already in use :::3000

Solution:

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
nitrostack dev --port 8080

Studio Not Connecting

Error: "Not connected" in Studio

Solution:

# Check MCP server logs
tail -f logs/server.log

# Restart dev mode
nitrostack dev

# Check environment variables
cat .env

Widgets Not Loading

Error: 500 error when loading widgets

Solution:

# Check widget server
curl http://localhost:3001

# Rebuild widgets
npm run widgets:build

# Check widget route matches tool
# Tool: @Widget('product-card')
# Route: src/widgets/app/product-card/page.tsx

Hot Reload Not Working

Solution:

# Ensure watching is enabled
# Check file permissions
ls -la src/

# Restart dev mode
nitrostack dev

# Check for syntax errors
npm run build

Database Locked

Error: SQLITE_BUSY: database is locked

Solution:

# Close other connections
# Kill other processes
ps aux | grep node

# Remove lock file
rm data/dev.db-wal
rm data/dev.db-shm

Performance Tips

1. Exclude Large Directories

Add to .gitignore:

node_modules/
dist/
.next/
logs/
data/*.db

2. Use Incremental Compilation

In tsconfig.json:

{
  "compilerOptions": {
    "incremental": true
  }
}

3. Limit Watching

Create .watchignore:

node_modules/
dist/
.next/
*.log
*.db

4. Use SSD

Development is faster on SSD storage.

Studio Features

Chat Interface

Test tools naturally:

You: Show me products in Electronics
AI: [Calls browse_products tool]
    [Renders products-grid widget]
    Here are the electronics...

Tool Testing

Manual execution:

Select tool
Fill form
Execute
See response
View widget

Resource Browser

Browse all resources:

View URIs
Execute handlers
Preview data

Theme Toggle

Switch between dark/light themes with one click.

Advanced Usage

Add Widget Dependencies

To add a new package to your widgets (e.g., Material UI):

npm run widget add @mui/material @emotion/react @emotion/styled

This runs npm install in the widgets directory with your specified packages.

Multiple Databases

Use different databases for dev:

# .env.development
DATABASE_PATH=./data/dev.db

# .env.test
DATABASE_PATH=./data/test.db

Debug Mode

Enable verbose logging:

LOG_LEVEL=debug nitrostack dev

Custom Middleware

Add development middleware:

if (process.env.NODE_ENV === 'development') {
  server.use(debugMiddleware);
}

Next Steps

Pro Tip: Keep Studio open while coding - it automatically refreshes when your server reloads!