Skip to main content
The pnpm dev command starts a development server with Hot Module Replacement (HMR) support. When you modify code, changes are instantly reflected without restarting the server.

​
Basic Usage

pnpm dev
Once the development server starts, you can use the following features:
  • Auto-restart: Automatic server restart on code changes
  • TypeScript support: Run .ts files directly
  • Source map support: Accurate line numbers on errors
  • Keyboard shortcuts: Shortcuts for quick actions

​
Subcommands

You can run API and Web separately.
CommandDescription
pnpm devIntegrated API + Web dev server (default)
pnpm dev apiAPI-only dev server (integrated web server disabled)
pnpm dev webStandalone Vite dev server
Running API and Web in separate terminals: 
# Terminal 1: API server
pnpm dev api

# Terminal 2: Web dev server
pnpm dev web
pnpm dev web passes arguments after -- directly to Vite. For example, to change the port:
pnpm dev web -- --port 5174

​
How It Works

pnpm dev internally uses the following tools:
ToolRoleProvider
@sonamu-kit/hmr-runnerHMR execution engineSonamu
@sonamu-kit/ts-loaderTypeScript loaderSonamu
@sonamu-kit/hmr-hookHMR hookSonamu
Important: These packages are automatically provided by Sonamu, so no separate installation is needed.

​
Execution Process

  1. Execute src/index.ts as entry point
  2. Transform and execute TypeScript files immediately
  3. Detect file changes
  4. Replace only changed modules (HMR)
  5. Full restart only when necessary

​
Keyboard Shortcuts

You can use the following shortcuts while the development server is running:
ShortcutFunctionDescription
rRestartManually restart the server
cClear screenClear the terminal screen
fForce restartDelete sonamu.lock file and restart
EnterTestKey binding test
Ctrl+F Ctrl+FUpdateGit pull, install packages, build, and restart

​
Shortcut Usage Examples

Server restart: 
# While development server is running in terminal
[Server running...]

# Press 'r' key
r

# Server restarts
πŸ”„ Restarting server...
Force restart (cache reset): 
# Press 'f' key
f

# Delete sonamu.lock and restart
πŸ—‘οΈ  Removing sonamu.lock...
πŸ”„ Restarting server...

​
Environment Variables

The development server automatically sets the following environment variables:
VariableValueDescription
NODE_ENVdevelopmentDevelopment mode indicator
HOTyesHMR activation flag
API_ROOT_PATHProject pathHMR root directory
You can check environment variables in code: 
if (process.env.NODE_ENV === 'development') {
  console.log('Development mode');
}

if (process.env.HOT === 'yes') {
  console.log('HMR is enabled');
}

​
How HMR Works

​
Cases That Auto-restart

The server automatically restarts when modifying these files:
  • Entity files (*.entity.ts)
  • Model files (*.model.ts)
  • Config files (sonamu.config.ts)
  • Migration files
// Modifying user.model.ts
class UserModelClass extends BaseModel {
  @api({ httpMethod: "GET" })
  async findById(id: number) {
    return this.getPuri("r").where("id", id).first();
  }
}

// Save file β†’ Server auto-restarts

​
Cases Reflected Instantly (HMR)

Changes to these files are reflected instantly without server restart:
  • General business logic
  • Utility functions
  • Service layer
// Modifying utils/helper.ts
export function formatDate(date: Date) {
  return date.toISOString();
}

// Save file β†’ Instantly reflected (no restart)

​
Troubleshooting

​
Server Won’t Start

Problem: Port already in use 
Error: listen EADDRINUSE: address already in use :::3000
Solution: 
# Kill process using the port
lsof -ti:3000 | xargs kill -9

# Restart
pnpm dev

​
HMR Not Working

Problem: Code changes not reflected Solution: 
# 1. Force restart (f key)
f

# 2. Or manual restart
pnpm dev

​
TypeScript Errors

Problem: Server won’t start due to type errors Solution: 
# Type check
pnpm tsc --noEmit

# Fix issues and restart
pnpm dev

​
Practical Tips

​
1. Fast Development Cycle

Modify code and test immediately: 
// Modify API endpoint
@api({ httpMethod: "GET" })
async getUsers() {
  return this.findMany({ num: 10, page: 1 });
}

// Save β†’ Auto-restart β†’ Test immediately

​
2. Check Logs

Development server outputs all logs to console: 
console.log('User query:', user);
logger.info('API call', { method, path });
logger.error('Error occurred', { error });

​
3. Debugging

Source maps are enabled for accurate line numbers: 
Error: User not found
    at UserModel.findById (user.model.ts:42:15)
    at API.handler (index.ts:28:20)

​
Differences from Production

FeatureDevelopment ServerProduction
HMRβœ… Enabled❌ Disabled
TypeScriptImmediate executionCompilation needed
Source mapsOriginal filesCompressed files
PerformanceSlowerFaster
Error displayDetailedBrief
Don’t use development server in production!
  • Slow performance
  • High memory usage
  • Security vulnerabilities
Use pnpm build then pnpm start for production.

​
Next Steps

build

Build for production

HMR

Learn more about HMR system