create-extro 0.0.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,64 @@
+# create-extro
+
+The scaffolder for [Extro](https://github.com/Sahilm416/extro), a framework for building Chrome extensions with file-based entrypoints, automatic Manifest V3 generation, and React routing.
+
+## Usage
+
+```bash
+pnpm create extro
+# npm create extro@latest
+# yarn create extro
+# bun create extro
+```
+
+Answer the prompts, or pass a directory and skip them:
+
+```bash
+pnpm create extro my-extension --template minimal
+```
+
+Then start the dev server and load the unpacked extension:
+
+```bash
+cd my-extension
+pnpm install   # if you skipped the install step
+extro dev      # writes output/chrome-mv3-dev, starts Vite with HMR
+```
+
+Open `chrome://extensions`, turn on Developer mode, and **Load unpacked** the `output/chrome-mv3-dev` directory.
+
+## What you get
+
+A clean starting point: a popup and a background service worker, plus `extro.config.ts`, icons, and a TypeScript setup. Nothing you have to delete.
+
+Extro is file-based, so you grow it by dropping a file under `src/app/`:
+
+- `options/page.tsx` - the options page
+- `sidepanel/page.tsx` - the side panel
+- `content/page.tsx` - a content-script UI (React, shadow DOM)
+- `popup/settings/page.tsx`, `popup/[id]/page.tsx` - nested and dynamic routes
+
+See the [Extro docs](https://github.com/Sahilm416/extro) for routing, layouts, and the manifest reference.
+
+## Options
+
+```
+create-extro [directory] [options]
+
+  -t, --template <name>   Template to use: default
+      --pm <manager>      Force a package manager: npm, pnpm, yarn, bun
+      --install           Install dependencies
+      --no-install        Skip installing dependencies
+      --git               Initialize a git repository
+      --no-git            Skip git initialization
+      --overwrite         Overwrite the target directory if it is not empty
+  -y, --yes               Accept defaults and skip the prompts
+  -h, --help              Show this help
+  -v, --version           Show the version
+```
+
+When the terminal is not interactive (CI, piped output) or `--yes` is passed, the prompts are skipped and flags plus defaults drive the run.
+
+## License
+
+[MIT](https://github.com/Sahilm416/extro/blob/main/LICENSE) © Sahil Mulani

package/dist/args.js

@@ -0,0 +1,65 @@
+/**
+ * @describe Hand-rolled argv parser. A scaffolder's UX lives in its prompts,
+ * not its flags, so we avoid a parser dependency and keep full control over
+ * `--help`. Supports `--flag`, `--no-flag`, `--key value`, `--key=value`, and
+ * the short aliases `-t`, `-y`, `-h`, `-v`.
+ */
+export const parseArgs = (argv) => {
+    const opts = { unknown: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("-")) {
+            if (opts.projectName === undefined)
+                opts.projectName = arg;
+            continue;
+        }
+        let key = arg;
+        let inlineValue;
+        const eq = arg.indexOf("=");
+        if (arg.startsWith("--") && eq !== -1) {
+            key = arg.slice(0, eq);
+            inlineValue = arg.slice(eq + 1);
+        }
+        const takeValue = () => inlineValue !== undefined ? inlineValue : argv[++i];
+        switch (key) {
+            case "-h":
+            case "--help":
+                opts.help = true;
+                break;
+            case "-v":
+            case "--version":
+                opts.version = true;
+                break;
+            case "-y":
+            case "--yes":
+                opts.yes = true;
+                break;
+            case "-t":
+            case "--template":
+                opts.template = takeValue();
+                break;
+            case "--pm":
+            case "--package-manager":
+                opts.packageManager = takeValue();
+                break;
+            case "--install":
+                opts.install = true;
+                break;
+            case "--no-install":
+                opts.install = false;
+                break;
+            case "--git":
+                opts.git = true;
+                break;
+            case "--no-git":
+                opts.git = false;
+                break;
+            case "--overwrite":
+                opts.overwrite = true;
+                break;
+            default:
+                opts.unknown.push(arg);
+        }
+    }
+    return opts;
+};

package/dist/cli.js

@@ -0,0 +1,186 @@
+import path from "node:path";
+import * as p from "@clack/prompts";
+import validatePackageName from "validate-npm-package-name";
+import { parseArgs } from "./args.js";
+import { printHelp } from "./help.js";
+import { pkg } from "./pkg.js";
+import { brand, brandTag, bold, dim, green } from "./colors.js";
+import { TEMPLATES, DEFAULT_TEMPLATE, isTemplate } from "./templates.js";
+import { detectPkgManager, isPkgManager, runScript, } from "./pkg-manager.js";
+import { scaffold } from "./scaffold.js";
+import { isDirEmpty, emptyDir, toValidPackageName, relativeTarget, } from "./fs.js";
+import { installDependencies, isGitInstalled, isInsideGitRepo, initGitRepo, } from "./system.js";
+const DEFAULT_DIR = "my-extension";
+/** Abort cleanly on Ctrl-C or an explicit cancel. */
+const bail = () => {
+    p.cancel("Cancelled.");
+    process.exit(0);
+};
+const unwrap = (value) => {
+    if (p.isCancel(value))
+        bail();
+    return value;
+};
+/** First validation error/warning for a package name, or undefined if valid. */
+const packageNameError = (name) => {
+    const { validForNewPackages, errors, warnings } = validatePackageName(name);
+    if (validForNewPackages)
+        return undefined;
+    return (errors ?? warnings ?? ["is not a valid package name"])[0];
+};
+export const run = async () => {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help)
+        return printHelp();
+    if (opts.version) {
+        console.log(pkg.version);
+        return;
+    }
+    const cwd = process.cwd();
+    const interactive = Boolean(process.stdout.isTTY) && !opts.yes;
+    p.intro(`${brandTag(" create-extro ")} ${dim(`v${pkg.version}`)}`);
+    if (opts.unknown.length) {
+        p.log.warn(`Ignoring unknown ${plural(opts.unknown.length, "option")}: ${opts.unknown.join(", ")}`);
+    }
+    // Package manager: an explicit --pm wins, otherwise infer from the runner.
+    let pm = detectPkgManager();
+    if (opts.packageManager) {
+        if (!isPkgManager(opts.packageManager)) {
+            p.log.error(`Unknown package manager "${opts.packageManager}". Use npm, pnpm, yarn, or bun.`);
+            process.exit(1);
+        }
+        pm = opts.packageManager;
+    }
+    // 1. Target directory + package name.
+    let dirInput = opts.projectName;
+    if (dirInput === undefined) {
+        if (!interactive) {
+            dirInput = DEFAULT_DIR;
+        }
+        else {
+            dirInput = unwrap(await p.text({
+                message: "Where should we create your extension?",
+                placeholder: `./${DEFAULT_DIR}`,
+                defaultValue: DEFAULT_DIR,
+                validate: (value) => {
+                    const input = (value ?? "").trim() || DEFAULT_DIR;
+                    const name = toValidPackageName(path.basename(path.resolve(input)));
+                    return packageNameError(name);
+                },
+            })).trim();
+        }
+    }
+    dirInput = dirInput || DEFAULT_DIR;
+    const targetDir = path.resolve(cwd, dirInput);
+    const rel = relativeTarget(cwd, targetDir);
+    const packageName = toValidPackageName(path.basename(targetDir));
+    const nameError = packageNameError(packageName);
+    if (nameError) {
+        p.log.error(`Cannot use "${packageName}" as a package name: it ${nameError}.`);
+        process.exit(1);
+    }
+    // 2. Resolve a conflicting, non-empty target directory.
+    if (!isDirEmpty(targetDir)) {
+        if (opts.overwrite) {
+            emptyDir(targetDir);
+        }
+        else if (!interactive) {
+            p.log.error(`${bold(rel)} is not empty. Pass --overwrite to replace its contents.`);
+            process.exit(1);
+        }
+        else {
+            const choice = unwrap(await p.select({
+                message: `${bold(rel)} is not empty. How should we proceed?`,
+                initialValue: "cancel",
+                options: [
+                    { value: "cancel", label: "Cancel" },
+                    { value: "overwrite", label: "Remove existing files and continue" },
+                    { value: "ignore", label: "Ignore files and continue", hint: "may conflict" },
+                ],
+            }));
+            if (choice === "cancel")
+                bail();
+            if (choice === "overwrite")
+                emptyDir(targetDir);
+        }
+    }
+    // 3. Template.
+    let template = opts.template ?? DEFAULT_TEMPLATE;
+    if (opts.template) {
+        if (!isTemplate(opts.template)) {
+            p.log.error(`Unknown template "${opts.template}". Choose from: ${TEMPLATES.map((t) => t.name).join(", ")}.`);
+            process.exit(1);
+        }
+    }
+    else if (interactive && TEMPLATES.length > 1) {
+        template = unwrap(await p.select({
+            message: "Which template?",
+            initialValue: DEFAULT_TEMPLATE,
+            options: TEMPLATES.map((t) => ({ value: t.name, label: t.label, hint: t.hint })),
+        }));
+    }
+    // 4. Install dependencies?
+    let doInstall = opts.install;
+    if (doInstall === undefined) {
+        doInstall = interactive
+            ? unwrap(await p.confirm({ message: `Install dependencies with ${brand(pm)}?`, initialValue: true }))
+            : false;
+    }
+    // 5. Initialize git? Never re-init when already inside a repo.
+    const gitAvailable = isGitInstalled() && !isInsideGitRepo(cwd);
+    let doGit = opts.git;
+    if (doGit === undefined) {
+        doGit =
+            interactive && gitAvailable
+                ? unwrap(await p.confirm({ message: "Initialize a git repository?", initialValue: true }))
+                : false;
+    }
+    if (doGit && !gitAvailable) {
+        p.log.warn("Skipping git: already inside a repository or git is not installed.");
+        doGit = false;
+    }
+    // 6. Write the template.
+    const scaffolding = p.spinner();
+    scaffolding.start(`Scaffolding the ${brand(template)} template`);
+    try {
+        scaffold({ templateName: template, targetDir, packageName });
+    }
+    catch (error) {
+        scaffolding.stop("Failed to scaffold the template");
+        throw error;
+    }
+    scaffolding.stop(`Created ${bold(rel)}`);
+    // 7. Install.
+    if (doInstall) {
+        const installing = p.spinner();
+        installing.start(`Installing dependencies with ${brand(pm)}`);
+        if (installDependencies(pm, targetDir)) {
+            installing.stop("Installed dependencies");
+        }
+        else {
+            installing.stop("Could not install dependencies");
+            p.log.warn(`Run ${brand(installCommand(pm))} yourself to finish setup.`);
+            doInstall = false;
+        }
+    }
+    // 8. Git.
+    if (doGit) {
+        const initializing = p.spinner();
+        initializing.start("Initializing a git repository");
+        initializing.stop(initGitRepo(targetDir)
+            ? "Initialized a git repository"
+            : "Could not initialize git");
+    }
+    // 9. Next steps.
+    const steps = [];
+    if (rel !== ".")
+        steps.push(`cd ${rel}`);
+    if (!doInstall)
+        steps.push(installCommand(pm));
+    steps.push(runScript(pm, "dev"));
+    p.note(steps.map((step, i) => `${dim(`${i + 1}.`)} ${brand(step)}`).join("\n"), "Next steps");
+    p.log.message(`Then open ${bold("chrome://extensions")}, enable Developer mode, and ${bold("Load unpacked")}\n${dim(`from ${rel === "." ? "" : `${rel}/`}output/chrome-mv3-dev`)}.`);
+    p.outro(`${green("✓")} Welcome to Extro. ${dim("https://github.com/Sahilm416/extro")}`);
+};
+const installCommand = (pm) => pm === "yarn" ? "yarn" : `${pm} install`;
+const plural = (count, word) => count === 1 ? word : `${word}s`;

package/dist/colors.js

@@ -0,0 +1,13 @@
+import pc from "picocolors";
+// Extro brand terracotta (#CC785C / rgb 204,120,92) on the logo's near-black
+// (#0a0a0a). This mirrors the framework CLI (packages/extrojs logger) so
+// `create-extro` and `extro dev` read as one coherent voice. picocolors only
+// covers the 16 ANSI names, so emit 24-bit truecolor directly, gated on the
+// same color-support check picocolors uses (auto-plain in pipes and CI).
+export const brand = (s) => pc.isColorSupported ? `\x1b[38;2;204;120;92m${s}\x1b[39m` : s;
+export const brandTag = (s) => pc.isColorSupported
+    ? `\x1b[1m\x1b[48;2;204;120;92m\x1b[38;2;10;10;10m${s}\x1b[0m`
+    : s;
+export const dim = pc.dim;
+export const bold = pc.bold;
+export const green = pc.green;

package/dist/fs.js

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+/** True when the path does not exist, or exists with nothing but a `.git` dir. */
+export const isDirEmpty = (dir) => {
+    if (!fs.existsSync(dir))
+        return true;
+    const entries = fs.readdirSync(dir);
+    return entries.length === 0 || (entries.length === 1 && entries[0] === ".git");
+};
+/** Remove every child of `dir` except `.git`, leaving the directory itself. */
+export const emptyDir = (dir) => {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir)) {
+        if (entry === ".git")
+            continue;
+        fs.rmSync(path.join(dir, entry), { recursive: true, force: true });
+    }
+};
+/**
+ * @describe Coerce a directory basename into a valid npm package name: lower
+ * case, spaces to hyphens, strip leading dots/underscores, and replace any
+ * remaining illegal characters. Mirrors the normalization create-vite applies.
+ */
+export const toValidPackageName = (input) => input
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/^[._]+/, "")
+    .replace(/[^a-z0-9-~]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "extro-extension";
+/** Display form of the target: the cwd-relative path, or "." for the cwd itself. */
+export const relativeTarget = (cwd, targetDir) => path.relative(cwd, targetDir) || ".";

package/dist/help.js

@@ -0,0 +1,34 @@
+import { brand, brandTag, bold, dim } from "./colors.js";
+import { pkg } from "./pkg.js";
+import { TEMPLATES } from "./templates.js";
+export const printHelp = () => {
+    const templates = TEMPLATES.map((t) => t.name).join(", ");
+    const lines = [
+        "",
+        `  ${brandTag(" create-extro ")} ${dim(`v${pkg.version}`)}`,
+        "",
+        `  Scaffold a new ${brand("Extro")} extension.`,
+        "",
+        `  ${bold("Usage")}`,
+        `    ${brand("create-extro")} [directory] [options]`,
+        "",
+        `  ${bold("Options")}`,
+        `    -t, --template <name>   Template to use: ${dim(templates)}`,
+        `        --pm <manager>      Force a package manager: ${dim("npm, pnpm, yarn, bun")}`,
+        `        --install           Install dependencies`,
+        `        --no-install        Skip installing dependencies`,
+        `        --git               Initialize a git repository`,
+        `        --no-git            Skip git initialization`,
+        `        --overwrite         Overwrite the target directory if it is not empty`,
+        `    -y, --yes               Accept defaults and skip the prompts`,
+        `    -h, --help              Show this help`,
+        `    -v, --version           Show the version`,
+        "",
+        `  ${bold("Examples")}`,
+        `    ${dim("pnpm create extro")}`,
+        `    ${dim("pnpm create extro my-extension")}`,
+        `    ${dim("npm create extro@latest my-extension -- --no-install")}`,
+        "",
+    ];
+    console.log(lines.join("\n"));
+};

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/pkg-manager.js

@@ -0,0 +1,21 @@
+const KNOWN = ["npm", "pnpm", "yarn", "bun"];
+export const isPkgManager = (name) => KNOWN.includes(name);
+/**
+ * @describe Resolves the package manager that invoked the scaffolder from
+ * `npm_config_user_agent` (set by every runner, e.g. `pnpm/10.15.1 ...`), so
+ * `pnpm create extro` defaults to pnpm and `npm create` defaults to npm.
+ * Falls back to npm when the agent is absent (an unusual direct invocation).
+ */
+export const detectPkgManager = (userAgent = process.env.npm_config_user_agent) => {
+    if (!userAgent)
+        return "npm";
+    const name = userAgent.split(" ")[0]?.split("/")[0];
+    return name && isPkgManager(name) ? name : "npm";
+};
+/** The argv that installs dependencies. yarn installs with a bare invocation. */
+export const installArgs = (pm) => pm === "yarn" ? [] : ["install"];
+/**
+ * @describe The command a user types to run a package script. npm and bun need
+ * the explicit `run`; pnpm and yarn forward bare script names.
+ */
+export const runScript = (pm, script) => pm === "npm" || pm === "bun" ? `${pm} run ${script}` : `${pm} ${script}`;

package/dist/pkg.js

@@ -0,0 +1,5 @@
+import { readFileSync } from "node:fs";
+// Read at runtime rather than `import`ing package.json: it lives outside
+// `rootDir: src`, so tsc would reject a static import. The URL resolves the
+// same in the workspace (dist/pkg.js -> ../package.json) and once published.
+export const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));

package/dist/scaffold.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const TEMPLATES_ROOT = fileURLToPath(new URL("../templates", import.meta.url));
+// Dotfiles ship under `_`-prefixed names so npm does not rewrite them at
+// publish time (it renames a packaged `.gitignore` to `.npmignore`) and so
+// they survive `npm pack`. They are restored to their real names on copy.
+const RENAME = {
+    _gitignore: ".gitignore",
+    "_env.example": ".env.example",
+};
+export const templateDir = (name) => path.join(TEMPLATES_ROOT, name);
+/**
+ * @describe Copy a template into the target directory, restoring `_`-prefixed
+ * dotfiles to their real names and stamping the chosen package name into
+ * package.json. Everything else is copied byte-for-byte.
+ */
+export const scaffold = ({ templateName, targetDir, packageName, }) => {
+    copyDir(templateDir(templateName), targetDir, packageName);
+};
+const copyDir = (srcDir, destDir, packageName) => {
+    fs.mkdirSync(destDir, { recursive: true });
+    for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, RENAME[entry.name] ?? entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, destPath, packageName);
+        }
+        else if (entry.name === "package.json") {
+            writePackageJson(srcPath, destPath, packageName);
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+};
+const writePackageJson = (srcPath, destPath, packageName) => {
+    const manifest = JSON.parse(fs.readFileSync(srcPath, "utf8"));
+    manifest.name = packageName;
+    fs.writeFileSync(destPath, `${JSON.stringify(manifest, null, 2)}\n`);
+};

package/dist/system.js

@@ -0,0 +1,30 @@
+import spawn from "cross-spawn";
+import { installArgs } from "./pkg-manager.js";
+/** Install dependencies in `cwd` with the given manager. Returns success. */
+export const installDependencies = (pm, cwd) => {
+    const result = spawn.sync(pm, installArgs(pm), { cwd, stdio: "ignore" });
+    return result.status === 0;
+};
+/** Whether a `git` binary is on PATH. */
+export const isGitInstalled = () => spawn.sync("git", ["--version"], { stdio: "ignore" }).status === 0;
+/** Whether `dir` already sits inside a git work tree (so we should not re-init). */
+export const isInsideGitRepo = (dir) => spawn.sync("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: dir,
+    stdio: "ignore",
+}).status === 0;
+/**
+ * @describe Initialize a git repository in `dir` with a single initial commit.
+ * The commit is best-effort: a missing git identity fails only the commit, not
+ * the init, so a fresh checkout still lands as a valid (if uncommitted) repo.
+ * Returns whether `git init` succeeded.
+ */
+export const initGitRepo = (dir) => {
+    const opts = { cwd: dir, stdio: "ignore" };
+    const inited = spawn.sync("git", ["init", "-b", "main"], opts).status === 0 ||
+        spawn.sync("git", ["init"], opts).status === 0;
+    if (!inited)
+        return false;
+    spawn.sync("git", ["add", "-A"], opts);
+    spawn.sync("git", ["commit", "-m", "Initial commit from create-extro"], opts);
+    return true;
+};

package/dist/templates.js

@@ -0,0 +1,14 @@
+// One curated, minimal starter. Extro's premise is that surfaces are files you
+// drop under src/app/, so the scaffold ships the canonical surface (a popup)
+// plus a background worker and lets the convention add the rest, rather than
+// pre-generating every surface. The registry stays a list so more starters can
+// be added later without reshaping the call sites.
+export const TEMPLATES = [
+    {
+        name: "default",
+        label: "Default",
+        hint: "a popup and a background service worker",
+    },
+];
+export const DEFAULT_TEMPLATE = "default";
+export const isTemplate = (name) => TEMPLATES.some((template) => template.name === name);

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "create-extro",
+  "version": "0.0.0",
+  "description": "Scaffold a new Extro extension. The official starter for the Extro framework.",
+  "keywords": [
+    "extro",
+    "create-extro",
+    "chrome-extension",
+    "browser-extension",
+    "manifest-v3",
+    "scaffold",
+    "starter",
+    "vite",
+    "react"
+  ],
+  "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/create-extro"
+  },
+  "type": "module",
+  "bin": {
+    "create-extro": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "cross-spawn": "^7.0.6",
+    "picocolors": "^1.1.1",
+    "validate-npm-package-name": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/validate-npm-package-name": "^4.0.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/templates/default/README.md

@@ -0,0 +1,31 @@
+# Extro extension
+
+An extension scaffolded with [Extro](https://github.com/Sahilm416/extro): file-based entrypoints, automatic Manifest V3 generation, and React routing, all driven by a single Vite plugin.
+
+## Develop
+
+```bash
+pnpm dev
+```
+
+`extro dev` starts a Vite dev server with HMR and writes an unpacked extension to `output/chrome-mv3-dev`. Open `chrome://extensions`, turn on Developer mode, and load that directory with **Load unpacked**. It stays loaded across dev restarts, so there is no manual reload between sessions.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Writes a production bundle to `output/chrome-mv3-prod`, ready to load or zip for the Chrome Web Store.
+
+## Project layout
+
+This starter ships two surfaces. Add more by dropping a file under `src/app/`:
+
+```
+src/app/
+├── popup/page.tsx        the toolbar popup
+└── background/index.ts   the background service worker
+```
+
+Add `options/page.tsx`, `sidepanel/page.tsx`, or `content/page.tsx` to grow into the other surfaces. Configure the generated manifest in `extro.config.ts`. See the [Extro docs](https://github.com/Sahilm416/extro) for the full reference.

package/templates/default/_env.example

@@ -0,0 +1,5 @@
+# Copy to .env.development / .env.production and fill in.
+# Only EXTRO_PUBLIC_* is inlined into surfaces via import.meta.env. Anything
+# else stays build-time only and is never shipped into a bundle.
+
+EXTRO_PUBLIC_GREETING=Hello from Extro

package/templates/default/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+output
+.output
+
+*.tsbuildinfo
+*.log
+
+.env
+.env.*
+!.env.example
+
+.DS_Store

package/templates/default/extro.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "extrojs"
+
+export default defineConfig({
+  name: "My Extension",
+  description: "An extension built with Extro.",
+  permissions: ["storage"],
+})

package/templates/default/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "extro-extension",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "extro dev",
+    "build": "extro build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "extrojs": "^0.3.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/chrome": "^0.1.42",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/default/public/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <rect x="13.6" y="13.6" width="56" height="56" rx="10.08" fill="#0a0a0a" />
+  <rect x="30.4" y="30.4" width="56" height="56" rx="10.08" fill="#CC785C" />
+</svg>

package/templates/default/src/app/background/index.ts

@@ -0,0 +1,6 @@
+// The background service worker. Runs in the extension's own context with full
+// access to the chrome.* APIs. This file is the entrypoint; import freely.
+
+chrome.runtime.onInstalled.addListener(() => {
+  console.log("Extension installed")
+})

package/templates/default/src/app/popup/page.tsx

@@ -0,0 +1,29 @@
+import { useState } from "react"
+import { asset } from "extrojs/asset"
+
+export default function Popup() {
+  const [count, setCount] = useState(0)
+
+  return (
+    <div style={{ width: 240, padding: 16, fontFamily: "system-ui, sans-serif" }}>
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          marginBottom: 16,
+        }}
+      >
+        {/* asset() wraps chrome.runtime.getURL. logo.svg lives in public/. */}
+        <img src={asset("logo.svg")} width={20} height={20} alt="Extro" />
+        <strong>My Extension</strong>
+      </div>
+
+      <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+        <button onClick={() => setCount((n) => n - 1)}>-</button>
+        <span style={{ minWidth: 24, textAlign: "center" }}>{count}</span>
+        <button onClick={() => setCount((n) => n + 1)}>+</button>
+      </div>
+    </div>
+  )
+}

package/templates/default/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["chrome"]
+  },
+  "include": ["src", "extro.config.ts"]
+}