{"id":39817596,"url":"https://github.com/alecm33/werewolf","last_synced_at":"2026-04-22T05:05:10.603Z","repository":{"id":36992078,"uuid":"205286715","full_name":"AlecM33/Werewolf","owner":"AlecM33","description":"A lightweight and flexible web application for hosting a game of Werewolf (Mafia). Helping people play Werewolf every day. Find it at: https://play-werewolf.app/","archived":false,"fork":false,"pushed_at":"2026-01-01T13:38:12.000Z","size":17058,"stargazers_count":37,"open_issues_count":5,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-01-18T18:18:36.068Z","etag":null,"topics":["express","html-css-javascript","javascript","mafia","nodejs","redis","social-deduction","social-deduction-game","socket-io","websocket","werewolf"],"latest_commit_sha":null,"homepage":"https://play-werewolf.app/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlecM33.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-08-30T02:10:37.000Z","updated_at":"2025-12-29T20:55:34.000Z","dependencies_parsed_at":"2025-12-29T08:08:01.985Z","dependency_job_id":null,"html_url":"https://github.com/AlecM33/Werewolf","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/AlecM33/Werewolf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlecM33%2FWerewolf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlecM33%2FWerewolf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlecM33%2FWerewolf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlecM33%2FWerewolf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlecM33","download_url":"https://codeload.github.com/AlecM33/Werewolf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlecM33%2FWerewolf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28747308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T05:12:38.112Z","status":"ssl_error","status_checked_at":"2026-01-25T05:04:50.338Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["express","html-css-javascript","javascript","mafia","nodejs","redis","social-deduction","social-deduction-game","socket-io","websocket","werewolf"],"created_at":"2026-01-18T12:52:40.944Z","updated_at":"2026-04-22T05:05:10.597Z","avatar_url":"https://github.com/AlecM33.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"200\" src=\"/client/src/images/new-logo.png\"/\u003e\n\u003c/p\u003e\n\n[![Node.js CI](https://github.com/AlecM33/Werewolf/actions/workflows/node.js.yml/badge.svg)](https://github.com/AlecM33/Werewolf/actions/workflows/node.js.yml)\n[![CodeQL Advanced](https://github.com/AlecM33/Werewolf/actions/workflows/codeql.yml/badge.svg)](https://github.com/AlecM33/Werewolf/actions/workflows/codeql.yml)\n\nFind the latest production deployment at: https://play-werewolf.app/\n\n- [Overview](#overview)\n- [Features](#features)\n- [Tech Stack](#tech-stack)\n- [Contributing and Developers' Guide](#contributing-and-developers-guide)\n- [Testing](#testing)\n- [Code Formatting](#code-formatting)\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./client/src/images/readme-collage.webp\" width=\"750\"/\u003e\n\u003c/p\u003e\n\n## Overview\n\nAn app to create and run games of \u003ca href=\"https://en.wikipedia.org/wiki/Mafia_(party_game)\"\u003eWerewolf (Mafia)\u003c/a\u003e with your friends. No sign-up, installation, or payment required. A moderator creates a room and deals a role to everyone's device, and then the app keeps track of the game state (timer, who is killed/revealed, etc). \nSince people tend to have their own preferences when it comes to what roles they use or how they run the game, the app tries to take a generalized, flexible, hands-off approach - it won't run day and night for you and won't implement any role abilities. Moderators can choose whether to be dealt in, and they can use any congifuration of roles they want, creating their own roles if needed.\n\nThe app prioritizes responsiveness. A key scenario would be when a group is hanging out with only their phones.\n\nInspired by my time playing \u003ca href=\"https://boardgamegeek.com/boardgame/152242/ultimate-werewolf-deluxe-edition\"\u003eUltimate Werewolf\u003c/a\u003e and by\n2020's quarantine. After a long hiatus I've rewritten a lot of the code. This was (and still is) fundamentally a learning project, so feedback or assistance is appreciated.\n\n## Features\n\n- hosts can build their own game for any player count using default roles or custom roles that they create. They can include a timer, shared by everyone, that the moderator can play or pause.\n- party members can join games easily via a shareable link, a QR code, or a 4-character code entered on the homepage.\n- Players and spectators can freely leave the lobby, or the moderator can kick them. Roles can also be edited in the lobby. This should allow a room to be re-usable for several games, even if the player count changes\n  and the moderator needs to change the cards in the game.\n- When a moderator starts a game, cards are dealt randomly and automatically.\n- players can reference helpful info, such as descriptions of all the roles in the game, the time remaining (if the host has set a timer), and who has been killed or had their role revealed.\n- Moderators have the option to be dealt into the game, and will have their moderator powers automatically delegated to whoever they first remove from the game. Moderators can also transfer their powers to players that have been killed or to people that are spectating.\n- The app is lightweight and loads fast. \n\n## Tech Stack\n\nThis is a Node.js application. It is written purely using JavaScript/HTML/CSS, with no front-end framework. The main dependencies are\n\u003ca href=\"https://expressjs.com/\"\u003eExpress.js\u003c/a\u003e, \u003ca href=\"https://socket.io/\"\u003eSocket.io\u003c/a\u003e, and \u003ca href=\"https://www.npmjs.com/package//redis\"\u003eNode-Redis\u003c/a\u003e. It runs as a containerized application\nvia \u003ca href='https://cloud.google.com/run'\u003eGoogle Cloud Run\u003c/a\u003e. \n\nInstances of this app are part of a stateless architecture that scales up and down as needed. Instances communicate with a separate \u003ca href=\"https://redis.io/\"\u003eRedis\u003c/a\u003e datastore, sending/receiving client events using the \u003ca href=\"https://redis.io/docs/manual/pubsub/\"\u003epub/sub model\u003c/a\u003e. So, it does not matter which instance a given client connects to. Games are purged from Redis after a period of inactivity.\n\n## Contributing and Developers' Guide\n\n### Running Locally\n\n#### Using Docker\n\nIf you have Docker Desktop installed, running `docker compose up` will spin up, by default, two\nweb servers and one redis server for them to connect to. The app can then be accessed at `localhost:5000`\nor `localhost:5001`. Otherwise, read below for setup that does not use Docker.\n\n![image](https://github.com/AlecM33/Werewolf/assets/24642328/36161f89-20a4-4236-ad24-e395985d48c3)\n\n#### Without Docker\n\nThe entrypoint for the application is `index.js` at the root. \n\nBefore starting the Node.js server, you'll need a Redis server running locally on the default port. This is what's used \nto store active games and keep any number of Node.js servers in sync. I followed\n\u003ca href=\"https://www.sitepoint.com/using-redis-node-js/\"\u003ethis tutorial\u003c/a\u003e, specifically using the installation method that uses\nWindows Subsystem for Linux (WSL), since I am on a windows machine. In a powershell, I simply run `wsl` and then `redis-server`, at which point you should see something like the following startup logs.\n\n![image](https://github.com/AlecM33/Werewolf/assets/24642328/206dd89c-6a48-4c49-9bb5-aeac829bc26d)\n\nI tested out the Redis server by using the Redis CLI\n(see their \u003ca href=\"https://redis.io/docs/getting-started/\"\u003egetting started page\u003c/a\u003e).\n\nOnce that's done, if you haven't already, install \u003ca href=\"https://nodejs.org/en/\"\u003eNode.js.\u003c/a\u003e This should include the node package \nmanager, \u003ca href=\"https://www.npmjs.com/\"\u003enpm\u003c/a\u003e.\n\nRun `npm install` from the root directory to install the necessary dependencies.\n\nThese instructions assume you are somewhat familiar with Node.js and npm. At this point, we will use some of the run\ncommands defined in `package.json`.\n\nIf you simply want to run the app on the default port of **5000**:\n\n`npm run start:dev` (if developing on a linux machine)\u003cbr\u003e\n`npm run start:dev:windows` (if developing on a windows machine)\n\nIf everything is okay, you should see logs indicating a connection to Redis and a starting of the web server. \n\nThis command uses \u003ca href=\"https://www.npmjs.com/package/nodemon\"\u003enodemon\u003c/a\u003e\nto listen for changes to **server-side code** (Node.js modules) and automatically restart the server. If you do not want \nthis, run instead `npm run start:dev:no-hot-reload` or `npm run start:dev:windows:no-hot-reload`. \n\nIf you are making changes to client-side javascript, in a separate terminal, execute `npm run build:dev`. This uses \u003ca href=\"https://webpack.js.org/\"\u003e\nWebpack\u003c/a\u003e to bundle javascript from the `client/src` directory and place it in the `client/dist` directory, which is ignored by Git.\nThis command uses the `--watch` flag, which means the process will continue\nto run in this terminal, watching for changes within the `client/src` directory and re-bundling automatically. You \ndefinitely want this if making frequent JavaScript changes to client-side source code. Any other changes, such as to HTML or CSS\nfiles, are not bundled, and thus your changes will be picked up simply by refreshing the browser.\n\n**Note:** in the development environment, cookies are stored using sessionStorage (vs. localStorage in production). This makes it a lot easier to create/run test games, as you can join as different people in different tabs.\n\n### CLI Options\n\nThese options will be at the end of your run command following two dashes: `npm run start:dev -- [options]`.\nOptions are whitespace-delimited key-value pairs with the syntax `[key]=[value]` e.g. `port=4242`. Options include:\n\n- `port`. Specify an integer port for the application.\n- `loglevel` the log level for the application. Can be `info`, `error`, `warn`, `debug`, or `trace`. \n- `protocol` either `http` or `https`. If you specify HTTPS, the server will look in `client/certs` for localhost certificates\nbefore serving the application over HTTPS - otherwise it will revert to HTTP. Using HTTPS is particularly useful if you\n  want to make the application public on your home network, which would allow you to test it on your mobile device. **Careful -\n  I had to disable my computer's firewall for this to work, which would of course make browsing the internet much riskier.**\n\nexample run command:\n\n`npm run start:dev:windows -- port=4242 loglevel=trace protocol=https`\n  \n### Admin API\n\nThe app exposes an admin API at `/api/admin`, e.g. `localhost:5000/api/admin`.\n\nThe admin api doesn't require any authentication in the development environment (but does in prod).\n\nCurrently, the available operations are:\n\n- **GET /games/state** - returns a JSON array of the currently existing games.\n\n- **POST /sockets/broadcast** - broadcasts a message to all connected sockets. This is not currently handled on the front-end, so it will not display anywhere.\n\n##### Example cURL\n```\ncurl --location --request GET \"http://localhost:5000/api/admin/games/state\"\n```\n\nHave a question that isn't covered here? Email me at \u003ca href=\"mailto:play.werewolf.contact@gmail.com?Subject=Werewolf App\" target=\"_top\"\u003eplay.werewolf.contact@gmail.com\u003c/a\u003e\n\n## Testing\n\nTests are written using \u003ca href=\"https://jasmine.github.io/\"\u003eJasmine\u003c/a\u003e. End-to-end tests are run using \u003ca href='https://karma-runner.github.io/latest/index.html'\u003eKarma\u003c/a\u003e.\n\nExecute all tests by running `npm run test`. Execute unit tests by running `npm run test:unit`. Execute end-to-end tests by running `npm run test:e2e`.\n\nUnit tests map 1:1 to the application directory structure - i.e. unit tests for \n`server/modules/GameManager` are found in `spec/unit/server/modules/GameManager_Spec.js`\n\n## Code Formatting\n\nThis application uses \u003ca href=\"https://eslint.org/\"\u003eESLint\u003c/a\u003e to enforce code formatting standards. This configuration is found at the root in `.eslintrc.json`. \nTo audit the codebase, run `npx eslint [directory]`, and to fix them along with that, run `npx eslint [directory] --fix`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecm33%2Fwerewolf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falecm33%2Fwerewolf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecm33%2Fwerewolf/lists"}