-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* README update * README update * README update * Address feedback
- Loading branch information
1 parent
273fa5a
commit 2376e15
Showing
1 changed file
with
80 additions
and
60 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,103 +1,123 @@ | ||
## Web Monetization Extension | ||
<h1 align="center">Web Monetization Extension</h1> | ||
|
||
![Github Actions CI](https://github.com/interledger/web-monetization-extension/actions/workflows/sanity.yml/badge.svg?branch=main) | ||
[![Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://prettier.io/) | ||
|
||
Web Monetization is a browser extension that detects Web Monetization on websites using a browser API that allows the | ||
creation of a payment stream from the user agent to the website. This extension is built with React, TypeScript, and | ||
Vite. | ||
The Web Monetization browser extension is an open source implementation of the Web Monetization draft specification - learn more [here](https://webmonetization.org/specification/). The extension is built with React and TypeScript. | ||
|
||
### Contributing | ||
## Local Development Environment | ||
|
||
Please read the [contribution guidelines](.github/CONTRIBUTING.md) before submitting contributions. All contributions must adhere to our [code of conduct](.github/CODE_OF_CONDUCT.md). | ||
|
||
### Installation | ||
### Prerequisites | ||
|
||
1. Clone the repository from GitHub: `git clone https://github.com/interledger/web-monetization-extension.git` | ||
2. Navigate to the project directory: `cd web-monetization-extension` | ||
3. Install the dependencies using PNPM: `pnpm install` | ||
- [NVM](https://github.com/nvm-sh/nvm) - or another Node Version Manager | ||
- [PNPM](https://pnpm.io/) | ||
|
||
### Development | ||
## Setup | ||
|
||
To run the extension in development mode with hot reload, use the following command: | ||
### Environment Setup | ||
|
||
`pnpm dev` | ||
```sh | ||
# Install Node 20 | ||
nvm install lts/iron | ||
nvm use lts/iron | ||
|
||
This command builds the extension using Vite's hot reload feature, allowing you to see immediate changes in the browser | ||
as you modify the code. | ||
# Install pnpm using Corepack | ||
corepack enable | ||
``` | ||
|
||
### Building the Extension | ||
If you do not have `corepack` installed locally you can use `npm` or `yarn` to install `pnpm`: | ||
|
||
To build the extension for production, use the following command: | ||
```sh | ||
npm install -g pnpm | ||
# or | ||
yarn install -g pnpm | ||
``` | ||
|
||
`pnpm build` | ||
For alternative methods of installing `pnpm`, you can refer to the [official `pnpm` documentation](https://pnpm.io/installation). | ||
|
||
### Building the Extension for Firefox | ||
To install dependencies, execute: | ||
|
||
To build the extension for Firefox, use the following command: | ||
```sh | ||
pnpm i | ||
``` | ||
|
||
`pnpm build firefox` | ||
### Commands | ||
|
||
This command transpiles the TypeScript code and generates a production-ready build of the extension in the dist | ||
directory. | ||
All commands are run from the root of the project, from a terminal: | ||
|
||
### Installing the Extension in Chrome | ||
| Command | Action | | ||
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| `pnpm dev <TARGET>` | Builds the extension for development, for a specified target (`chrome` or `firefox`). If the target is not specified the script will build the extension for a Chromium based browser. Output folder: `dev`. | | ||
| `pnpm build <TARGET>` | Builds the extension for production usage, for a specified target (`chrome` or `firefox`). If the target is not specified the script will build the extension for all available targets. Output folder: `dist`. | | ||
| `pnpm test` | Runs all test files using Jest. | | ||
|
||
To install the extension in Chrome, follow these steps: | ||
### Installing the extension from source, in Chromium based browsers (Chrome, Opera, Edge, Brave, Arc) | ||
|
||
1. Extract the Files:<br/> | ||
Extract the contents of the ZIP file to a folder on your computer. | ||
1. <b>Build the extension with `pnpm build chrome`</b> | ||
|
||
2. Open Chrome's Extensions Page:<br/> | ||
Open Chrome, click the three dots in the top-right corner, go to "More tools," and select "Extensions." | ||
1. <b>Open extensions page</b><br/> | ||
In Chrome, click the three dots in the top-right corner. Look for the `Extensions` options and select `Manage extesions`. | ||
|
||
3. Enable Developer Mode:<br/> | ||
Enable "Developer mode" using the toggle switch at the top-right of the Extensions page. | ||
1. <b>Enable developer mode</b><br/> | ||
To enable `Developer mode`, use the switch at the top-right of the extensions page. | ||
|
||
4. Load the Extension:<br/> | ||
Click the "Load unpacked" button that appears after enabling Developer mode. | ||
1. <b>Load the extension</b><br/> | ||
After enabling `Developer mode`, new buttons should appear in the top-left corner. Click the `Load unpacked` one and choose the <b>folder</b> that contains the extension files (in the `dist` folder, look for the `chrome` one with the `manifest.json` file). | ||
|
||
5. Select the Extension Folder:<br/> | ||
Choose the folder containing the extracted extension files (with the manifest.json file). | ||
### Installing the extension from source, in Firefox | ||
|
||
6. Pin the Extension:<br/> | ||
Click on the puzzle piece icon in the top-right corner of Chrome, and pin the Web Monetization extension. | ||
1. <b>Build the extension with `pnpm build firefox`</b> | ||
|
||
### Installing the Extension in Firefox | ||
1. <b>Open Firefox's add-ons page</b><br/> | ||
Open Firefox, click the three horizontal lines in the top-right corner, and choose `Add-ons and themes`. | ||
|
||
1. Extract the Files:<br/> | ||
Extract the contents of the ZIP file to a folder on your computer. | ||
1. <b>Navigate to the add-ons debugging page</b><br/> | ||
In the add-ons page, click the gear icon and select "Debug Add-ons". | ||
|
||
2. Open Firefox's Add-ons Page:<br/> | ||
Open Firefox, click the three horizontal lines in the top-right corner, and choose "Add-ons." | ||
1. <b>Load the extension</b><br/> | ||
Look for the `Temporary Extensions` section and expand its content. After expanding its content click on the `Load Temporary Add-on...` button and select the `manifest.json` file (in the `dist` folder, go in the `firefox` folder and select the manifest file). | ||
|
||
3. Access Extensions Settings:<br/> | ||
In the Add-ons Manager, click the gear icon in the top-right corner and select "Install Add-on From File..." | ||
### Project structure | ||
|
||
4. Select the Extension File:<br/> | ||
Navigate to the folder where you extracted the extension files and select the manifest.json file or the main folder of the extension. | ||
Inside this project, you'll see the following folders and files: | ||
|
||
### Testing the Extension | ||
``` | ||
. | ||
├── .github/ # GitHub Workflows | ||
├── scripts/ # Script to build the extension (production, development) | ||
├── src/ # Extension's source code | ||
│ ├── _locales/ # Files for multi-lang support | ||
│ ├── assets/ # Images for the extension (icon, etc.) | ||
│ ├── background/ # Source code for the background script | ||
│ ├── content/ # Source code for the content script | ||
│ │ ├── static/ # WM polyfill | ||
│ ├── popup/ # Source code for the popup UI | ||
│ └── shared/ # Shared utilities | ||
├── webpack/ # Webpack configuration | ||
├── jest.config.ts | ||
├── jest.setup.ts | ||
├── package.json | ||
├── tailwind.config.ts | ||
└── tsconfig.json | ||
``` | ||
|
||
To run the tests, use the following command: | ||
## Contributing | ||
|
||
`pnpm test` | ||
Please read the [contribution guidelines](.github/CONTRIBUTING.md) before submitting contributions. All contributions must adhere to our [code of conduct](.github/CODE_OF_CONDUCT.md). | ||
|
||
This command runs the tests using Jest and generates a coverage report in the coverage directory. | ||
## Roadmap | ||
|
||
### Linting and Pre-Commit Hooks | ||
[Web Monetization Roadmap](https://github.com/orgs/interledger/projects/6/views/1?filterQuery=label%3A%22web+monetization%22) | ||
|
||
The extension is set up with ESLint and Prettier for code linting and formatting. Husky and lint-staged are configured | ||
to enforce linting and formatting rules before each commit. When you commit changes, Husky will run the linting and | ||
formatting tasks to ensure code quality. | ||
|
||
## License | ||
|
||
This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) | ||
file for details | ||
See the [open issues](https://github.com/interledger/web-monetization-extension/issues) for a full list of proposed features (and known issues). | ||
|
||
## Feedback and Issues | ||
|
||
If you encounter any issues or have feedback, please open an issue on | ||
the [GitHub repository](https://github.com/interledger/web-monetization-extension/issues). We appreciate your feedback | ||
and contributions! | ||
|
||
## License | ||
|
||
This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) | ||
file for details |