zihluwang
861852961f
These files were already out of step with the project's Prettier config before this branch of work; running `pnpm format` finally swept them up. No semantic changes. Kept separate from the functional commits so the reformatting does not bury them in diff noise.
61 lines
2.4 KiB
Plaintext
61 lines
2.4 KiB
Plaintext
---
|
|
title: Port Checker
|
|
---
|
|
|
|
import { Tabs, Tab } from "@rspress/core/theme"
|
|
|
|
## Introduction
|
|
|
|
**vite-plugin-port-checker** is a lightweight Vite plugin that warns you when the dev server is listening on a port blocked by common browsers. Browsers such as Chrome and Firefox maintain a [list of restricted ports](https://fetch.spec.whatwg.org/#port-blocking) — typically those associated with well-known protocols like SMTP, SSH, and DNS — and refuse to connect to them. Accidentally running your dev server on one of these ports leads to a confusing "connection refused" or "blocked" error with no clear explanation.
|
|
|
|
This plugin detects the situation at startup and prints a clear, colour-coded warning to the console, advising you to change the `server.port` setting in your Vite configuration.
|
|
|
|
## Features
|
|
|
|
- **Automatic Detection** — Checks the dev server port against the complete Fetch spec port-blocking list (68 restricted ports).
|
|
- **Clear Warnings** — Yellow-highlighted console output with actionable guidance.
|
|
- **Zero Configuration** — Works out of the box with no options to set.
|
|
- **Lightweight** — Single-file plugin with no dependencies beyond Vite itself.
|
|
|
|
## Installation
|
|
|
|
<Tabs>
|
|
<Tab label="npm">```bash npm install vite-plugin-port-checker -D ```</Tab>
|
|
<Tab label="pnpm">```bash pnpm add vite-plugin-port-checker -D ```</Tab>
|
|
</Tabs>
|
|
|
|
## Usage
|
|
|
|
Add the plugin to your `vite.config.ts`:
|
|
|
|
```ts
|
|
// vite.config.ts
|
|
import { defineConfig } from "vite"
|
|
import checkRestrictedPort from "vite-plugin-port-checker"
|
|
|
|
export default defineConfig({
|
|
plugins: [checkRestrictedPort()],
|
|
})
|
|
```
|
|
|
|
When the dev server starts on a restricted port (e.g. port 25, 22, or 53), you will see:
|
|
|
|
```
|
|
[Warning] The current listening port 25 is categorised as a restricted port
|
|
by most browsers. This may prevent you from accessing the application.
|
|
Please consider changing the port in your 'vite.config.ts' or 'vite.config.js'
|
|
via 'server.port'.
|
|
```
|
|
|
|
## How It Works
|
|
|
|
The plugin hooks into Vite's `configureServer` lifecycle. Once the HTTP server emits the `listening` event, the plugin inspects the bound port and checks it against the hardcoded set of 68 restricted ports defined in the [Fetch specification](https://fetch.spec.whatwg.org/#port-blocking). If there is a match, a yellow `console.warn` message alerts the developer.
|
|
|
|
## Requirements
|
|
|
|
- Vite 3.0.0 or later
|
|
|
|
## License
|
|
|
|
vite-plugin-port-checker is open-source software released under the MIT License.
|