Development Workflow

Development Server

Start the Vite development server with hot module replacement (HMR):

npm run dev

The development server will start on http://localhost:5173 by default.

Dev Server Features

Hot Module Replacement (HMR): Changes appear instantly without full page reload
Fast Startup: Vite uses native ES modules for lightning-fast cold starts
Optimized Dependencies: Pre-bundled with esbuild for performance
Error Overlay: Clear error messages displayed in the browser

Available Scripts

All npm scripts are defined in package.json:

Development

npm run dev

Starts the Vite development server with HMR enabled. The server automatically:

Watches for file changes
Recompiles modified modules
Updates the browser without full reload
Preserves application state when possible

Production Build

npm run build

Builds the application for production. This command:

Type Checks: Runs tsc -b to validate TypeScript types
Builds: Runs vite build to create optimized production bundle
Output: Generates files in the dist/ directory

The build will fail if there are any TypeScript type errors. Fix all type errors before deploying.

Preview Production Build

npm run preview

Locally preview the production build before deploying. This:

Serves the built files from dist/
Runs on a local server (default: http://localhost:4173)
Simulates production environment

The preview server is not designed for production use. Use proper hosting services for deployment.

Linting

npm run lint

Runs ESLint to check code quality and enforce standards. The linter checks:

TypeScript type usage
React Hooks rules
React Fast Refresh compatibility
Code style consistency

Hot Module Replacement (HMR)

Vite provides fast and reliable HMR out of the box:

How HMR Works

File Change Detection: Vite watches for changes in your source files
Module Graph Update: Only the changed module and its dependencies are updated
State Preservation: React Fast Refresh preserves component state when possible
Instant Updates: Changes appear in milliseconds

HMR with React

The @vitejs/plugin-react enables React Fast Refresh:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
})

When HMR Triggers Full Reload

Some changes require a full page reload:

Changes to index.html
Changes to Vite configuration files
Changes to environment variables
Syntax errors in modules

Build Process

The production build process optimizes your application for deployment.

Build Command Breakdown

tsc -b && vite build

TypeScript Type Checking

tsc -b performs incremental type checking across project references:

Checks tsconfig.app.json (application code)
Checks tsconfig.node.json (Vite config)
Uses cached build info from node_modules/.tmp/
Fails the build if type errors are found

Vite Build

vite build creates the production bundle:

Bundles JavaScript with Rollup
Processes CSS with PostCSS and TailwindCSS
Optimizes assets (images, fonts, etc.)
Generates hashed filenames for cache busting
Creates source maps for debugging

Output Generation

Build artifacts are output to dist/:

index.html - Entry point
assets/*.js - JavaScript bundles
assets/*.css - Compiled stylesheets
Static assets copied from public/

Build Output Structure

dist/
├── index.html
├── assets/
│   ├── index-[hash].js
│   ├── index-[hash].css
│   └── [other-assets]
└── [public-files]

Build Optimizations

Vite automatically applies production optimizations:

Optimization	Description
Code Splitting	Splits code into smaller chunks for faster loading
Tree Shaking	Removes unused code from the bundle
Minification	Compresses JavaScript and CSS
Asset Hashing	Adds content hashes to filenames for caching
CSS Extraction	Extracts CSS into separate files
Source Maps	Generates source maps for debugging

Typical Development Cycle

Start Dev Server

npm run dev

Open browser to http://localhost:5173

Make Changes

Edit React components in src/:

Changes appear instantly via HMR
Component state is preserved
Console shows any errors

Check Code Quality

npm run lint

Fix any linting errors or warnings

Build for Production

npm run build

Ensure TypeScript types are valid and build succeeds

Preview Build

npm run preview

Test the production build locally

Best Practices

Keep Dev Server Running

Leave npm run dev running while developing for instant feedback. HMR works best when the dev server stays active.

Fix Type Errors Early

TypeScript errors will prevent production builds. Use your editor’s TypeScript integration to catch errors as you code.

Run Linter Regularly

Run npm run lint before committing code. This catches common React and TypeScript issues early.

Test Production Builds

Always run npm run build && npm run preview before deploying to catch production-only issues.

Performance Tips

Faster Development

Use Chrome DevTools: Enable React DevTools extension for better debugging
Leverage HMR: Avoid full page reloads by keeping component state pure
Code Splitting: Use dynamic imports for large dependencies

// Lazy load heavy components
const HeavyComponent = lazy(() => import('./HeavyComponent'))

Faster Builds

Reduce Dependencies: Remove unused npm packages
Optimize Images: Compress images before adding to public/
Use Production Mode: NODE_ENV=production enables optimizations

Troubleshooting

Dev Server Won’t Start

Port Conflict
Permission Issues
Cache Issues

If port 5173 is in use, specify a different port:

npm run dev -- --port 3000

On Linux/macOS, ensure proper permissions:

chmod -R u+w node_modules

Clear Vite cache and restart:

rm -rf node_modules/.vite
npm run dev

HMR Not Working

Check Browser Console: Look for HMR connection errors
Verify File Watcher: Ensure your OS supports file watching
Check Import Paths: Incorrect imports can break HMR
Restart Dev Server: Sometimes a restart fixes the issue

Build Failures

TypeScript Errors

# See detailed type errors
npx tsc --noEmit

Fix all type errors before building. Common issues:

Missing type definitions
Incorrect prop types
Unused variables (with strict mode enabled)

Out of Memory

For large projects, increase Node memory:

NODE_OPTIONS="--max-old-space-size=4096" npm run build

Module Resolution Errors

Ensure all imports are correct:

Check file extensions in imports
Verify package is installed
Clear node_modules and reinstall

Next Steps

Configuration

Customize Vite, TypeScript, ESLint, and TailwindCSS settings

Setup

Review installation and dependency requirements

Get Started

Backend

Frontend