Skip to content

Latest commit

 

History

History
195 lines (139 loc) · 12.7 KB

README.md

File metadata and controls

195 lines (139 loc) · 12.7 KB
Raw

Create React WebExtension Build Status

Develop WebExtensions with no build configuration.

WebExtension API is the widely adopted system for extending and modifying the capability of a browser.

  • Quick Start – How to create a new extension.
  • User Guide – How to develop extensions bootstrapped with Create React WebExtension.
  • WebExtensions on MDN - API reference and tutorials for developing extensions.
  • Examples - Example extensions from MDN.

This project is a fork of the excellent Create React App (CRA) project.

The latest version of Create React WebExtension (CRWX) is based on create-react-app#v1.0.10.

Highlights

  • Get started immediately, no need to install or configure tools like Webpack or Babel.
    They are preconfigured and hidden so that you can focus on the code.
  • Live reload of JavaScript and CSS as you work on your extension. Works seamlessly in Chrome, Firefox, and Opera, even on pages protected by HTTPS and Content Security Policy.
  • You can use TypeScript or JavaScript and import modules between them.
  • At any time, you can "eject" Create React WebExtension from your project to relinquish full control over the webpack configuration.

Limitations

  • This is a new project. You'd be an early adopter.
  • The User Guide is 90% relevant, but hasn't been updated yet. This project is mostly a super set of CRA features.
  • Not tested on Windows.
  • The example extension works in all major browsers. However, CRWX does not automatically make your extension code cross platform. To target multiple browsers you have to take care to use polyfills and to not use incompatible properties in the manifest.json file.
  • CRWX will create a production build, ready for packaging. However, the packaging process itself varries significantly between browsers and is considered out of scope for this project.

If something doesn’t work please be kind and report an issue.

Quick Start

Installation

Install yarn or npm.

Install facebookincubator/create-react-app once globally:

yarn global add create-react-app

Create a New Extension

To start working on a new extension, run:

create-react-app my-extension --scripts-version react-scripts-webextension
cd my-extension
yarn start

Follow the instructions on the screen to install the extension in your browser:

Screenshot of terminal on yarn start

Once installed in your browser, the example extension navigates to the latest version of the User Guide and injects itself as a content script on that page.

Screenshot of browser when installed

Directory Structure

The directory structure of a newly generated project looks like this:

.
├── README.md
├── package.json
├── tsconfig.json
├── public
│   ├── icon-128.png
│   ├── icon-16.png
│   └── manifest.json
└── src
    └── guide
        ├── background-script
        │   ├── _bundle
        │   └── index.js
        ├── content-script
        │   ├── _bundle
        │   ├── Search.css
        │   ├── Search.tsx
        │   ├── index.css
        │   └── index.js
        └── popup
            ├── _bundle
            ├── index.html
            ├── index.css
            └── index.js

Starting from a Clean Slate

If you find the example code confusing or not helpful, you can start with an empty code base:

  1. Delete everything from the src and public directories.
  2. Run yarn start and follow the error messages.

Refer to the User Guide for solutions to common tasks.

List of Commands

Create React WebExtension supports four commands:

  • start - Build and watch the extension in development mode.
  • test - Run the test watcher in an interactive mode.
  • build - Create a production build.
  • eject - Remove Create React WebExtension from your project and relinquish control.

Each command is described in more detail bellow.

yarn start (or npm run start)

Running yarn start populates the build/ directory with the development build of the example extension.

Changing any JavaScript in the src/ directory or any file in the public/ directory will intelligently reload the extension and all affected tabs.

Changing any CSS in the src/ directory will live update the extension on the screen, without reloading.

You will see any build errors and lint warnings in the console.

Build errors

yarn test (or npm run test)

By default, runs tests related to files changed since the last commit.

Read more about testing.

yarn build (or npm run build)

When you’re ready to package your extension for distribution, create minified code with yarn build.

Since the procedure for packaging extensions varries significantly between browsers and distribution channels, you will have to do this step manually or using additional tools.

yarn eject (or npm run eject)

If you’re a power user and you aren’t happy with the default configuration, you can “eject” from the tool and use it as a boilerplate generator.

Running yarn eject copies all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. Commands like yarn start and yarn build will still work, but they will point to the copied scripts so you can tweak them. At this point, you’re on your own.

Note: this is a one-way operation. Once you eject, you can’t go back!

User Guide

The User Guide includes information on different topics, such as:

A copy of the user guide will be created as README.md file in your project folder.

Alternatives

If you don’t agree with the choices made in this project, you might want to explore alternatives with different tradeoffs:

Happy hacking!