Think of Twitch Extensions as Apps for Twitch. Developers can create sandboxed web applications that run on Twitch that provide new and different ways for viewers and broadcasters to interact.
To build the simplest Extension, a developer creates a web application; a collection of assets that include HTML, CSS, and Javascript; and then hosts these assets from the Twitch CDN ext.twitch.tv. A more complicated, but more common, Extension, leverages an Extension Backend Service (EBS). An EBS is a web service written by a developer for managing the state of their Extension. These two blocks of developer written code are often referred to as the frontend and the backend.
Developer's are currently completely responsible for operating their backends.
The Twitch Developer Site is currently where the lifecycle of an Extension is managed. This includes creation, frontend asset upload, submitting to review, and promoting to be released. The Dev Site is where key pieces of data are retrieved to configure and run the Developer Rig.
The Developer Rig hosts Extension frontends locally. This gives developers complete flexibility to run and test their Extensions without needing to load Twitch. For example, the Developer Rig does not currently stream video, reducing friction for testing a Video Overlay Extension. Additionally, multiple views of a single Extension can be loaded onto a single page, giving developers a single pane of glass for the different relevant views for their Extension.
The Developer Rig is a tool that enables Twitch Extensions developers to iterate more quickly and focus on building great Extensions, by providing a single pane of glass for all end user Extensions views and interactions. It is a lightweight web app that runs in a browser and is built using NodeJS 6+ and React. The Developer Rig allows Extensions Developers to quickly and easily, locally end-to-end test in development Extensions.
The Developer Rig renders Extensions in a combination of user contexts, views and different anchor types.
Supported user contexts include:
- broadcaster
- logged in viewers (linked and unlinked)
- logged out viewers (i.e. anonymous users)
Supported views include:
- channel page
- live dashboard
- broadcaster configuration
Supported anchor types include:
- panels
- video overlays
- mobile and video components (coming soon)
Extension output logs can be redirected to the Rig Console, a Developer Rig specific local console.
This project requires yarn and NodeJS. Both must be installed to use the Developer Rig.
Additionally, to pull in the sample Hello World project, it requires that Git is in your local PATH.
To install Node.js, follow the instructions here. By default, this installs the NPM package manager (npm), however, in all of our documentation we reference the use of Yarn which you can install by following the instructions here.
Once you have Yarn installed, simply run the command yarn install from the root of the cloned repository to fetch all the dependencies need to run the Developer Rig.
yarn installFor each Extension to be tested in the Developer Rig, a corresponding Extension needs to be created on the Twitch Dev Site. More detailed instructions to do this can be found here. Most fields are not relevant for the Developer Rig. The Type of Extension is loaded into the Developer Rig, and is hence important. Similarly, the Author Email must be correctly set and verified, before an Extension secret can be created.
There are several highly pertinent pieces of data that need to be taken from the dev site, and surfaced in the Developer Rig for it to operate. These include:
- The Client ID of the Extension
- The version of the Extension to be loaded in the Developer Rig
- A generated Extension Secret, to be used to sign Extension JWTs
These are hard requirements that enable the Developer Rig to function correctly!
Where possible, the Developer Rig is self-contained.
To allow non-Twitch hosted assets to not be blocked by the Extension's Content Security Policy (CSP), the Developer Rig requires a local host file entry.
The following line must be added to your local hosts file:
127.0.0.1 localhost.rig.twitch.tvOn Unix based systems run the command:
echo '127.0.0.1 localhost.rig.twitch.tv' | sudo tee -a /etc/hostsOn Windows machines:
1. Press the Windows key.
2. Type Notepad in the search field.
3. In the search results, right-click Notepad and select Run as administrator.
4. From Notepad, open the following file: c:\Windows\System32\Drivers\etc\hosts.
5. Add the line: 127.0.0.1 localhost.rig.twitch.tv
6. Click File > Save to save your changes.
This is a one time setup and is required to run the Developer Rig.
If you are new to building Twitch Extensions, read this first.
There are several pieces of configuration that the Developer Rig requires to function correctly:
-
Client ID: the unique identifier for your Extension. Go to the Extensions Dashboard, select the Extension you want to run in the Developer Rig, then look for
Client IDunderAbout This Extension.
-
Extension Secret: a valid secret, that allows your Extension to authenticate. Go to the Extensions Dashboard, select the Extension you want to run in the Developer Rig, select the
settingstab, and then navigate toSecret Keysand create/retrieve a valid secret.
This is not the Client Secret field located on the General tab under settings. Please ensure to go to Secret Keys.
-
Version: the exact version of an Extension to be loaded in the Developer Rig. Go to the Extensions Dashboard, find the Extension you want to run in the Developer Rig, and take note of the version number displayed under
status.
-
Channel: the name of the channel to be used for Twitch PubSub messaging. A channel is a string of less than 32 alphanumeric characters. We recommend prefixing your channel with
rig. If you later want to change the name of your channel you must delete or edit your browser's local storage as well as changing your EXT_CHANNEL argument. -
Owner name: the Twitch user name of the owner of the Extension (the Twitch user who created the Extension).
Values for these fields need to be injected as environment variables to the Developer Rig at startup. The environment variables names are:
EXT_CLIENT_IDEXT_SECRETEXT_VERSIONEXT_CHANNELEXT_OWNER_NAME
If you don't want to set these values via environment variables, all but the extension secret can be set through a configuration file. This file is specified via a command line argument and is in the format of
{
"clientID": "<client id>",
"version": "<version>",
"channel": "<channel>",
"ownerName": "<owner>"
}Ensure that the Developer Rig dependencies are installed and required configuration is available.
To start the rig with environment variables, run:
EXT_CLIENT_ID=<client id> EXT_SECRET=<secret> EXT_VERSION=<version> EXT_CHANNEL=<channel> EXT_OWNER_NAME=<owner> yarn startTo start the rig with a config file and command line arguments, run:
yarn start -s <secret> -c location/of/your/configThe location of your config file can be either relative to the directory you are running the command or an absolute path to the file.
This will cause your browser to open to https://localhost.rig.twitch.tv:3000.
Note: Depending on your browser and operating system, you may see a warning that the TLS certificate is illegitimate as it is self-signed. You can choose to proceed through this warning (or just use Chrome). TLS certificate generation occurs the first time the Developer Rig is started or it is used to host a sample extension. Generated certificates are stored in the ssl directory. If you are on OSX, we'll generate and install the certs in the keychain. If you are on Windows or Linux, you'll have to configure that yourself.
The Developer Rig UI presents a variety of views, anchors, and contexts.
This is likely the most used area for the Developer Rig. Views, anchors, and contexts can be configured to support comprehensive testing of an Extension.
Click the plus button to add a new view for the configured Extension Client ID, and remove them by clicking on the x on a view.
This section displays the Broadcaster Config view that is presented to broadcasters after they have installed an Extension, but before they are able to activate it.
This section displays the Live Config view that appears on a broadcaster's dashboard for an Extension.
The section displays manifest data pulled from Twitch for the corresponding Extension Client ID.
At the bottom of every page, there is the Developer Rig Console. Extensions are able to output directly to this console by making the following call from their Extension's frontend javascript:
window.Twitch.ext.rig.log(<message to log>)
Each view is prefixed with the corresponding “user context”, i.e logged in viewer, broadcaster etc. An active video stream is not required to leverage video overlays in the Developer Rig. When an Extension is running in the Developer Rig, developers can interact with it just like an end user.
By default, the Developer Rig links to sample Extension code available on GitHub. To pull and link this code into the Developer Rig, run:
# Usage: yarn extension-init -a [github_account] -r [github_repo] -l [local_dir]
yarn extension-init -l <local_dir>To have the Developer Rig host the frontend assets of an Extension, use the host command. Assets for the sample Extension can be hosted on https://localhost.rig.twitch.tv:8080 by issuing the following command:
# Usage: yarn host -l [local_dir] -p [port]
yarn host -l <local_dir>/public/ -p 8080Ensure that the URL that the sample Extension's Extension Backend Service (EBS) is running on and the Extension secret, match what is specified in the dev site!
In the above screenshot, assets are specified as being available at:
https://localhost:8080/viewer.html
https://localhost:8080/config.html
If the Developer Rig is used to host an Extension's front end assets, the Testing Base URI must be set to:
https://localhost.rig.twitch.tv:[port]
When an Extension has been loaded into the Developer Rig, refreshing your browser window will cause the latest Extension assets to be pulled into the page.
Conceptualising how an Extension works can be tricky, particularly in the context of the Developer Rig. Three main pieces are needed:
- the Developer Rig service (i.e.
yarn start) - a service hosting the Extension front end and associated assets (i.e.
yarn host) - an Extension Backend Service (EBS)
The Developer Rig loads the front end assets into its pages. The front end pages are able to call the EBS (signing requests with the Extension's JWT). An EBS can either respond directly to a front end client, or is able to push messages to all connected front ends via PubSub.
If you are experience difficulties getting things to work:
- ensure that everything is running on HTTPS and accessible in your browser
- ensure that the secret that is loaded into the Developer Rig matches the secret present in your EBS
- if you are struggling to get PubSub to work, assert that your EBS receives and extracts the channel name from the JWT sent by the Extension front end
Can I use the Developer Rig without first completing Extensions Developer On-boarding?
No. Valid client IDs and Extension secrets are required to leverage the Developer Rig. Currently, these can only be generated on the Twitch Dev Site, once on-boarding is complete. This will change with future Developer Rig enhancements.
Are the Extensions Function Components supported?
Extensions function components will be added shortly to the Developer Rig.
Will the Developer Rig support Mobile Extension views and Video Components?
Yes. The Developer Rig will shortly support all new Twitch Extensions functionality as it becomes available. Right now, the Developer Rig is playing catchup.
XXX in the Developer Rig sucks! The Developer Rig is missing feature YYY!
Neither of these are questions :) . Raise a PR with proposed changes, and let's help each other!
What are these Twitch Extensions of which you speak, and how can I learn more?
More information about Twitch Extensions is available on the Twitch Developer Site, and in the Twitch Developer Forums.
The linked Hello World repository uses EXT_OWNER_ID whilst the Developer Rig uses EXT_OWNER_NAME. What's up with that?
The Developer Rig uses an API call to the Twitch /users endpoint to retrieve an owner's user id. This has not been done yet in the Hello World repository. It should be added shortly.
What browsers are supported?
We know that the Developer Rig works in Chrome. Feel free to help ensure it works in other browsers!
The Extension I have specified is not appearing the Developer Rig.
There are a number of things that can create problems. The most common causes are: invalid NPM or NodeJS installations; a missing host file entry for the Developer Rig; misconfigured Environment variables being passed to the Developer Rig; or Extension configuration that does not match the contents of the Twitch Developer Site.
I am certain that my Developer Rig Configuration is correct, but my Extension is still not working.
Clear your browser cache and local storage, restart the Developer Rig, and cross your fingers. To delete the rig's local storage open the javascript console in your browser on a tab with the rig open and do
localStorage.clear();then refresh. Ensure you've included the Twitch Extension Helper is included in your front end files.
I see an error when attempting to run 'yarn test'.
Sometimes deleting and reinstalling your
node_modulescan correct this issue. On MacOS, you may need to explicitly install watchman viabrew install watchman.
yarn install fails in libssh2
See issue #48. Be sure libssh, and it's dependencies are installed.
_I get an error when pulling in the sample project!
Ensure that Git is in your PATH variables by attempting to run "git" at your commmandline. If that works, also ensure that the local folder does not currently exist.