This tutorial was written to go with the official Phaser Twitch Extensions Template repository. It is meant to be used as a starting point for creating Overlay Twitch Extensions with Phaser, utilizing the Twitch Extension JavaScript Helper and basic Twitch API calls. It helps you to get started building Twitch Extensions, creating fun interactions on stream and building games on Twitch.

At the end of this Tutorial, you will know everything you need to know to build a client-side Overlay Twitch Extension as a classic follower alert on stream, with Phaser. This tutorial aims to be beginner friendly for both Phaser and Twitch devs alike to be build something awesome.

What are Twitch Extensions?

Twitch extensions are webpages that live inside Twitch channels and utilize functionalities by Twitch can be used to create interactive Overlays. There are different types of Twitch Extensions, which you will learn more about in this Tutorial at a later point.

A twitch extension example is the Firestarter Twitch Extension built with Phaser, it allows viewers and twitch communities to blast fireworks live on stream with the best of both Twitch and Phaser worlds.

In this Tutorial you will build an "Overlay Extension" that sits on top of the twitch channels video stream.

Let's get started!

Requirements

Already have a Twitch Account? You can skip this section and get right into creating your first Twitch Extension!

You must have a Twitch account in good standing at twitch.tv. This account is the same that you will need to create, manage and publish Twitch Extensions.

Additionally, you must have 2FA (two-facter authentication) enabled for your Twitch Account. Once you are registered, update your security settings in the Security and Privacy settings tab in the Settings menu on Twitch to install and activate 2FA. To do so, you must also verify your E-Mail.

Now it is time to login in with your newly registered twitch account to https://dev.twitch.tv/. This is where you will manage your extensions.

Create a new Twitch Extension

All Twitch Extensions can be created, managed and monitored in the Developer Console. It is your control center for important changes to your Twitch Extension settings such as the Twitch Extension's visible name, manage testuser access, upload your builds and do other things.

Press the "Create Extension" button to start build your first Twitch Extension.

A dialogue will open. Think of a name for your Phaser twitch extension and type it in. Click continue when you are happy with your chosen name.

The name of your Extension is unique across all existing Twitch Extensions. You are going to see an error if you enter an existing name. Not to worry, try another one. This name is not user-facing, you may change your Twitch Extension name at a later point.

You are now one step away from coding! There are different types of Twitch Extensions, all of them serve different purpose and show up in different places on the Twitch Channel.

• Panel Extensions live right beneath a twitch channel's livestreaming window. It is always shown, even if the livestream is offline.
• Video - Fullscreen, also known as Overlay Extensions sits right above the livestream. In the tutorial you are going to build this one.
• Video - Component is a small, clearly distinguishable window on the rightern side above the streaming window.
• Mobile are Twitch Extensions that are enabled for the native Twitch App, they are dedicated for mobile use. Other extensions do not run inside the native Twitch App.

Select "Video - Fullscreen" and scroll down to confirm your configuration. You can add any other information about your Phaser twitch extension at a later point.

Installation

To get started, clone the Phaser Twitch Extension Project Template:

git clone https://github.com/phaserjs/template-twitch-extension.git

Client Installation

Ensure that you have a project compatible NodeJS version. The required NodeJS is specified inside the .nvmrc file in the root directory and the package.json file.

node -v
npm install

Development

Go to the Twitch Developer Console and select your Extension. For this basic template it is sufficient to leave the Extension in status Local Test.

It is not necessary setup a public proxy that allows accessing your localhost. Twitch provides us with a Testing Base URI. This is convenient as you do not need to upload new builds to the Twitch CDN where Twitch Extensions are hosted everytime you change the code.

Ensure that the Testing Base URI looks like this, to match the local Vite devserver configuration, which is http://localhost:8080/. Of course, you can add SSL support if you like and change the Testing Base URI accordingly.

You can now start your local development server which will serve the assets from your local machine on the live channel and not from the Twitch CDN. Only you will be able to see and use the Phaser twitch extension at this point.

npm run dev

Now you can go live on your Twitch Channel that has the Extension installed and activated. On the right side you can enable the Test Extension for use. The Extension will reload automatically on changes within your template repository.

Navigate to your live channel and see the Extension in action.

Upload

Now that the Twitch Extension runs locally and inside the Twitch embedded iframe, you probably want to share your work with friends and testers.

To do so, create a build and zip the content of the distribution folder dist. The .zip file is intended to be uploaded to the Twitch CDN via the Twitch Developer Console. The production Vite config config.prod.mjs utilizes the vite-plugin-zip-pack to allow you a seamless compression of your latest build into a .zip folder.

npm run build

The generated zip file is named dist.zip and sits in the project directory of this project. To modify the output name (for example for versioning) edit the config.prod.mjs to your liking.

...
zipPack({
    outFileName: "dist.zip",
    outDir: "."
})

Now that you have your Phaser Twitch Extension build zipped, open your Twitch Extension in the Developer Console. Navigate to "Files" and upload the zip file.

Test with Friends

There are three steps left to show off with your newest project. You can add testers by entering their Twitch User in the "Access" tab. The streamer allowlist is not required to test your Twitch Extension, this is relevant if you plan to develop your Twitch Extension for multiple specific streamers, only allow-listed streamers can use your Twitch Extension on their channel.

When you are happy with your set of testers (no worries you can change them anytime before submitting your extension for release), it is time to move your Twitch Extension to "Hosted Test". This will allow you to install and activate the Twitch Extension on your Twitch Channel. Click on the "Status" tab and hit the "Move to Hosted Test". You should then see that your Twitch Extension has moved to the next status in the progress bar above.

The Extension is now available for everyone added to the testing accounts allowlist. In your last step you would find your creation in the Twitch Creator Dashbard in "Extensions" on the left side. Add your extension from the "Invite-Only" tab and activate it as an "Overlay" within the "My Extensions" tab. You are now ready to stream with your fancy new Twitch Extension made with Phaser. Your Overlay Extension will automatically load when you visit your livechannel, just like in the Testing Development step before. Have fun!

That's it! Create something awesome.

This completes the extensive template Tutorial to build a Twitch Extension with Phaser.

Whilst writing, the Twitch Extension Developer Team has resumed the Twitch Extensions review process. By now the SLA (Service-Level-Agreement) is still work in progress. Please visit the Twitch Developer Console or Twitch Dev Discord Server for more information about recent developments.

We would love to see more Phaser twitch extensions out there! Tell us about your Phaser twitch extension via games@phaser.io or show off on our Discord Server.

Twitch Extension Tips

• To ensure a fast and smooth review process,we recommend to read through Submission Best Practices carefully.
  💡 It has been proven that a well structured and detailled submission text is less likely to be rejected and can be released faster.
• It is mentioned that the livechannel must be live during the review time.
  💡However, this is not required for Twitch Extensions, like the template project, who do not require an EBS (an Extension Backend Service) that is run by you. Add a text to your submission notes that states that this is a client-side only Extension and you are good to go. This also applies to "Video - Fullscreen" extensions.
• Audio must be muted until a user turns it on manually. The AudioContext does not automatically start when the Twitch Extension loads until first user gesture. It will not pass the Twitch Review if the audio is not muted initially.
  💡 However, you may store the volume in the localstorage and load it from there on next visit.
• You will read about the Developer Rig. This has been marked as deprecated.
  💡 We recommend an alternative as a testing tool, the Twitch Extension Tools that primarily handles JWTs and App Access Token for Advanced Twitch Extensions
• Commonly, Twitch Extensions should be seen as a tool, rather than a standalone browser game or standalone playful experience. It should level up and enrich the viewer experience to what the streamer's content they are streaming.