@greener-games/vite-deterministic-port

A Vite plugin that automatically assigns a stable, deterministic port to your project based on its name.

This ensures that every developer on your team uses the exact same localhost URL for a specific project, eliminating the "it works on my port 3000 but not yours" confusion. This is especially powerful for:

• Micro-frontends: Ensuring each app always has its own dedicated port.
• Webhook testing: Maintaining stable callback URLs for services like Stripe or GitHub.
• Shared documentation: Referencing local dev URLs in team wikis that actually work for everyone.

Features

• Zero Config: Automatically reads name from your package.json.
• Team Consistency: Everyone gets the same port (e.g., http://localhost:52491) for the same project.
• Informative: Logs the chosen port to the console on startup.
• Customizable: Define your own port ranges and salts.
• Smart Fallback: Attempts the deterministic port first and hunts for the next available port if occupied (configurable via strict).

Installation

npm install --save-dev @greener-games/vite-deterministic-port

Usage

Add it to your vite.config.ts:

import { defineConfig } from 'vite';
import deterministicPortPlugin from '@greener-games/vite-deterministic-port';

export default defineConfig({
  plugins: [
    deterministicPortPlugin()
  ]
});

Options

The plugin works out of the box, but you can customize its behavior:

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | strict | boolean | false | If true, Vite fails immediately if the port is busy instead of hunting for the next available port. | | portSalt | string \| number | '' | Change this to force a new port if a collision occurs. | | minPort | number | 10000 | The minimum port number in the range. | | maxPort | number | 60000 | The maximum port number in the range. | | verbose | boolean | true | Log the port selection to the console. |

Example with Options

deterministicPortPlugin({
  strict: false, // Default is false; set true to prevent Vite from hunting for port + 1
  portSalt: 'v2',
  minPort: 3000,
  maxPort: 3999,
  verbose: true
})

Troubleshooting

Port Collision

In the rare event that two projects hash to the same port, simply provide a portSalt:

deterministicPortPlugin({ portSalt: 'resolve-collision' })

Port Already in Use

By default (strict: false), if the deterministic port is already occupied (e.g., running multiple instances of the same project), Vite will automatically hunt for the next open port (e.g. port + 1). If you require strict port enforcement where Vite fails rather than incrementing, set strict: true.

License

MIT