Catonaut is a Manifest V3 browser extension starter template that uses Astro to build the popup UI and Bun as the runtime and bundler.
What is Catonaut?
Catonaut is a GitHub template that scaffolds a Chrome and Firefox extension project with Astro and Bun. It takes TypeScript source files for content and background scripts plus an Astro popup page, and outputs a buildable extension in the dist folder that can be loaded unpacked. The template targets Manifest V3, includes Firefox-specific browser settings, and has a companion Node.js + npm version in the catonaut-node repository. It is authored by AminoffZ and released under the MIT License.
Key Features
- TypeScript development — content and background scripts are written in TypeScript in src/scripts and compiled to JavaScript when building.
- Bun toolchain — Bun handles dependency installation, the popup dev server, building, formatting, and project generation;
bun create catonautscaffolds a new extension. - Manifest V3 — the included manifest.json example defines content scripts, a background service worker, and an action popup, matching MV3 requirements for priority publishing.
- Astro popup — the popup is an Astro application; you edit src/pages/index.astro and can organize components in src/components.
- Icon generation — after replacing public/assets/images/example.png,
bun run iconscreates icons at 16, 32, 48, and 128 pixel sizes referenced by the manifest. - Popup dev server —
bun run devserves the popup as a standalone website in your browser for real-time UI development. - Firefox support — browser_specific_settings with a Gecko ID and strict_min_version are provided in the manifest example.
- Structured project layout — dedicated folders for build-tools, dist, public, and src; dist is the output you load as an unpacked extension.
Who should use Catonaut?
- Extension developers new to MV3 — want a pre-configured manifest, content script, and background service worker to start from.
- Bun users — want a fast all-in-one toolchain that avoids npm and uses Bun for everything from scaffolding to builds.
- Developers building cross-browser extensions — can use the included Firefox-specific manifest settings alongside Chrome-focused docs.
Use cases
- Hobbyist developers: scaffold a browser extension with
bun create catonaut [AppName]to quickly get a working Manifest V3 project with a popup. - Teams modernizing legacy extensions: rewrite an existing extension using TypeScript, Astro, and Bun, and load the built dist folder as an unpacked extension for testing.
- Open-source maintainers: use the showcase projects (GitHub Repo Size, Steam Multisell, Google Maps Button) as real-world examples of what this template can produce.
How does Catonaut work?
After cloning the template or running the create command, install dependencies with bun i. Edit the source files: the manifest at the root, the popup in src/pages/index.astro, and the content and background scripts in src/scripts. Run bun run build to compile everything into the dist folder, then load that folder as an unpacked extension in Chrome or Firefox. For popup-only UI work, use bun run dev to preview it as a normal web page.
Pricing
Catonaut is free and open source under the MIT License, so it can be used in personal and commercial extension projects without payment.
FAQ
Is Catonaut free?
Yes. The template is released under the MIT License, meaning you can use, modify, and distribute it freely, including in commercial projects.
What does Catonaut build?
Catonaut builds a browser extension in the dist folder as an unpacked extension. It compiles TypeScript content and background scripts, generates the popup from Astro, and copies public assets into the output.
Do I need to know browser extension development?
The README recommends having some understanding of extension development before starting, and links to Chrome and Firefox documentation for beginners. The template handles the build setup, but you still need to write the extension logic.
Can I use Catonaut with npm and Node.js instead of Bun?
Yes. The author provides a separate repository called catonaut-node that offers a Node.js + npm version of the same template, for developers who don't use Bun.
How do I test the extension without publishing it?
Run bun run build to create the dist folder, then open your browser's extension management page and load the dist folder as an unpacked extension. You can also test the popup alone with bun run dev.
