@elumixor/devkit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,46 @@
1
+ # @elumixor/devkit
2
+
3
+ Dev orchestrator for bun monorepos. One config, and `bun run dev` frees the ports, runs every app side-by-side with colored prefixes, prints the local URLs, and (with `--open`) opens the browser once the server is live.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ bun add -d @elumixor/devkit
9
+ ```
10
+
11
+ ## Configure
12
+
13
+ Add a `devkit` block to your root `package.json`:
14
+
15
+ ```jsonc
16
+ {
17
+ "scripts": {
18
+ "dev": "devkit dev",
19
+ "dev:open": "devkit dev --open"
20
+ },
21
+ "devkit": {
22
+ "apps": [
23
+ { "name": "backend", "port": 10000, "color": "blue" },
24
+ { "name": "frontend", "port": 3000, "color": "magenta", "open": true }
25
+ ]
26
+ }
27
+ }
28
+ ```
29
+
30
+ Each app runs `bun --filter <name> dev` by default. Override with:
31
+
32
+ | field | meaning |
33
+ | --------- | ----------------------------------------------------------------- |
34
+ | `name` | display label + default `bun --filter` target |
35
+ | `filter` | explicit `bun --filter <target>` (defaults to `name`) |
36
+ | `cwd` | run `bun --cwd <cwd> run <script>` instead of `--filter` |
37
+ | `script` | script to run in the workspace (default `dev`) |
38
+ | `command` | raw shell command, overrides the above (e.g. `vite dev`) |
39
+ | `port` | freed on start and shown in the URL banner |
40
+ | `color` | prefix color (blue, magenta, green, yellow, cyan, red) |
41
+ | `open` | with `--open`, open this app's URL when its port comes up |
42
+
43
+ ## Bins
44
+
45
+ - `devkit dev [--open]` — the orchestrator above.
46
+ - `free-port <port>` — kill whatever is listening on a port (handy in a `predev`).
package/package.json ADDED
@@ -0,0 +1,35 @@
1
+ {
2
+ "name": "@elumixor/devkit",
3
+ "version": "0.1.0",
4
+ "description": "Dev orchestrator for bun monorepos — free ports, run apps side-by-side, open the browser when ready",
5
+ "author": "elumixor",
6
+ "license": "ISC",
7
+ "type": "module",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/elumixor/devkit.git"
11
+ },
12
+ "bin": {
13
+ "devkit": "./src/bin/devkit.ts",
14
+ "free-port": "./src/bin/free-port.ts"
15
+ },
16
+ "files": [
17
+ "src"
18
+ ],
19
+ "scripts": {
20
+ "build": "tsc --noEmit",
21
+ "typecheck": "tsc --noEmit",
22
+ "lint": "biome lint src",
23
+ "release:patch": "npm version patch -m \"Release v%s\" && git push --follow-tags",
24
+ "release:minor": "npm version minor -m \"Release v%s\" && git push --follow-tags",
25
+ "release:major": "npm version major -m \"Release v%s\" && git push --follow-tags"
26
+ },
27
+ "dependencies": {
28
+ "concurrently": "^10.0.3"
29
+ },
30
+ "devDependencies": {
31
+ "@biomejs/biome": "^2.4.8",
32
+ "@types/bun": "latest",
33
+ "typescript": "^5"
34
+ }
35
+ }
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env bun
2
+ import { runDev } from "../dev.ts";
3
+
4
+ const [command, ...rest] = process.argv.slice(2);
5
+
6
+ if (command !== "dev") {
7
+ console.error("usage: devkit dev [--open] [--dry]");
8
+ process.exit(1);
9
+ }
10
+
11
+ await runDev(rest.includes("--open"), rest.includes("--dry"));
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env bun
2
+ import { freePort } from "../free-port.ts";
3
+
4
+ const port = process.argv[2];
5
+ if (!port) {
6
+ console.error("usage: free-port <port>");
7
+ process.exit(1);
8
+ }
9
+
10
+ await freePort(port);
package/src/config.ts ADDED
@@ -0,0 +1,37 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { resolve } from "node:path";
3
+
4
+ /** One dev process. Resolved into a shell command by {@link commandFor}. */
5
+ export interface DevApp {
6
+ /** Display name; also the default `bun --filter` target. */
7
+ name?: string;
8
+ /** Explicit `bun --filter <target>` (defaults to `name`). */
9
+ filter?: string;
10
+ /** Run via `bun --cwd <cwd> run <script>` instead of `--filter`. */
11
+ cwd?: string;
12
+ /** Script to run in the workspace (default `dev`). */
13
+ script?: string;
14
+ /** Raw shell command; overrides filter/cwd/script (e.g. `vite dev`). */
15
+ command?: string;
16
+ /** Port to free on start and show in the URL banner. */
17
+ port?: number;
18
+ /** Prefix color for this process's output. */
19
+ color?: string;
20
+ /** With `--open`, open this app's URL once its port is live. */
21
+ open?: boolean;
22
+ }
23
+
24
+ export interface DevkitConfig {
25
+ apps: DevApp[];
26
+ }
27
+
28
+ /** Read the `devkit` config from the nearest package.json. */
29
+ export function loadConfig(dir: string = process.cwd()): DevkitConfig {
30
+ const pkgPath = resolve(dir, "package.json");
31
+ const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { devkit?: DevkitConfig };
32
+ const cfg = pkg.devkit;
33
+ if (!cfg?.apps?.length) {
34
+ throw new Error(`No "devkit.apps" found in ${pkgPath}`);
35
+ }
36
+ return cfg;
37
+ }
package/src/dev.ts ADDED
@@ -0,0 +1,65 @@
1
+ import concurrently from "concurrently";
2
+ import { type DevApp, loadConfig } from "./config.ts";
3
+ import { freePort } from "./free-port.ts";
4
+ import { openUrl, waitForPort } from "./wait-port.ts";
5
+
6
+ const PALETTE = ["blue", "magenta", "green", "yellow", "cyan", "red"];
7
+
8
+ /** Turn an app entry into the shell command that runs it. */
9
+ function commandFor(app: DevApp): string {
10
+ if (app.command) return app.command;
11
+ const script = app.script ?? "dev";
12
+ if (app.cwd) return `bun --cwd ${app.cwd} run ${script}`;
13
+ return `bun --filter ${app.filter ?? app.name} ${script}`;
14
+ }
15
+
16
+ function labelFor(app: DevApp, index: number): string {
17
+ return app.name ?? app.filter ?? app.cwd ?? `app${index}`;
18
+ }
19
+
20
+ /** Free ports, print URLs, run every app side-by-side, optionally open the browser. */
21
+ export async function runDev(open: boolean, dry = false): Promise<void> {
22
+ const { apps } = loadConfig();
23
+ const withPort = apps.filter((app) => app.port != null);
24
+
25
+ if (dry) {
26
+ console.log("devkit (dry run):");
27
+ apps.forEach((app, i) => {
28
+ const url = app.port != null ? ` → http://localhost:${app.port}${app.open ? " (open)" : ""}` : "";
29
+ console.log(` [${labelFor(app, i)}] ${commandFor(app)}${url}`);
30
+ });
31
+ return;
32
+ }
33
+
34
+ await Promise.all(withPort.map((app) => freePort(app.port as number)));
35
+
36
+ if (withPort.length > 0) {
37
+ const width = Math.max(...withPort.map((app, i) => labelFor(app, i).length));
38
+ const lines = withPort.map((app, i) => `${labelFor(app, i).padEnd(width)} http://localhost:${app.port}`);
39
+ console.log(`\n${lines.join("\n")}\n`);
40
+ }
41
+
42
+ const { result } = concurrently(
43
+ apps.map((app, i) => ({
44
+ command: commandFor(app),
45
+ name: labelFor(app, i),
46
+ prefixColor: app.color ?? PALETTE[i % PALETTE.length],
47
+ })),
48
+ { prefix: "name", killOthersOn: ["failure", "success"] },
49
+ );
50
+
51
+ if (open) {
52
+ for (const app of apps.filter((a) => a.open && a.port != null)) {
53
+ const url = `http://localhost:${app.port}`;
54
+ void waitForPort(app.port as number).then((ready) => {
55
+ if (ready) void openUrl(url).then(() => console.log(`✓ Opened ${url}`));
56
+ });
57
+ }
58
+ }
59
+
60
+ try {
61
+ await result;
62
+ } catch {
63
+ process.exitCode = 1;
64
+ }
65
+ }
@@ -0,0 +1,29 @@
1
+ import { exec } from "node:child_process";
2
+ import { promisify } from "node:util";
3
+
4
+ const execAsync = promisify(exec);
5
+
6
+ /** Kill whatever is listening on `port` so a dev server can always bind it. */
7
+ export async function freePort(port: number | string): Promise<void> {
8
+ try {
9
+ const { stdout } = await execAsync(`lsof -nP -iTCP:${port} -sTCP:LISTEN`);
10
+ const pids = [
11
+ ...new Set(
12
+ stdout
13
+ .split("\n")
14
+ .slice(1)
15
+ .map((line) => line.trim().split(/\s+/)[1])
16
+ .filter(Boolean),
17
+ ),
18
+ ];
19
+ if (pids.length > 0) {
20
+ await execAsync(`kill -9 ${pids.join(" ")}`);
21
+ console.log(`✓ Freed port ${port} (killed ${pids.join(", ")})`);
22
+ } else {
23
+ console.log(`✓ Port ${port} already free`);
24
+ }
25
+ } catch {
26
+ // lsof exits 1 when nothing is listening
27
+ console.log(`✓ Port ${port} already free`);
28
+ }
29
+ }
@@ -0,0 +1,29 @@
1
+ import { exec } from "node:child_process";
2
+ import { promisify } from "node:util";
3
+
4
+ const execAsync = promisify(exec);
5
+
6
+ /** Poll a local port until it accepts HTTP connections (or the timeout elapses). */
7
+ export async function waitForPort(
8
+ port: number | string,
9
+ { timeoutMs = 60_000, intervalMs = 400 }: { timeoutMs?: number; intervalMs?: number } = {},
10
+ ): Promise<boolean> {
11
+ const url = `http://localhost:${port}`;
12
+ const deadline = Date.now() + timeoutMs;
13
+ while (Date.now() < deadline) {
14
+ try {
15
+ const res = await fetch(url);
16
+ if (res.status < 500) return true;
17
+ } catch {
18
+ // server not up yet
19
+ }
20
+ await new Promise((resolve) => setTimeout(resolve, intervalMs));
21
+ }
22
+ return false;
23
+ }
24
+
25
+ /** Open a URL in the default browser (macOS / Linux / Windows). */
26
+ export async function openUrl(url: string): Promise<void> {
27
+ const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
28
+ await execAsync(`${opener} ${url}`);
29
+ }