extrojs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahil Mulani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

package/README.md

@@ -0,0 +1,31 @@
+# extrojs
+
+> Next.js for Chrome extensions.
+
+File-based entrypoints, automatic Manifest V3 generation, and type-safe routing for popup / options / sidepanel surfaces, driven by a single Vite plugin. ESM-only, React, MV3.
+
+> **Status:** pre-stable. APIs may change between releases.
+
+## Install
+
+```bash
+pnpm add -D extrojs
+pnpm add react react-dom
+```
+
+## Quick start
+
+```bash
+extro dev      # dev server with HMR, writes .output/chrome-mv3-dev/
+extro build    # production build to .output/chrome-mv3-prod/
+```
+
+Load `.output/chrome-mv3-dev/` (or `.output/chrome-mv3-prod/`) in Chrome via **Load Unpacked**.
+
+## Docs and source
+
+Full documentation, architecture notes, and the source tree live at [github.com/Sahilm416/extro](https://github.com/Sahilm416/extro).
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+import type { ExtroConfig } from "@extrojs/types";
+export type { ExtroConfig } from "@extrojs/types";
+export declare const defineConfig: (config: ExtroConfig) => ExtroConfig;

package/dist/config.js

@@ -0,0 +1 @@
+export const defineConfig = (config) => config;

package/dist/dev-assets.d.ts

@@ -0,0 +1,18 @@
+import type { ExtroConfig } from "@extrojs/types";
+import { type AppTree } from "@extrojs/vite-plugin/internal";
+interface WriteDevAssetsOptions {
+    tree: AppTree;
+    root: string;
+    outDir: string;
+    port: number;
+    signalPort: number;
+    config: ExtroConfig;
+}
+/**
+ * @describe Writes the dev manifest + HTML shells + icons to disk so Chrome
+ * can load the unpacked extension while the Vite dev server serves modules
+ * over HTTP. Background/content scripts are written by the build-watch
+ * sidecar (a Vite watch-mode build) — not here.
+ */
+export declare const writeDevAssets: ({ tree, root, outDir, port, signalPort, config, }: WriteDevAssetsOptions) => Promise<void>;
+export {};

package/dist/dev-assets.js

@@ -0,0 +1,26 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { emitAssets, } from "@extrojs/vite-plugin/internal";
+/**
+ * @describe Writes the dev manifest + HTML shells + icons to disk so Chrome
+ * can load the unpacked extension while the Vite dev server serves modules
+ * over HTTP. Background/content scripts are written by the build-watch
+ * sidecar (a Vite watch-mode build) — not here.
+ */
+export const writeDevAssets = async ({ tree, root, outDir, port, signalPort, config, }) => {
+    await fs.mkdir(outDir, { recursive: true });
+    const pkgRaw = await fs.readFile(path.join(root, "package.json"), "utf8").catch(() => "{}");
+    const pkg = JSON.parse(pkgRaw);
+    await emitAssets({ tree, root, pkg, config, dev: { port, signalPort } }, (fileName, source) => fs.writeFile(path.join(outDir, fileName), source));
+    await copyIcons(root, outDir);
+};
+const copyIcons = async (root, outDir) => {
+    const srcDir = path.join(root, "icons");
+    const exists = await fs.stat(srcDir).then((s) => s.isDirectory()).catch(() => false);
+    if (!exists)
+        return;
+    const dstDir = path.join(outDir, "icons");
+    await fs.mkdir(dstDir, { recursive: true });
+    const files = await fs.readdir(srcDir);
+    await Promise.all(files.map((f) => fs.copyFile(path.join(srcDir, f), path.join(dstDir, f))));
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { createServer, build as viteBuild } from "vite";
+import { WebSocketServer } from "ws";
+import { extro } from "@extrojs/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { scanAppTree } from "@extrojs/vite-plugin/internal";
+import { loadConfig } from "./load-config.js";
+import { writeDevAssets } from "./dev-assets.js";
+const command = process.argv[2];
+const root = process.cwd();
+// Separate output dirs let dev artifacts (with the bridge installed) persist
+// across `extro dev` sessions without needing a prod-restore on shutdown.
+const devOutDir = path.join(root, ".output", "chrome-mv3-dev");
+const prodOutDir = path.join(root, ".output", "chrome-mv3-prod");
+const dev = async () => {
+    const config = await loadConfig(root);
+    // 1. Scan once up front so we can decide what to start.
+    const tree = await scanAppTree(root);
+    validateTree(tree);
+    // 2. Signal WS — the dev bridge in the extension's BG SW connects here.
+    //    Fixed port (not :0) so the port baked into a previously-loaded BG SW
+    //    keeps working across `extro dev` restarts — otherwise users have to
+    //    refresh the extension every time to pick up a new random port.
+    const signalPort = 9012;
+    const wss = new WebSocketServer({ port: signalPort });
+    wss.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.error(`\n[extro] Signal port ${signalPort} is in use — is another \`extro dev\` already running?\n`);
+            process.exit(1);
+        }
+        throw err;
+    });
+    await once(wss, "listening");
+    const broadcast = (msg) => {
+        const payload = JSON.stringify(msg);
+        for (const client of wss.clients) {
+            if (client.readyState === 1)
+                client.send(payload);
+        }
+    };
+    // 3. Vite dev server for routable surfaces.
+    //    `broadcastHmr` lets the plugin push HMR updates over our signal WS —
+    //    we can't piggy-back on Vite's own HMR WS because its origin check
+    //    rejects chrome-extension:// service workers.
+    const server = await createServer({
+        root,
+        plugins: [
+            react(),
+            extro({
+                root,
+                config,
+                broadcastHmr: (payload) => broadcast({ kind: "vite-hmr", payload }),
+            }),
+        ],
+        server: { cors: true },
+    });
+    await server.listen();
+    const addr = server.httpServer?.address();
+    const port = addr && typeof addr === "object" ? addr.port : server.config.server.port ?? 5173;
+    // 4. Dev manifest + HTML + icons.
+    await writeDevAssets({ tree, root, outDir: devOutDir, port, signalPort, config });
+    // 5. Build-watch sidecar for background + content. Always runs in dev so
+    //    the dev bridge gets bundled into background.js (even if the user has
+    //    no BG of their own).
+    const watcher = await viteBuild({
+        root,
+        plugins: [extro({ root, config, scriptsOnly: true, devBridge: { signalPort } })],
+        // emptyOutDir: false so the watcher doesn't wipe the manifest / HTML /
+        // icons that writeDevAssets just put down.
+        build: { watch: {}, emptyOutDir: false, outDir: devOutDir },
+        logLevel: "error",
+    });
+    // The watcher is a RollupWatcher; bundle events fire on every rebuild
+    // (including the first one). Broadcast on each so the bridge reloads.
+    if (watcher && typeof watcher.on === "function") {
+        ;
+        watcher.on("event", (event) => {
+            if (event.code === "BUNDLE_END") {
+                broadcast({ kind: "scripts-rebuilt" });
+            }
+        });
+    }
+    console.log(`\nExtro dev server: http://localhost:${port}`);
+    console.log(`Load unpacked extension from: ${devOutDir}\n`);
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown) {
+            console.log("\nAlready shutting down, please wait...");
+            return;
+        }
+        shuttingDown = true;
+        console.log("\nShutting down dev server...");
+        if (watcher && typeof watcher.close === "function") {
+            await watcher.close();
+        }
+        wss.close();
+        await server.close();
+        // No prod-restore: dev artifacts live in their own .output/chrome-mv3-dev
+        // dir so the loaded extension stays untouched. Run `extro build` for a
+        // standalone prod bundle in .output/chrome-mv3-prod.
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+};
+const validateTree = (tree) => {
+    const empty = Object.keys(tree.scripts).length === 0 &&
+        Object.keys(tree.surfaces).length === 0;
+    if (!empty)
+        return;
+    throw new Error("Extro: No extension entrypoints found.\n\nExpected files like:\n  src/app/popup/page.tsx\n  src/app/options/page.tsx\n  src/app/sidepanel/page.tsx\n  src/app/background/index.ts\n  src/app/content/index.ts");
+};
+const once = (emitter, event) => new Promise((resolve) => emitter.once(event, () => resolve()));
+const build = async () => {
+    console.log("Building extension...");
+    const config = await loadConfig(root);
+    await viteBuild({
+        root,
+        plugins: [react(), extro({ root, config })],
+        build: { outDir: prodOutDir },
+    });
+    console.log(`Build complete. Load unpacked extension from: ${prodOutDir}`);
+};
+switch (command) {
+    case "dev":
+        await dev();
+        break;
+    case "build":
+        await build();
+        break;
+    case "init":
+        console.log("Initializing Extro project...");
+        break;
+    default:
+        console.log("Extro CLI");
+}

package/dist/load-config.d.ts

@@ -0,0 +1,2 @@
+import type { ExtroConfig } from "@extrojs/types";
+export declare const loadConfig: (root: string) => Promise<ExtroConfig>;

package/dist/load-config.js

@@ -0,0 +1,14 @@
+import { createJiti } from "jiti";
+import fs from "node:fs";
+import path from "node:path";
+const CONFIG_FILENAMES = ["extro.config.ts", "extro.config.js"];
+export const loadConfig = async (root) => {
+    const configPath = CONFIG_FILENAMES
+        .map((name) => path.join(root, name))
+        .find((p) => fs.existsSync(p));
+    if (!configPath)
+        return {};
+    const jiti = createJiti(root, { interopDefault: true });
+    const mod = await jiti.import(configPath);
+    return "default" in mod ? mod.default : mod;
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "extrojs",
+  "version": "0.1.0",
+  "description": "Next.js for Chrome extensions. File-based entrypoints, automatic Manifest V3 generation, and React routing in a single Vite-powered CLI.",
+  "keywords": [
+    "extro",
+    "chrome-extension",
+    "browser-extension",
+    "manifest-v3",
+    "vite",
+    "react",
+    "framework"
+  ],
+  "author": "Sahil Mulani <sahilmulani501@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/Sahilm416/extro#readme",
+  "bugs": {
+    "url": "https://github.com/Sahilm416/extro/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sahilm416/extro.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "main": "./dist/config.js",
+  "types": "./dist/config.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    }
+  },
+  "bin": {
+    "extro": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "^6.0.1",
+    "jiti": "^2.4.2",
+    "vite": "^8.0.0",
+    "ws": "^8.20.0",
+    "@extrojs/react": "0.1.0",
+    "@extrojs/vite-plugin": "0.1.0",
+    "@extrojs/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "typecheck": "tsc --noEmit"
+  }
+}