Skip to main content

​
Overview

The preview command allows you to test your production build locally before deploying it to a live environment. This is a critical step to catch any issues that might only appear in production builds.

​
Preview Command

After building your application with npm run build, start the preview server: 
npm run preview
This command is defined in package.json:
package.json
{
  "scripts": {
    "preview": "vite preview"
  }
}
You must run npm run build before using npm run preview. The preview server serves the built files from the dist/ directory.

​
How Preview Works

1

Build the Application

First, create a production build:
npm run build
This generates optimized files in the dist/ directory.
2

Start Preview Server

Start the local preview server:
npm run preview
The server typically starts on http://localhost:4173.
3

Test the Application

Open your browser and navigate to the preview URL. Test all functionality as if it were in production.

​
Preview Server Details

The vite preview command starts a local static file server that serves your production build:
  • Default port: 4173
  • Serves from: dist/ directory
  • MIME types: Proper content-type headers for all assets
  • HTTP only: No HTTPS by default (can be configured)
Terminal Output
> vite preview

  ➜  Local:   http://localhost:4173/
  ➜  Network: http://192.168.1.100:4173/
  ➜  press h + enter to show help

​
When to Use Preview vs Dev

Development Server

Use for active development
npm run dev
  • Fast Hot Module Replacement
  • Source maps for debugging
  • Development-only warnings
  • Not optimized
  • Runs on port 5173

Preview Server

Use for testing production builds
npm run preview
  • Serves optimized build
  • Production environment
  • Tests actual deployment code
  • Minified and bundled
  • Runs on port 4173

​
What to Test in Preview

When testing your production build, verify:

​
Functionality

  • All routes and navigation work correctly
  • Forms submit and validate properly
  • API calls function as expected
  • State management behaves correctly
  • Authentication/authorization flows work

​
Performance

  • Page load times are acceptable
  • Images and assets load quickly
  • No console errors or warnings
  • Network requests are optimized
  • Code splitting works as expected

​
Visual Appearance

  • Tailwind CSS styles are applied correctly
  • Responsive design works on different screen sizes
  • Images and fonts display properly
  • No CSS conflicts or missing styles
Production builds may behave differently than development builds. Always test thoroughly in preview mode before deploying.

​
Common Issues in Preview

​
Issue: Routes Return 404

If your app uses client-side routing (React Router), you may need to configure the server to serve index.html for all routes. Solution for deployment:
  • Most hosting platforms (Vercel, Netlify) handle this automatically
  • For custom servers, configure fallback to index.html

​
Issue: Environment Variables Not Working

Only environment variables prefixed with VITE_ are exposed to the client:
.env.production
# ✅ Exposed to client
VITE_API_URL=https://api.example.com

# ❌ Not exposed (server-side only)
API_SECRET=secret123

​
Issue: Assets Not Loading

If assets fail to load, check:
  1. Base path configuration in vite.config.ts
  2. Asset imports are using Vite’s import syntax
  3. Public assets are in the public/ directory
vite.config.ts
export default defineConfig({
  base: '/my-app/', // If deploying to a subdirectory
  plugins: [react(), tailwindcss()],
})

​
Issue: Different Behavior Than Development

Some features behave differently in production:
  • React strict mode: May have different effects
  • Source maps: Not available by default
  • Console warnings: Development-only warnings are removed
  • Performance: Much faster due to optimization

​
Configuring Preview Server

You can customize the preview server in vite.config.ts:
vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  preview: {
    port: 8080,
    strictPort: true,
    host: true,
    open: true,
  },
})
Options:
  • port: Change the preview server port
  • strictPort: Exit if port is already in use
  • host: Listen on all addresses (useful for network testing)
  • open: Automatically open browser

​
Testing Checklist

Before deploying to production, verify:
1

Build Successfully

npm run build
No TypeScript or build errors.
2

Start Preview Server

npm run preview
Server starts without errors.
3

Test All Routes

Navigate through all pages and routes in your application.
4

Check Console

Open browser DevTools and verify no errors in the console.
5

Test Functionality

Test forms, API calls, and interactive features.
6

Verify Performance

Check network tab for asset sizes and load times.
The preview server is not designed for production use. It’s only for local testing. Use a proper hosting platform for production deployment.

​
Next Steps

Once you’ve verified your build works correctly in preview:

Build Documentation

Learn more about the build process

Deploy to Production

Deploy your application to a hosting platform

Build docs developers (and LLMs) love

Get started for freeTalk to us