Setting a Custom Port in Vite

When developing with Vite, you might need to run your application on a specific port—whether to avoid conflicts with other services or to align with specific deployment requirements. This guide will show you multiple ways to configure your Vite application's port for both development and production environments.

Configuring Port in vite.config.js/ts

The most common and maintainable approach is to specify the port in your Vite configuration file.

Basic Port Configuration

// vite.config.js or vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    port: 3006, // Development server port
  },
})

TIP

If you're using TypeScript, make sure to have the appropriate types installed and your TypeScript configuration properly set up.

Separate Ports for Development and Preview

You can configure different ports for the development server and the production preview server:

export default defineConfig({
  server: {
    port: 3000, // Development port
  },
  preview: {
    port: 3001, // Production preview port
  },
})

Using Environment Variables

For more dynamic configuration, you can use environment variables to set the port:

1. Create Environment Files

# .env.development
VITE_PORT=3000

# .env.production  
VITE_PORT=3001

2. Load Environment Variables in Config

import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), 'VITE_')
  
  return {
    server: {
      port: Number(env.VITE_PORT) || 3000,
      strictPort: true, // Ensures the port is always used
    },
    preview: {
      port: Number(env.VITE_PORT) || 3000,
      strictPort: true,
    }
  }
})

Command Line Options

For quick, one-time port changes, you can use command-line arguments:

# Using npm
npm run dev -- --port 3006

# Using yarn
yarn dev --port 3006

# Using pnpm
pnpm dev --port 3006

WARNING

The double dash (--) is important as it passes the arguments to the underlying Vite command.

Package.json Script Modification

You can also permanently set a custom port by modifying your package.json:

{
  "scripts": {
    "dev": "vite --port 3006",
    "build": "vite build",
    "preview": "vite preview --port 3007"
  }
}

Best Practices

1. Use Configuration Files: For team projects, prefer vite.config.js/ts over package.json modifications for better maintainability.

2. Environment-Specific Ports: Use different ports for development and production to avoid conflicts.

3. Error Handling: Enable strictPort: true to ensure your app fails immediately if the port is unavailable rather than silently switching to a random port.

4. Documentation: Always document port configurations in your project's README for new team members.

Troubleshooting

If your port changes aren't taking effect:

• Ensure you're modifying the correct configuration file
• Restart the dev server after making changes
• Check that the port isn't already in use by another application
• Verify syntax in your configuration files

By understanding these different approaches, you can choose the method that best fits your development workflow and project requirements.