diff --git a/docs/en-gb/projects/regions4j/index.mdx b/docs/en-gb/projects/regions4j/index.mdx index 2f453c8..340b511 100644 --- a/docs/en-gb/projects/regions4j/index.mdx +++ b/docs/en-gb/projects/regions4j/index.mdx @@ -1,5 +1,5 @@ --- -title: regions4j +title: Regions for Java --- ## Introduction diff --git a/docs/en-gb/projects/vite-plugins/index.mdx b/docs/en-gb/projects/vite-plugins/index.mdx new file mode 100644 index 0000000..88e44ed --- /dev/null +++ b/docs/en-gb/projects/vite-plugins/index.mdx @@ -0,0 +1,11 @@ +--- +title: Vite Plugins +--- + +## Overview + +A collection of Vite plugins developed and maintained by OnixByte. Each plugin is designed to solve a specific problem in the Vite development workflow — lightweight, zero-dependency, and plug-and-play. + +## Available Plugins + +- **[Port Checker](/projects/vite-plugins/port-checker)** — Warns when the dev server listens on a browser-restricted port (per the Fetch specification), helping you avoid silent connection failures. diff --git a/docs/en-gb/projects/vite-plugins/port-checker/index.mdx b/docs/en-gb/projects/vite-plugins/port-checker/index.mdx new file mode 100644 index 0000000..7327d2d --- /dev/null +++ b/docs/en-gb/projects/vite-plugins/port-checker/index.mdx @@ -0,0 +1,68 @@ +--- +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 + + + + ```bash + npm install vite-plugin-port-checker -D + ``` + + + ```bash + pnpm add vite-plugin-port-checker -D + ``` + + + +## 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. diff --git a/docs/zh-hans/projects/regions4j/index.mdx b/docs/zh-hans/projects/regions4j/index.mdx index df6a752..655db38 100644 --- a/docs/zh-hans/projects/regions4j/index.mdx +++ b/docs/zh-hans/projects/regions4j/index.mdx @@ -1,5 +1,5 @@ --- -title: regions4j +title: Regions for Java --- ## 介绍 diff --git a/docs/zh-hans/projects/vite-plugins/index.mdx b/docs/zh-hans/projects/vite-plugins/index.mdx new file mode 100644 index 0000000..07bfebc --- /dev/null +++ b/docs/zh-hans/projects/vite-plugins/index.mdx @@ -0,0 +1,11 @@ +--- +title: Vite 插件 +--- + +## 概览 + +由 OnixByte 开发和维护的 Vite 插件合集。每个插件旨在解决 Vite 开发工作流中的特定问题 — 轻量级、零依赖、即插即用。 + +## 可用插件 + +- **[Port Checker](/projects/vite-plugins/port-checker)** — 当开发服务器监听浏览器限制的端口(依据 Fetch 规范)时发出警告,帮助您避免无响应的连接失败。 diff --git a/docs/zh-hans/projects/vite-plugins/port-checker/index.mdx b/docs/zh-hans/projects/vite-plugins/port-checker/index.mdx new file mode 100644 index 0000000..4af0052 --- /dev/null +++ b/docs/zh-hans/projects/vite-plugins/port-checker/index.mdx @@ -0,0 +1,67 @@ +--- +title: Port Checker +--- + +import { Tabs, Tab } from "@rspress/core/theme" + +## 介绍 + +**vite-plugin-port-checker** 是一个轻量级的 Vite 插件,可在开发服务器监听被常见浏览器屏蔽的端口时发出警告。Chrome 和 Firefox 等浏览器维护了一份[受限制端口列表](https://fetch.spec.whatwg.org/#port-blocking) — 这些端口通常与 SMTP、SSH 和 DNS 等知名协议关联 — 并拒绝连接这些端口。如果不小心将开发服务器运行在这些端口上,会导致令人困惑的"连接被拒绝"或"已被屏蔽"错误,且没有任何明确的解释。 + +该插件会在启动时检测到这种情况,并向控制台打印一条清晰且带有颜色标记的警告,建议您修改 Vite 配置中的 `server.port` 设置。 + +## 特性 + +- **自动检测** — 对照完整的 Fetch 规范端口屏蔽列表(68 个受限端口)检查开发服务器端口。 +- **清晰的警告** — 黄色高亮控制台输出,并提供可操作的指导。 +- **零配置** — 开箱即用,无需设置任何选项。 +- **轻量级** — 单文件插件,除 Vite 本身外无任何依赖。 + +## 安装 + + + + ```bash + npm install vite-plugin-port-checker -D + ``` + + + ```bash + pnpm add vite-plugin-port-checker -D + ``` + + + +## 使用 + +在 `vite.config.ts` 中添加插件: + +```ts title="vite.config.ts" +import { defineConfig } from "vite" +import checkRestrictedPort from "vite-plugin-port-checker" + +export default defineConfig({ + plugins: [checkRestrictedPort()], +}) +``` + +当开发服务器启动在受限端口(如 25、22 或 53 端口)时,您将看到: + +``` +[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'. +``` + +## 工作原理 + +该插件通过钩入 Vite 的 `configureServer` 生命周期工作。当 HTTP 服务器触发 `listening` 事件后,插件检查绑定的端口号,并与 [Fetch 规范](https://fetch.spec.whatwg.org/#port-blocking)中定义的 68 个受限端口进行比对。如果匹配,则通过黄色的 `console.warn` 消息提醒开发者。 + +## 要求 + +- Vite 3.0.0 或更高版本 + +## 许可证 + +vite-plugin-port-checker 是采用 MIT 许可证发布的开源软件。