{"id":27700892,"url":"https://github.com/ASteinheiser/ts-online-game-template","last_synced_at":"2025-12-30T20:01:15.183Z","repository":{"id":289579202,"uuid":"971242035","full_name":"ASteinheiser/ts-real-time-online-game-template","owner":"ASteinheiser","description":"A template for creating real time, online games using TypeScript! Quickly create mmo-style games using React + Phaser for rendering, Colyseus for websockets, Electron for native builds, and SST (IaC) for deployment!","archived":false,"fork":false,"pushed_at":"2025-04-24T03:49:41.000Z","size":230,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-25T19:08:08.265Z","etag":null,"topics":["colyseus","electron","eslint","fullstack","game-development","iac","monorepo","phaser3","phaserjs","prettier","pwa","reactjs","serverless-stack-toolkit","shadcn-ui","sst","tailwindcss","turborepo","typescript","vite","websockets"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ASteinheiser.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-04-23T08:17:38.000Z","updated_at":"2025-04-24T03:50:39.000Z","dependencies_parsed_at":"2025-04-24T02:23:43.822Z","dependency_job_id":"d708e4e9-43dd-463c-9edc-4373fa1dc2cb","html_url":"https://github.com/ASteinheiser/ts-real-time-online-game-template","commit_stats":null,"previous_names":["asteinheiser/ts-real-time-online-game-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ASteinheiser%2Fts-real-time-online-game-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ASteinheiser%2Fts-real-time-online-game-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ASteinheiser%2Fts-real-time-online-game-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ASteinheiser%2Fts-real-time-online-game-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ASteinheiser","download_url":"https://codeload.github.com/ASteinheiser/ts-real-time-online-game-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250878894,"owners_count":21501743,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["colyseus","electron","eslint","fullstack","game-development","iac","monorepo","phaser3","phaserjs","prettier","pwa","reactjs","serverless-stack-toolkit","shadcn-ui","sst","tailwindcss","turborepo","typescript","vite","websockets"],"created_at":"2025-04-25T19:08:14.398Z","updated_at":"2025-12-30T20:01:15.178Z","avatar_url":"https://github.com/ASteinheiser.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TypeScript Online Game Template\n\nA _highly opinionated_ template for creating real-time, online games using [TypeScript](https://www.typescriptlang.org/)! Quickly create mmo-style games using [React](https://react.dev/) + [Phaser](https://phaser.io/) for rendering, [Colyseus](https://colyseus.io/) for websockets, [Electron](https://www.electronjs.org/) for native builds, and [SST](https://sst.dev/) ([IaC](https://en.wikipedia.org/wiki/Infrastructure_as_code)) for deployment! Also has support for [Progressive Web Apps](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps) (PWA). Oh, and lots and lots of [Vite](https://vite.dev/) for builds and testing!\n\n#### Comes with 3 apps:\n\n- `desktop`: Frontend rendering for the game written in TypeScript using Electron, React, Phaser, Colyseus and GraphQL. When built, compiles an executable that runs a version of Chromium to render the game.\n- `game-api`: Backend server that handles the game state and data via WebSockets and GraphQL. Written in TypeScript with Colyseus, Express and [Apollo GraphQL](https://www.apollographql.com/docs).\n- `web`: Static webpage that can serve as a marketing site, devlog, roadmap, wiki etc. Written in Typescript with React and GraphQL. Could also be used to serve the Phaser/Colyseus game (with support for PWA).\n\n#### And 5 packages:\n\n- `core-game`: Main logic for the game. Shareable for use on the server as well as the client. Client-side prediction ([CSP](https://en.wikipedia.org/wiki/Client-side_prediction)) demo included.\n- `client-auth`: Shared auth forms, hooks, etc. built with the local `ui` package. Used by both the static webpage and Electron app.\n- `ui`: Shared Tailwindcss theme and Shadcn/ui components\n- `typescript-config`: Shared TypeScript configs\n- `eslint-config`: Shared ESlint configs\n\n## Third-party Dependencies\n\nThis project relies on [Supabase](https://supabase.com/) for [JWT authentication](https://auth0.com/docs/secure/tokens/json-web-tokens). They offer a very generous free tier ([50k MAU](https://supabase.com/pricing)) and a straight-forward developer experience. It's also [open source](https://github.com/supabase/supabase?tab=readme-ov-file#supabase), so you can self-host if the need arises!\n\nYou'll need to create a free tier [project](https://supabase.com/dashboard/) and add the relevant keys to your local environment. Keys can be found by navigating to your [Supabase project](https://supabase.com/dashboard/), then from the sidebar, \"Project Settings\" \u003e \"Data API\". Here you should see a few important sections: \"Project URL\", \"Project API Keys\" and \"JWT Settings\". **Use the values from these sections to create the following files based on the `.env.example` files:**\n- `apps/desktop/.env`\n- `apps/game-api/.env`\n- `apps/web/.env`\n\n**NOTE:** You'll need to update the `Site URL` (under `Authentication` \u003e `URL Configuration`) to send email links to the auth redirect route. For example, if your custom domain is `https://ts-game.online`, you should enter: `https://ts-game.online/auth/redirect`. You can use `http://localhost:4200/auth/redirect` for local development. Configure this value here:\n\n`https://supabase.com/dashboard/project/\u003cPROJECT_ID\u003e/auth/url-configuration`\n\nI recommend also updating the `Secure email change` setting to `false` (under `Authentication` \u003e `Providers` \u003e `Email`). By default, Supabase sets this to `true`, which will require users to click a link in both the old and new emails. While this is a good security measure, it can be annoying if users can't access their old email for some reason.\n\n### Env Considerations\n- [Turborepo recommends](https://turborepo.com/docs/crafting-your-repository/using-environment-variables#best-practices) that you define environment variables for each \"app\" instead of trying to define them globally. This helps prevent sensitive env values from leaking across apps.\n  - Although vite has built-in mechanisms for ensuring certain env doesn't get exposed on the frontend, I find it messy to have env from the web app loaded on the backend, for example.\n- To ensure caches miss when updating env values, you may need to update the `turbo.json` section for `tasks.build.env`. It should be noted that [turborepo will infer](https://turborepo.com/docs/crafting-your-repository/using-environment-variables#framework-inference) any `VITE_`-prefixed env.\n  - This means that if you add more `VITE_WHATEVER` variables to either `apps/desktop/.env` or `apps/web/.env`, then you do **NOT** need to update the `turbo.json`.\n  - However, if you add another variable to `apps/game-api/.env`, then you **SHOULD** update the `build` tasks' `env` in the `turbo.json`.\n  - *NOTE:* the `dev` task does not need the `env` field since it's `cache` setting is set to `false`.\n\n### Auth Email Templates\n\nYou can also quickly customize the auth emails using the templates under `packages/client-auth/email-templates` by navigating to:\n\n`https://supabase.com/dashboard/project/\u003cPROJECT_ID\u003e/auth/templates`\n\n## Developer Quickstart\n\nIf you are familiar with `pnpm` and `docker-compose`, you can skip to [Useful Commands](#useful-commands) or quickly start development with:\n```bash\npnpm i\npnpm db:start\npnpm db:sync\npnpm dev\n```\n\nWhen you run `dev`, you should see:\n- Web page at http://localhost:4200\n- Native desktop window with the game connected to ws://localhost:4204\n- Colyseus playground at http://localhost:4204\n- Colyseus monitor tool at http://localhost:4204/monitor\n- Apollo GraphQL playground at http://localhost:4204/graphql\n- PostgreSQL DB at postgresql://guest:guest@localhost:5432/game_db\n\n#### Otherwise, you should:\n\nInstall the `docker-compose` cli, which can be [installed via Docker Desktop](https://docs.docker.com/compose/install/). Make sure you have Docker Desktop running!\n\n\u003cb\u003eEnsure\u003c/b\u003e you are using the \u003cins\u003ecorrect version\u003c/ins\u003e of \u003cins\u003eNode.js\u003c/ins\u003e. You can validate this by comparing your local version of node (`node -v`) with the `.nvmrc`.\n\nNOTE: The `.nvmrc` uses an alias for the node version. I highly recommend managing your local node version with [`nvm`](https://github.com/nvm-sh/nvm). This will allow you to quickly swap to the correct version with:\n```\nnvm use\n```\n\nThis project uses [`pnpm`](https://pnpm.io/) for it's dependency mangement. You can install it with `npm`:\n```\nnpm i -g pnpm\n```\n\nThis project also uses [Turborepo](https://turborepo.com/) to manage scripts across the monorepo. While this is NOT necessary, [it is recommended](https://turborepo.com/docs/getting-started/installation#installing-turbo) that you install a local version:\n```\nnpm i -g turbo\n```\n\nWith the `turbo` cli, you can take a look at the project structure as well as the available commands:\n```\nturbo ls\nturbo run\n```\n\n## Most Used Commands\n\nThese commands are available from the root directory whether you decide to install the `turbo` cli locally or not...\n\n\u003cb\u003eNOTE\u003c/b\u003e: Commands should \u003cins\u003ealmost always\u003c/ins\u003e be ran from the root directory. The package manager, `pnpm`, uses `turbo` to manage and run scripts. Since code can be shared between repos, `turbo` helps ensure that scripts run in a certain order when necessary.\n\n| Command | Description |\n|---------|-------------|\n| `pnpm db:[start\\|stop\\|sync]` | Uses `docker-compose` and `prisma` to manage a local PostgreSQL DB |\n| `pnpm dev` | Run local development servers for each app |\n| `pnpm db:test:[start\\|stop\\|sync]` | Uses `docker-compose` and `prisma` to manage a test PostgreSQL DB |\n| `pnpm test` | Runs the typecheck, linter and tests for each repo |\n| `pnpm test:watch` | Runs the test suite in each repo and watches for changes |\n| `pnpm test:load` | Builds and runs the `game-api` then starts the load test |\n| `pnpm preview` | Builds each app and runs a local server using the output |\n| `pnpm build:[win\\|mac\\|linux]` | Builds the desktop app via Electron |\n\n\u003cb\u003eNOTE\u003c/b\u003e: If, for example, your Electron app is throwing an error when starting or building, but was previously working, try:\n```\npnpm install:clean\n```\n\n## Working with the PostgreSQL DB\n\nIf this is your first time running the project, you'll need to start the DB with `docker-compose` and sync the tables with `prisma`:\n```\npnpm db:start\npnpm db:sync\n```\n\n`pnpm generate:db-types` will run during `dev`, `build`, etc., if you're using the monorepo commands.\n\nHowever, if you change the DB schema via `apps/game-api/prisma/schema.prisma`, then you'll need to run `db:sync` again:\n```\npnpm db:sync\n```\n\nThis will generate a SQL migration, migrate your local DB, and update your types.\n\n\u003cb\u003eNOTE\u003c/b\u003e: This project uses Turborepo's Terminal UI ([tui](https://turborepo.com/blog/turbo-2-0#new-terminal-ui)) and some tasks are interactive, such as `test:watch` and `db:sync`. When you want to interact with a window, press \"i\", then interact as normal. Press \"ctrl\" + \"z\" to leave interactive mode.\n\n## Testing\n\nWhen you run `pnpm test` or `pnpm test:watch`, it will run the `game-api` test suite, which requires a local test DB to be running. This can be accomplished by following the instructions for [working with the PostgreSQL DB](#working-with-the-postgresql-db), with the only difference being that you add `test:` to the `db:` commands, ie:\n```\npnpm db:test:start\npnpm db:test:sync\npnpm db:test:stop\n```\n\n\u003cb\u003eNOTE\u003c/b\u003e: `pnpm test:watch` offers a similar experience to `pnpm dev`, in the sense that it will watch for graphql and prisma type changes, and hot-reload as needed. `pnpm test` acts as a complete CI check as it will run all the type generators, typechecks, linters, then finally tests.\n\n## Load Testing\n\nColyseus has a built-in load testing tool that can be used to test the scalability of the game rooms. The example load test is located in `apps/game-api/test/load/test.ts`. To start the load test, run:\n```\npnpm test:load\n```\n\n\u003cb\u003eNOTE\u003c/b\u003e: This will run the `game-api` CI checks, start the server in preview mode, then run the load test. The preview server is production-like, but pointed at a local test DB. Please ensure the test DB is running and synced, same as the [testing instructions](#testing) above:\n```\npnpm db:test:start\npnpm db:test:sync\n```\n\n## Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `pnpm install` | Installs dependencies for each repo |\n| `pnpm install:clean` | Runs a script to clear builds, caches, deps, etc., then runs install |\n| `pnpm test` | Runs the typecheck, linter and tests for each repo |\n| `pnpm test:watch` | Runs the test suite in each repo and watches for changes |\n| `pnpm test:load` | Builds and runs the `game-api` then starts the load test |\n| `pnpm lint` | Runs the code linting check in each repo |\n| `pnpm lint:fix` | Runs the linter and fixes code when possible |\n| `pnpm check-types` | Runs the typescript check in each repo |\n| `pnpm generate:gql-types` | Generates the GraphQL types in each repo |\n| `pnpm generate:gql-types:watch` | Generates the GraphQL types and watches each repo  |\n| `pnpm generate:db-types` | Generates DB types via `prisma.schema` |\n| `pnpm generate:db-types:watch` | Generates DB types via `prisma.schema` and watches for changes |\n| `pnpm db:start` | Uses `docker-compose` to start a local PostgreSQL DB |\n| `pnpm db:stop` | Uses `docker-compose` to stop the local PostgreSQL DB |\n| `pnpm db:sync` | Uses `prisma` to manage the local DB based on the `schema.prisma` |\n| `pnpm db:test:start` | Uses `docker-compose` to start a local PostgreSQL DB for testing |\n| `pnpm db:test:stop` | Uses `docker-compose` to stop the local PostgreSQL DB for testing |\n| `pnpm db:test:sync` | Uses `prisma` to manage the testing DB based on the `schema.prisma` |\n| `pnpm dev` | Run local development servers for each app |\n| `pnpm generate:app-icons` | Generates PWA/Electron icons from `apps/web/public/logo.svg` |\n| `pnpm generate:pwa-assets` | Generates PWA assets from `apps/web/public/logo.svg` |\n| `pnpm build` | Generates icons and builds each app including sub-repos |\n| `pnpm preview` | Builds each app and runs a local server using the output |\n| `pnpm build:win` | Builds the desktop app (via Electron) for Windows |\n| `pnpm build:mac` | Builds the desktop app (via Electron) for MacOS |\n| `pnpm build:linux` | Builds the desktop app (via Electron) for Linux |\n\n## Infra/Hosting Setup\n\nThis is TBD at this point still...\n\nThe goal is to provide Infrastructure as Code (IaC) for hosting a scalable, cheap setup. Possibly:\n\n\u003cimg src=\"./infra/system-design.png\" width=\"800px\" height=\"auto\"\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FASteinheiser%2Fts-online-game-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FASteinheiser%2Fts-online-game-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FASteinheiser%2Fts-online-game-template/lists"}