vite-plugin-killer-instincts

1.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that detects when a process is already using the configured dev server port and optionally kills it. Version 1.1.0, works with Vite >=5.0.0. Key differentiator: integrates with Vite's `strictPort` to either throw a helpful error (default) or automatically terminate the blocking process (`autoKill: true`). Compatible with both ESM and CommonJS setups. Maintained by Wes Bos.

Common errors

error Error: Port 3000 is already in use. Could not automatically kill process. Run `kill -9 PID` to manually kill the process. ↓

cause autoKill is set to false and port is occupied.

fix

Set autoKill: true in plugin options, or run the displayed kill -9 PID command.

error [vite] Internal server error: killerInstincts is not a function ↓

cause User tried to use a named import `{ killerInstincts }` instead of default import.

fix

Use import killerInstincts from 'vite-plugin-killer-instincts' (default import).

Warnings

gotcha The plugin only activates when `strictPort: true` is set in the Vite server config. ↓

fix Ensure you have `server.strictPort: true` in your Vite config.

gotcha When `autoKill` is false (default), the plugin throws an error with instructions; it does not attempt to kill the process. ↓

fix Set `autoKill: true` if you want automatic process termination. Otherwise, manually run the suggested kill command.

Install

npm install vite-plugin-killer-instincts

yarn add vite-plugin-killer-instincts

pnpm add vite-plugin-killer-instincts

Imports

default

wrong

import { killerInstincts } from 'vite-plugin-killer-instincts'

correct

import killerInstincts from 'vite-plugin-killer-instincts'

This package exports a default function, not a named export.

killerInstincts (default import in CommonJS)

wrong

const { killerInstincts } = require('vite-plugin-killer-instincts')

correct

const killerInstincts = require('vite-plugin-killer-instincts')

CJS require returns the default export directly.

default import with type assertion (TypeScript users)

wrong

import killerInstincts = require('vite-plugin-killer-instincts')

correct

import killerInstincts from 'vite-plugin-killer-instincts'

Use ESM import syntax; the package ships TypeScript types.

Quickstart

Configure Vite to use the plugin with strictPort and autoKill enabled.

// vite.config.ts
import { defineConfig } from 'vite';
import killerInstincts from 'vite-plugin-killer-instincts';

export default defineConfig({
  server: {
    port: 3000,
    strictPort: true,
  },
  plugins: [
    killerInstincts({
      autoKill: true, // kills the blocking process automatically
    }),
  ],
});