@bridgerb/port-from-name 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -0,0 +1,59 @@
+# @bridgerb/port-from-name
+
+Give every project its own dev-server port, automatically. The port comes from your project's name, so it's the same every time you run it — no more "port 5173 is already in use" when you've got a couple of apps going at once.
+
+## Install
+
+```sh
+npm install -D @bridgerb/port-from-name
+```
+
+## Use it
+
+Add it to `vite.config.ts` and you're done:
+
+```ts
+import { sveltekit } from '@sveltejs/kit/vite';
+import { autoPort } from '@bridgerb/port-from-name';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [sveltekit(), autoPort()],
+});
+```
+
+It picks a stable port for both `npm run dev` and `npm run preview`. If two apps ever happen to pick the same one, Vite just bumps to the next free port instead of crashing.
+
+## What ports it uses
+
+By default it picks from **3100–4899**. That range is chosen to stay out of the way:
+
+- Above the low ports your OS reserves (anything under 1024).
+- Past the usual suspects everything else grabs — 3000 (Node/Next/Rails), 5173 (Vite's default), 5432 (Postgres), and 5000/7000 (AirPlay on Mac).
+- Well below the high ports your machine hands out for its own connections, so you're never fighting it for one.
+
+It's also wide enough that running a handful of apps at once almost never picks the same port twice. Want a different range? Set `base` and `range` (see below).
+
+## Just want the number?
+
+```ts
+import { portFromName } from '@bridgerb/port-from-name';
+
+const port = portFromName();              // from this project's name
+const port2 = portFromName({ name: 'my-app' });
+```
+
+## Options
+
+```ts
+autoPort({
+  name,        // use a custom name instead of package.json's
+  base,        // lowest port to pick (default 3100)
+  range,       // how wide the range is (default 1800, so 3100–4899)
+  strictPort,  // crash instead of bumping on a clash (default false)
+});
+```
+
+## License
+
+[Unlicense](./LICENSE) — public domain.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import type { Plugin } from 'vite';
+export interface PortOptions {
+    /** Override the project name. Defaults to the "name" field of the nearest package.json. */
+    name?: string;
+    /** Directory to look for package.json in. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Lowest port to assign. Default 3100. */
+    base?: number;
+    /** Width of the port band. Default 1800, so ports land in 3100–4899. */
+    range?: number;
+    /** Fail instead of incrementing when the port is already taken. Default false. */
+    strictPort?: boolean;
+}
+/**
+ * Lowest port assigned by default. Sits above the privileged range (<1024) and
+ * steps off 3000, the single most contested dev port (Node, Rails, Next, CRA).
+ */
+export declare const DEFAULT_BASE = 3100;
+/**
+ * Default width of the port band. 3100–4899 clears privileged ports, ends before
+ * AirPlay (5000), Vite (5173) and Postgres (5432), stays far below the ephemeral
+ * range (Linux 32768+, macOS 49152+), and is wide enough that the birthday-paradox
+ * collision odds stay low for the handful of projects you run at once.
+ */
+export declare const DEFAULT_RANGE = 1800;
+/**
+ * Deterministic port derived from a project name.
+ * Same name -> same port, every time, on every machine.
+ */
+export declare function portFromName(options?: PortOptions): number;
+/**
+ * Vite plugin that pins the dev server and preview ports to portFromName().
+ * Drop it in plugins[] and forget about it.
+ */
+export declare function autoPort(options?: PortOptions): Plugin;
+export default autoPort;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,MAAM,WAAW,WAAW;IAC1B,2FAA2F;IAC3F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,OAAO,CAAC;AA4BlC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,WAAgB,GAAG,MAAM,CAI9D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,WAAgB,GAAG,MAAM,CAY1D;AAED,eAAe,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Lowest port assigned by default. Sits above the privileged range (<1024) and
+ * steps off 3000, the single most contested dev port (Node, Rails, Next, CRA).
+ */
+export const DEFAULT_BASE = 3100;
+/**
+ * Default width of the port band. 3100–4899 clears privileged ports, ends before
+ * AirPlay (5000), Vite (5173) and Postgres (5432), stays far below the ephemeral
+ * range (Linux 32768+, macOS 49152+), and is wide enough that the birthday-paradox
+ * collision odds stay low for the handful of projects you run at once.
+ */
+export const DEFAULT_RANGE = 1800;
+/** FNV-1a 32-bit hash. Stable across machines, well-distributed, zero deps. */
+function fnv1a(str) {
+    let h = 0x811c9dc5; // 2166136261 offset basis
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193); // 16777619 prime; Math.imul = correct 32-bit multiply
+    }
+    return h >>> 0;
+}
+function resolveName(options) {
+    if (options.name)
+        return options.name;
+    const pkgPath = resolve(options.cwd ?? process.cwd(), 'package.json');
+    let raw;
+    try {
+        raw = readFileSync(pkgPath, 'utf8');
+    }
+    catch {
+        throw new Error(`[port-from-name] could not read ${pkgPath} — pass { name } explicitly.`);
+    }
+    const name = JSON.parse(raw).name;
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new Error(`[port-from-name] no "name" field in ${pkgPath} — pass { name } explicitly.`);
+    }
+    return name;
+}
+/**
+ * Deterministic port derived from a project name.
+ * Same name -> same port, every time, on every machine.
+ */
+export function portFromName(options = {}) {
+    const base = options.base ?? DEFAULT_BASE;
+    const range = options.range ?? DEFAULT_RANGE;
+    return base + (fnv1a(resolveName(options)) % range);
+}
+/**
+ * Vite plugin that pins the dev server and preview ports to portFromName().
+ * Drop it in plugins[] and forget about it.
+ */
+export function autoPort(options = {}) {
+    return {
+        name: 'port-from-name',
+        config() {
+            const port = portFromName(options);
+            const strictPort = options.strictPort ?? false;
+            return {
+                server: { port, strictPort },
+                preview: { port, strictPort },
+            };
+        },
+    };
+}
+export default autoPort;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bridgerb/port-from-name",
+  "version": "1.0.0",
+  "description": "Deterministic Vite/SvelteKit dev-server port derived from your project name",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["vite", "vite-plugin", "sveltekit", "port", "dev-server", "deterministic"],
+  "author": "BridgerB",
+  "license": "Unlicense",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BridgerB/port-from-name.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.0.0"
+  }
+}