Extension Coordinator

Extension Coordinator handles the construction of extensions and all communication they make with our first party clients. Any client wishing to create extensions should vendor this library into their application.

Setup

1. Install Yarn.
2. Clone the repository.
3. Navigate to the cloned directory and run yarn install.

Building

• yarn build - Builds the lib folder (typescript) and the umd.
• yarn build:lib - Only builds the lib folder (compiled typescript)
• yarn build:umd - Only builds the umd file.

Developing

• yarn start - Starts the typescript compiler in watch mode.
• yarn lint - Runs lint against the src/ directory.

Since we use the typescript compiler directly to generate our builds, lint errors do not appear when using yarn start. You should consider installing a tslint extension for your editor of choice otherwise lint errors won't appear until you've pushed your code or run yarn build which executes webpack to generate the umd file.

Developing from a Client (Twilight, Player, Mobile Bridge, etc.)

You'll likely find it most useful to have extension-coordinator linked to the application you're developing it.

It is recommended you use npm as yarn link is buggy and results in failed builds from within the application:

Steps:

cd /path/to/extension-coordinator
npm link
cd /path/to/application
npm link extension-coordinator

Changes to extension-coordinator should continue to cause rebuilds of whichever client application you're working on when using yarn start.

You can read more about this process here if you're interested. But the gist of it is that the first step creates a global link of extension-coordinator in npm's global directory, and the second step makes the application point to that folder.

Releasing New Versions

Versions of extension-coordinator are maintained in Twitch's internal NPM Registry so that they can be included in twilight and mobile-extension-native-layer.

Ensure you are logged into the internal npm registry. See instructions.

1. Make sure you are on the JTV VPN
2. Merge your feature branch into master.
3. Checkout out master.
4. Run yarn release:patch|minor|major for the respective semver bump.

The yarn release command will run yarn lint, yarn test, and yarn build before publishing to the npm repository. If these succeed, the generated tag will also be pushed.

Releasing to the Hosted Endpoint

Our mobile clients and the extension dev rig fetch coordinator from a CDN endpoint.

Coordinator is deployed to this endpoint manually through this Jenkins Job. For rig, the endpoint is https://extension-files.twitch.tv/coordinator/<version>/extension-coordinator.umd.js. For mobile, this endpoint is accessed via devassets-proxy with some logic that maps a version of the mobile app to the version of coordinator that it needs. This is to make sure that changes that break the public API of coordinator aren't picked up by older versions of the mobile app. This endpoint is of the form of:

https://coordinator.ext-twitch.tv/<android|ios>/<mobile-build-number>/extension-coordinator.umd.js

To release a new version of coordinator to the endpoint, first ensure that it is tested in staging (staging builds are created on any change to master and are hosted at):

https://s3-us-west-2.amazonaws.com/twitch-ds-exthelper-us-west-2-510557735000/coordinator/<VERSION>/extension-coordinator.umd.js)

Then, run the Jenkins job with the name of the tag corresponding to the version that you want to release. By default, these releases will not be pushed to the mobile endpoint without checking the DEPLOY_MOBILE box. We'd like to keep mobile releases limited to changes that directly affect them to minimize QA effort. If you do plan on checking that box, make sure the mobile team is aware of it.

You can find out what version of coordinator is currently used by mobile by substituting /extension-coordinator.umd.js with /metadata.json in the path.

Example: https://coordinator.ext-twitch.tv/android/5.10/metadata.json

Major version Updates

When making major version changes to the coordinator it is crucial that previous versions of the mobile application load the version of coordinator that has their expected interface. This will require adding checks to the following configuration on the devassets-proxy.

You should pin the current loaded version (taken from above) to their respective builds. Follow the examples already implemented in that file.

Release Troubleshooting

My Publish Step Is Hanging/Timing Out

Make sure you are on the JTV VPN, and that you have signed in to artifactory. If you ran any of the yarn release commands, your version tag will have been created and pushed to git, so don't re-run the command or you will create a superfluous version. Instead, fix your VPN and run npm publish --registry https://npm.pkgs.xarth.tv to push up the version. You can use the "quick search" bar at the Artifactory Homepage to see if you can find the version you published.

Creating Test Releases

When you are attempting to run tests against extension-coordinator in one of the client applications but are not quite ready to release the next version of extension-coordinator you'll want to create a test release (release candidate/prerelease). This is the preferred course of action rather than cutting a release every time you want to run a build so we don't have multiple releases during development.

To release a release candidate, follow these steps:

1. Make sure you've committed/pushed the latest code to your branch.
2. Run yarn release:manual and enter the name over the version you'd like to release.

Note that doing this makes will make a tag in git and also pushes to the NPM registry. It's not a big deal that either of these things happen but please do not ever merge a pre-release version to master in any of the client applications. This should only be for testing on local branches and dev environments. Never for production.

When you are done with your testing, delete the tags from github:

git push origin :<tag_name>

And unpublish the version:

npm unpublish extension-coordinator@your-version