Franklin Sidekick Extension

Browser extension for authoring Franklin projects

Status

Installation

Note: The Sidekick extension and bookmarklet share the same Sidekick module.

Installing the bookmarklet

Navigate to https://www.hlx.live/tools/sidekick/ and follow the instructions there.

Installing the Chrome extension

1. Go to the Chrome Web Store
2. Click Add to Chrome
3. Confirm by clicking Add extension
4. Click the extensions icon next to Chrome's address bar to see a list of all extensions:
   
5. Verify that there's an icon like this:
   
   
6. Click the pin button next to it to make sure it always stays visible.

Adding projects to the Chrome extension

1. Click the extension's icon and select Options:
   
   On this page, you can add projects by either pasting a share URL* or a GitHub URL in the respective fields and clicking Add. This page will also allow you to view, edit and delete existing projects.
   1. Alternatively, you can also navigate to a share URL* or a GitHub project, click the extension's icon and select Add project.
2. Navigate to your project's homepage and click on the extension's icon to toggle the Sidekick.

* Share URLs start with https://www.hlx.live/tools/sidekick/...

Usage

Refer to the Sidekick documentation to learn more about its features.

Development

Build

$ npm install
$ npm run build

Test

$ npm test

Lint

$ npm run lint

Branch testing a bookmarklet

Every development branch in this repository will be mirrored in https://github.com/adobe/helix-website with a sidekick- prefix to enable enable branch testing:

1. Push changes to a branch issue-77
2. Note the sidekick-issue-77 branch in https://github.com/adobe/helix-website/branches
3. Go to https://sidekick-issue-77--helix-website--adobe.hlx.page/tools/sidekick/ to install a development version of the bookmarklet for your project

Note: Mirrored development branches in https://github.com/adobe/helix-website/branches must be deleted manually when no longer needed.

Local testing

Testing a local bookmarklet

1. Run npm start on your local checkout of this repository
2. Go to `http://localhost:3001/ and follow the instructions.

Testing a local Chrome extension

1. Run npm run build:chrome
2. Open Chrome and navigate to chrome://extensions
3. Turn on Developer mode at the top right of the header bar
   
4. Click the Load unpacked button in the action bar
   
5. Navigate to the dist > chrome folder and click Select to install and activate the Sidekick extension.
6. Verify that your Extensions page displays a box like this:
   
   
7. Follow the steps under Adding projects to the extension

Testing a local project config

If you want to test a config file before deploying it to your project:

1. Run hlx up on your local checkout of the project repository
2. Add your project to the sidekick extension
3. Enable local project configruation:
   1. Click the extension's icon and select Options
   2. Click Advanced on the left
   3. Click Edit on the project configuration you want to test locally
   4. Tick the Test project configuration locally checkbox
   5. Click Save
4. Navigate to a project URL and activate the sidekick extension

Deployment

Deploying the bookmarklet

The Sidekick bookmarklet gets staged automatically each time a pull request is merged into main.

1. Go to helix-website pull requests
2. Click the Sidekick Release Candidate PR
3. Add a comment listing the helix-sidekick PR(s) included in this release
4. Get a team member to review the Sidekick RC. The PR is based on a sidekick-rc-* branch (* being a random ID) so the RC can be tested at: https://sidekick-rc-*--helix-website--adobe.hlx.page/tools/sidekick/
5. Once approved, merge the RC PR to deploy the changes into production

Deploying the Chrome extension

The Chrome extension is built and uploaded automatically each time a pull request is merged into main and, once reviewed by Google, auto-published and pushed to users' browsers.

CI setup

The following environment variables are required to be set in the CircleCI project settings: GOOGLE_APP_ID, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_REFRESH_TOKEN. See here for detailed instructions how to obtain and generate them.

If you have to re-deploy manually or make changes to the store page, you can gain access to the Chrome Developer Dashboard by following these instructions:

1. Go to the Chrome Developer Dashboard
2. Switch to the Adobe Inc. publisher at the top right
3. Click the Sidekick item in the extension list
4. Switch to Package
5. Click Upload new package
6. Upload dist > chrome.zip
7. Click Submit for review