{"id":13603250,"url":"https://github.com/AminoffZ/catonaut","last_synced_at":"2025-04-11T14:30:50.718Z","repository":{"id":197839288,"uuid":"699273788","full_name":"AminoffZ/catonaut","owner":"AminoffZ","description":"Astro + Bun browser extension template.","archived":false,"fork":false,"pushed_at":"2024-10-14T20:28:46.000Z","size":286,"stargazers_count":80,"open_issues_count":3,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T12:07:50.523Z","etag":null,"topics":["astro","astro-template","bun","chrome-extension","chrome-extension-boilerplate","chrome-extension-starter","chrome-extension-template","mv3","template","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AminoffZ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-02T09:55:17.000Z","updated_at":"2025-03-01T16:57:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"ab0e126b-c971-4251-914d-406e2ba848e5","html_url":"https://github.com/AminoffZ/catonaut","commit_stats":null,"previous_names":["aminoffz/catonaut"],"tags_count":0,"template":true,"template_full_name":"AminoffZ/bun-browser-extension-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AminoffZ%2Fcatonaut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AminoffZ%2Fcatonaut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AminoffZ%2Fcatonaut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AminoffZ%2Fcatonaut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AminoffZ","download_url":"https://codeload.github.com/AminoffZ/catonaut/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248419648,"owners_count":21100213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astro","astro-template","bun","chrome-extension","chrome-extension-boilerplate","chrome-extension-starter","chrome-extension-template","mv3","template","typescript"],"created_at":"2024-08-01T18:01:59.231Z","updated_at":"2025-04-11T14:30:50.692Z","avatar_url":"https://github.com/AminoffZ.png","language":"TypeScript","funding_links":[],"categories":["chrome-extension","ℹ️ Repositories/Starter Kits/Components","TypeScript"],"sub_categories":[],"readme":"\u003cimg src=\"https://github.com/AminoffZ/catonaut/blob/main/public/assets/images/icon128.png?raw=true\" align=\"right\" width=\"128\" height=\"128\" title=\"catonaut\"\u003e\n\n# Catonaut\n\nA browser extension builder with Astro and Bun\n[Node.js + npm Version here](https://github.com/AminoffZ/catonaut-node) 💚\n\n## 🏆 Showcase\n\n- [GitHub Repo Size](https://github.com/AminoffZ/github-repo-size) - Shows the total size of repos and of files and folders.\n- [Steam Multisell](https://github.com/AminoffZ/steam-multisell) - UI for multiselling on the Steam marketplace.\n- [Google Maps Button](https://github.com/AminoffZ/google-maps-button) - Re-adds the Google Maps link to searches (removed in EU).\n\n## 🌟 Features\n\n- 📘 Typescript for a better developer experience\n- 🚄 Bun for blazing fast development\n- ⏱ Manifest version 3 (MV3) for priority publishing\n- 🚀 Astro enabling flexible popup design\n- 🐱‍🏍 Cool Mascot\n\n## 📣 Community\n\nHead over to the [community page](https://github.com/AminoffZ/catonaut/discussions) for announcements, Q\u0026A, collaboration and inspiration!\n\n## 🚧 Before starting\n\nMake sure you have some understanding of extension development. Here are some resources:\n\n- [Chrome](https://developer.chrome.com/docs/extensions/mv3/getstarted/development-basics/)\n- [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension)\n\n## 🛠️ Quick Setup\n\nYou can use Bun to quickly initialize a new project:\n\n```bash\nbun create catonaut [AppName]\n```\n\nOR\n\n```bash\nbunx create-catonaut [AppName]\n```\n\nFor more information, refer to [create-catonaut](https://github.com/AminoffZ/create-catonaut)\n\n## 🛠️ Setup\n\n![image](https://github.com/AminoffZ/catonaut/assets/55880031/261b38a7-09d5-417a-a908-807c29bf37fb)\n\nUse the template or clone the project, navigate into the project folder and run:\n\n```bash\nbun i\n```\n\n### The manifest\n\nThe manifest is a JSON file that defines the extension's name, version, functionality, permissions, and other details. It is required for all browser extensions and must be carefully constructed to ensure the extension is secure and efficient (and works).\n\nFor additional information visit the [manifest](https://developer.chrome.com/docs/extensions/mv3/manifest/) documentation page. Please note that some browsers, like [Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_specific_settings), require specific information for extensions to work.\n\nExample:\n\n```json\n{\n  \"manifest_version\": 3,\n  \"name\": \"Your Extension Name\",\n  \"version\": \"0.1.0\",\n  \"web_accessible_resources\": [\n    {\n      \"matches\": [\"http://*/*\"],\n      \"resources\": [\"assets/styles/content.css\"]\n    }\n  ],\n  \"content_scripts\": [\n    {\n      \"matches\": [\"http://*/*\"],\n      \"js\": [\"content.js\"],\n      \"css\": [\"content.css\"]\n    }\n  ],\n  \"background\": {\n    \"service_worker\": \"background.js\"\n  },\n  \"action\": {\n    \"default_popup\": \"index.html\"\n  },\n  \"browser_specific_settings\": {\n    \"gecko\": {\n      \"id\": \"yourcustom@token.io\",\n      \"strict_min_version\": \"42.0\"\n    }\n  },\n  \"icons\": {\n    \"16\": \"assets/icon16.png\",\n    \"32\": \"assets/icon32.png\",\n    \"48\": \"assets/icon48.png\",\n    \"128\": \"assets/icon128.png\"\n  }\n}\n```\n\n## Modifying a page\n\n### JavaScript\n\nTo add JavaScript to modify the page, edit the src/scripts/content.ts. It will be compiled to JavaScript when you build the extension. Look at **Build** for more information.\n\n### What is a content.ts?\n\nA content script is a JavaScript file that runs in the context of a web page and can modify its content and behavior. The content script can read and modify the HTML, CSS, and JavaScript of the web page, and can be used to add new functionality, modify existing functionality, or manipulate the content of the page in various ways.\n\nThe name \"content.ts\" is often used as a convention to indicate that the file contains the code for a content script. However, developers are free to use any filename they like for their content script.\n\nFor additional information visit the [content script](https://developer.chrome.com/docs/extensions/mv3/content_scripts/) documentation page.\n\n### What is a background.ts?\n\nBackground scripts create service workers that live independent of any other window or tab. These allows extensions to observe and act in response to events. Commonly leveraging Chrome's Browser API they can be used to listen for events, such as the addition of a new tab or navigation to a new URL. They can also be used to keep state across multiple pages within the extension.\n\nFor example, a background script can listen for an event, such as the user clicking on the browser action icon, then dispatch an event to the content script in the active tab to take action.\n\nFor additional information visit the [background script](https://developer.chrome.com/docs/extensions/mv3/background_pages/) documentation page.\n\n### CSS\n\nTo add CSS to the DOM, you need to create a CSS file in the public folder and reference it in the manifest.json. The above manifest example assumes there is a file called content.css in the public/assets/styles/ folder.\n\n### HTML\n\nFor manipulating the DOM, HTML can be added or changed [programmatically](https://developer.mozilla.org/en-US/docs/Web/API/Document) using JavaScript. Your best friends for achieving this are most likely going to be [document.querySelector()](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector), [document.createElement()](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement) and [Node.insertBefore()](https://developer.mozilla.org/en-US/docs/Web/API/Node/insertBefore).\n\n## The Popup\n\nYou can modify the popup just like you would modify an Astro app. You can start by modifying the src/pages/index.astro file. When starting, there is a Placeholder component inside the body that you can modify at src/components/Placeholder.astro or remove.\n\n### Changing the icon\n\nYou can generate the icons from an image.\n\n1. Replace the public/assets/images/example.png\n2. Run the following command in the terminal:\n\n```bash\nbun run icons\n```\n\nThis will create the icons referenced by default in the manifest of sizes 16, 32, 48 and 128.\n\n### Testing the popup\n\nYou can test the popup by running the following command in the terminal:\n\n```bash\nbun run dev\n```\n\nThis will start a development server and open the popup in your browser as if it were a website. You can then modify the popup and see the changes in real time.\n\n## Testing your extension\n\nThankfully you don't have to get your extension published before being able to test it. Refer to [**Before starting**](https://github.com/AminoffZ/catonaut/tree/main#-before-starting) for information about testing an extension, also referred to as loading unpacked extensions. You do however need to build the extension to be able to test it.\n\n## Build\n\nTo build the extension, run:\n\n```bash\nbun run build\n```\n\n## 🏗️ Project structure\n\n\u003cpre\u003e\nroot\n├── 📁 build-tools\n├── 📁 dist\n├── 📁 public\n└── 📁 src\n    ├── 📁 pages\n    └── 📁 scripts\n        └── 📁 internal\n\u003c/pre\u003e\n\n### build-tools\n\nContains tools used for building the extension. You should not need to modify anything in this folder.\n\n### dist\n\nContains the built extension. This folder can be loaded as an unpacked extension.\n\n### public\n\nContains the public files. This folder is copied to the dist folder when building the extension. The files are not modified in any way.\n\n### src\n\nContains the source files. This is where you will be doing most of your work.\n\n### src/pages\n\nContains the index.astro. This is compiled to HTML when building the extension and functions as the popup. I find adding a folder src/components/ and importing them in the index.astro to be a good way to structure the popup.\n\n### src/scripts\n\nContains the content.ts and background.ts. These are compiled to JavaScript when building the extension. The content.ts is injected into the DOM of the page.\n\n### src/scripts/internal\n\nNot necessary although I find that a useful way to structure the scripts is to add files in this folder and import their functionality in the content.ts and background.ts.\n\n## 💅 Formatting\n\nI added a .prettierrc for contributing. If building for your own purposes, feel free to remove it.\nTo format with the provided configuration, run:\n\n```bash\nbun run format\n```\n\n## LICENSE\n\nCatonaut is under [MIT License](https://github.com/AminoffZ/catonaut/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAminoffZ%2Fcatonaut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAminoffZ%2Fcatonaut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAminoffZ%2Fcatonaut/lists"}