hfellerhoff/listentogether

Listen to Spotify synchronously with your friends. Queue songs, control playback, and chat in real time.

Listen Together

An app for listening syncronously with friends on Spotify. Join a room, queue some songs, and chat with friends.

Technology

Listen Together is built with Next.js and Supabase (an open-source Google Firebase alternative).

Project Prerequisites

1. Make sure Node.js is installed. You can download it here.
2. Listen Together uses pnpm for package management. While we recommend using pnpm, this is only necessary if you'd like to contribute to the project. For installation instructions, see the pnpm installation page.

Building the Project

1. Clone this repository from GitHub.
2. Run npm install or yarn within the root project directory.
3. Rename .env.example to .env and populate it with the corresponding API keys from Supabase and Spotify.
   • Create a Supabase project: https://app.supabase.io/
     1. Create a new Supabase project.
     2. In the left sidebar navigation, go to Settings > API.
        1. Under API Keys, copy the anon public key and add it to your .env file. DO NOT use the secret key – this will give any user Read/Write access to your entire database.
     3. In the left sidebar navigation, go to SQL.
        1. Copy the SQL from the repository's DATABASE_INIT.sql file, paste it in the query editor, and run the query to create the required database tables. Note: This is WIP. Please add a GitHub issues if you run into issues with this command. 🚧
   • Create a Spotify app: https://developer.spotify.com/dashboard/login
     1. Log in, create an app, and continue to the app dashboard.
     2. Copy the displayed Client ID and add it to your .env file.
     3. Click Show Client Secret, copy the displayed Client Secret and add it to your .env file.
     4. Click Edit Settings and perform the following:
        1. Add localhost:3000/api/spotify/callback to the list of Redirect URIs.
        2. If you have a production URL, add it to the list of Redirect URIs in the format https://PRODUCTION_URL/api/spotify/callback
4. To run the project locally, run npm run dev or yarn dev.
5. To build the project, run npm run build or yarn build.
6. Once built, the production application can be served using npm run start or yarn start.

Testing

At the moment, testing is not a part of Listen Together. If you would like to help create tests for common database/backend interactions and other portions of the app, feel free to create a PR.

---

Project Structure

• .next: Auto-generated by Next.js. No editing needed.
• components: This is where all React components are stored. Currently organized by type or location, will likely be changed to be organized by either type or location.
• constants: This is where any widely-used strings and other variables are stored. Examples include cookie/localstorage keys, API endpoints, etc.
• hooks: This is where all custom React hooks are stored. These often have to do with communication with Spotify, state management, or interacting with Supabase.
• models: This is where all project-wide Typescript interfaces are stored. Examples include the types for a User, Room, etc.
• node_modules: Required for using NPM packages. Auto-generated, so no editing needed. Not a part of the GitHub repository.
• pages: Used by Next.js to create the various routes of the application. Any .js or .tsx file in this directory will be converted into a page in the website/application. For more information, see the Next.js documentation on the pages directory.
• public: Used by Next.js (and normal websites too) for resources needed in the site. The main use for this folder is to store any assets needed for the site, primarily images.
• state: Used for any global state management. The project currently uses Jotai, a super simple state management package. View the documentation here.
• styles: Used for global styles. Most styling happens at the component level thanks to Next.js, so use for this directory is limited.
• util: Used for helper functions, both generally and for specific application services. This will be used for any functions needed across a number of components, e.g. the logic for joining a room, saving/favoriting a room, etc.

Other individual files

• .gitignore: Any files that shouldn't be committed to git (auto-generated files, .env files, etc.).
• next-env.d.ts: Specific types for Next.js. Don't edit unless there is a good reason to.
• package.json: Information about the application, helpful scripts, dependency management.
• README.md: What you're reading right now! Documentation about the application.
• tsconfig.json: TypeScript settings. Rarely need changing, set up to work with Next.js.
• pnpm-lock.yml: Auto-generated by pnpm for managing dependencies. Don't edit.

Previous Versions

This is an updated version of the previous Listen Together, which was built in a weekend for the Same Home Different Hacks hackathon in 2020. If you're looking for that, you can find it here.

License

As of 2023, Listen Together is under the GNU Affero General Public License v3.0. See the LICENSE for more information.