Skip to content


Repository files navigation

🛠 Status: Maintenance Mode | Stable

This project is currently in maintenance mode - users should feel free to continue to use this app and expect bug fixes, but not expect many additional features.


Play fair.

Resonate is an open-source music streaming service run by a cooperative of artists and software developers.

If you want to know what we're building or want to get more involved, head over to the Platform category on our forum or read the Developer Guide in our Resonate Handbook.

If you're looking for a good first task, feel encouraged to take on an un-assigned 'help wanted' issues.

Are you building something using the Resonate API and would like to request a change? Resonate welcomes #proposals in the Co-Operation section of the forum.

Table of Contents

Getting Started


Quick-n-dirty instructions to get the player up and running on your computer using http and pointing to the existing production API (see API to learn more about the API). Assumes the latest version of node.js.

Stuck? Make an issue on Github! Curious about the roadmap? Ask in the forum.

Clone the repo and cd into it:
cd stream

Install dependencies:

npm install

Create your env file:

cp beta/.env.example beta/.env

Run the app:

npm run dev

You should see the app running at http://localhost:8080.

Try logging in at http://localhost:8080/login.

You can run the app at a different port using the command below:

npm run dev -- --port 8089

The embed app (optional)

npm run dev:embed

Testing on Mobile: Using HTTPS

HTTPS is required to test PWAs on mobile. Read more about Progressive Web Apps.


You can find a reference nginx configuration file in the docs. Note that the reference is not a complete nginx.conf file, it should fit within your existing configuration or be wrapped in a http block directive:

http {
  server {

In the example nginx.conf, note the lines referring to the ssl_certificate_key and the ssl_certificate_key.

Generating a Custom Certificate

You can generate a custom certificate using mkcert for beta.resonate.localhost. This origin is whitelisted in our CORS config.

Generate the certificate (cert.pem) and key (key.pem) for beta.resonate.localhost:

mkcert -key-file key.pem -cert-file cert.pem beta.resonate.localhost

In your nginx.conf file, update the ssl_certificate_key and the ssl_certificate_key to refer to your new key and certificate files.

Update your Hosts file

Update your hosts file to include:       beta.resonate.localhost

Update on your .env file


Run the app!

npm run dev

You should now see the player running on https://beta.resonate.localhost or



If you want to build on the API for personal use, consider checking the backlog in our community forum. The Tracks API repo is currently private, but you may ask for access in the forum.

The Swagger API documentation is currently in flux and split across the Resonate Search API (see the top right corner for the different services) and Resonate Service Documentation: User.

Other Commands

Add a package

Installing one of the monorepo packages into one of the other ones is as easy as this:

npm install @resonate/button --workspace "beta"

This installs @resonate/button into the beta package.

Add a dev dependency

Here's how you would add gulp so that it can be used in any package in this repo:

npm install -D gulp


npm run build

To compile a specific package

npm run build --workspace "@resonate/rangeslider"


Run all tests (lint, dependency-check)

npm test

Test a specific component

npm run test --workspace "@resonate/player-component"

A package can have browser tests (tape-run)

npm run test:browser --workspace "@resonate/api-factory-generator"


Command Description
$ npm run dev Start beta app development server
$ npm test Lint, validate deps & run dependency-check for all packages
$ npm run build Compile all beta app files into beta/dist/

Code style

We use eslint together with the standard config as a linter and javascript style guide. Make sure to add appropriate plugin for your editor, unless it is already supported out-of-box. It can also be handy to install the pre-commit hook (see .pre-commit-config.yaml) to automatically apply the standard style.


See Also

  • choo - sturdy 4kb frontend framework
  • nanohtml - HTML template strings for the Browser with support for Server Side Rendering in Node. strings
  • nanocomponent - create performant HTML components
  • tachyons - functional CSS for humans