Contributing

First Time Contributing

It's easy! Here are some resources to get started:

• https://www.youtube.com/embed/dSl_qnWO104
• https://docs.github.com/en/get-started/quickstart/contributing-to-projects

Project Goals

The goal of webext-core is to create useful, targeted, quality utilities for creating and publishing web extensions. Not just Chrome extensions, but web extensions that work on all browsers, for all manifest versions.

With that in mind, there's a couple of expectations I have around new code:

• Code is written in TypeScript and packages provide great TypeScript support.
• Utilities support all browsers.
• Well unit tested. I won't require 100% coverage, but it should be close.

Before You Contribute

If you're just fixing a bug or improving the docs, feel free to open a PR, no questions asked!

If you want to add a new package or feature, open an issue first. That way we can collaborate and make sure it fits the purpose listed in the project goals. If you open a PR, but it's not something I want to maintain or it doesn't fit this project, you will have wasted your time. We both have lives to live 😃.

Development Setup

You'll need to install Bun before contributing.

Then you can fork the repo, install the dependencies, and build the packages for the first time!

git clone {your-fork}
cd webext-core
bun i
bun run build

Project Layout

The webext-core repo is a monorepo containing all the packages under the @webext-core scope.

Here's an overview of the main directories:

• docs: The website for https://webext-core.aklinker1.io
• packages/*: Each NPM package has it's own directory
• packages/*-demo: Some packages have a demo extension

Each package's README (packages/*/README.md) will have additional details for setting up or testing the package.

In general, all packages are the same.

• They all have a README.md with additional documentation
• They all use src/index.ts as the entrypoint
• They all use tsup for building the final package for NPM
• They're all written in TypeScript
• They all share the same basic scripts for common tasks

Scripts

In the root directory, you can run the following scripts:

bun run build  # Run the build script for all packages
bun run format # Run prettier to format all your files

Or cd into a package's directory and run these scripts

bun run build   # Build the package and it's dependencies
bun run check   # Check for type errors
bun run test    # Run unit tests in watch mode

Each directory might have additional scripts you can run. See each package.json for a complete list.

Publishing Packages

Only owners of the repo can publish a new version of the extension. But in summary: other than pressing the button, everything is automated via the "Publish Packages" GitHub action. That includes:

• Bumping the package version
• Generating release notes
• Creating a GitHub release
• Publishing to NPM

The action will run these steps for a set list of packages.

There is no way to filter or prevent a package from being publish when running this command. If there's a feat or fix unpublished for any package, it will get published. Packages without any features or fixes will be skipped.

Commit Style

If you are submitting PRs, don't worry about this! A maintainer will squash and merge your PR with a commit message in the correct style.

Each commit's title effects the publishing process. The style is based on conventional commits, but using scoped prefixes. Use the fix(package-name): and feat(package-name): prefixes when committing a change. For example, the following commit history:

docs: Fixed typos
fix(storage): Some change
feat(proxy-service): Some new feature
chore: Refactored scripts

Would result in a patch version change for @webext-core/storage (like from 1.2.1 → 1.2.2), and a minor change for @webext-core/proxy-service (like from 1.3.4 → 1.4.0).

Publishing a New Package

When publishing a package for the first time, publish it by hand and create a release manually.

cd packages/package-name
pnpm publish

Updating Docs

This documentation website is continuously deployed on Vercel. You do not need to run any actions or scripts to publish the docs. Just push changes to main.