https://github.com/tobenot/basic-web-game-backend
๐ Modern TypeScript backend for web games with Fastify, tRPC & Prisma. Features magic link auth, type-safe APIs, and game-ready architecture.
https://github.com/tobenot/basic-web-game-backend
api authentication backend database deployment fastify game-backend game-development jwt magic-link nodejs orm prisma serverless trpc typesafe typescript vercel web-game web-game-backend
Last synced: 5 days ago
JSON representation
๐ Modern TypeScript backend for web games with Fastify, tRPC & Prisma. Features magic link auth, type-safe APIs, and game-ready architecture.
- Host: GitHub
- URL: https://github.com/tobenot/basic-web-game-backend
- Owner: tobenot
- License: mit
- Created: 2025-07-28T13:59:54.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-04T18:16:14.000Z (8 months ago)
- Last Synced: 2025-08-04T19:21:41.884Z (8 months ago)
- Topics: api, authentication, backend, database, deployment, fastify, game-backend, game-development, jwt, magic-link, nodejs, orm, prisma, serverless, trpc, typesafe, typescript, vercel, web-game, web-game-backend
- Language: HTML
- Homepage: https://basic-web-game-backend.vercel.app
- Size: 153 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Basic Web Game Backend
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://fastify.io/)
[](https://trpc.io/)
[](https://www.prisma.io/)
A modern, type-safe backend for web games built with Fastify, tRPC, and Prisma. Features secure authentication with magic links and a robust API architecture.
## โจ Features
- ๐ **Magic Link Authentication** - Secure, passwordless login system
- ๐ **Fastify Server** - High-performance Node.js web framework
- ๐ **tRPC Integration** - End-to-end type safety
- ๐๏ธ **Prisma ORM** - Type-safe database operations
- ๐ฑ **CORS Support** - Cross-origin resource sharing enabled
- ๐ฎ **Game-Ready API** - Built specifically for web game backends
- ๐ **User Management** - Complete user lifecycle management
- ๐ข **Announcement System** - Built-in announcement functionality
## ๐ ๏ธ Tech Stack
- **Runtime**: Node.js
- **Framework**: Fastify
- **API**: tRPC
- **Database**: Prisma ORM (SQLite/PostgreSQL)
- **Language**: TypeScript
- **Authentication**: JWT + Magic Links
- **Email**: Resend
## ๐ Quick Start
### Prerequisites
- Node.js 22+
- npm or yarn
- Database (SQLite for development, PostgreSQL for production)
### Installation
1. **Clone the repository**
```bash
git clone https://github.com/tobenot/Basic-Web-Game-Backend.git
cd Basic-Web-Game-Backend
```
2. **Install dependencies**
```bash
npm install
```
3. **Set up environment variables**
```bash
cp .env.example .env
```
Configure your `.env` file:
```env
DATABASE_URL="file:./dev.db"
JWT_SECRET="your-secret-key"
RESEND_API_KEY="your-resend-api-key"
EMAIL_FROM="noreply@sendmail.tobenot.top"
EMAIL_FROM_NAME="YourApp"
```
4. **Generate Prisma schema and run migrations**
```bash
npm run migrate:dev
```
5. **Start the development server**
```bash
npm run dev
```
The server will be available at `http://localhost:3000`
## ๐ API Documentation
### Authentication Endpoints
- `POST /api/trpc/auth.sendMagicLink` - Send magic link to user email
- `POST /api/trpc/auth.verifyToken` - Verify magic link token
- `GET /api/trpc/auth.me` - Get current user info
Magic link generation:
- Uses frontend URL (`FRONTEND_LOCAL_URL` / `FRONTEND_PRODUCTION_URL`) as base
- Appends `token` as a query param
- If the frontend URL contains a hash route, the query is inserted before the hash so the frontend can read it
### User Management
- `GET /api/trpc/user.profile` - Get user profile
- `PUT /api/trpc/user.update` - Update user information
### Announcements
- `GET /api/trpc.announcement.list` - Get announcement list
- `POST /api/trpc.announcement.create` - Create new announcement
## ๐๏ธ Database Schema
The application uses Prisma with the following models:
- **User**: Core user information and authentication
- **AuthToken**: Magic link tokens for passwordless authentication
## ๐งช Development
### Available Scripts
```bash
# Development
npm run dev # Start development server
npm run build # Build for production
npm run studio # Open Prisma Studio
# Database
npm run migrate:dev # Run migrations in development
npm run migrate:prod # Deploy migrations to production
# Utilities
npm run prisma:generate:schema # Generate Prisma schema
npm run copy-templates # Copy template files
```
### ๅๅธๅฐ GitHub Packages
1. ๆๅจ่งฆๅๅทฅไฝๆต `Update Version`๏ผ้ๆฉ `patch|minor|major`
2. ๆตๆฐด็บฟๅฐๆไบค็ๆฌๆดๆฐ๏ผ้ๅ่ชๅจ่งฆๅ `Publish API Contract` ๅฎๆๅๅธ
3. ้ช่ฏ็ๆฌ๏ผ
```bash
npm view @tobenot/basic-web-game-backend-contract version --registry=https://npm.pkg.github.com
```
4. ๅ็ซฏๅฎ่ฃ
๏ผ
```bash
yarn add @tobenot/basic-web-game-backend-contract@latest
```
ๅค็จ๏ผๆฌๅฐ็ดๆฅๅๅธ
```bash
npm login --scope=@tobenot --registry=https://npm.pkg.github.com
npm run build
npm version patch --no-git-tag-version
npm publish --registry=https://npm.pkg.github.com
```
### Project Structure
```
src/
โโโ ai/ # AI service & queue
โ โโโ AiService.ts
โ โโโ AiRequestQueueService.ts
โ โโโ types.ts
โโโ routers/ # tRPC/Fastify routers
โ โโโ auth.ts
โ โโโ user.ts
โ โโโ announcement.ts
โ โโโ llm-proxy.ts
โโโ utils/ # Utilities (e.g. LLM upstream client)
โ โโโ llm-client.ts
โโโ templates/ # Email templates
โโโ server.ts # Fastify server setup
โโโ trpc.ts # tRPC configuration
```
## ๐ Deployment
### Vercel Deployment
This project is configured for Vercel deployment. The `vercel.json` file contains the necessary configuration.
### Environment Variables for Production
```env
DATABASE_URL="postgresql://..."
JWT_SECRET="your-production-secret"
RESEND_API_KEY="your-resend-api-key"
```
## ๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
### Development Guidelines
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐ Acknowledgments
- Built with [Fastify](https://fastify.io/) for high-performance web applications
- Powered by [tRPC](https://trpc.io/) for end-to-end type safety
- Database management with [Prisma](https://www.prisma.io/)
- Email delivery via [Resend](https://resend.com/)
## ๐ Support
If you have any questions or need help, please:
- Open an [issue](https://github.com/tobenot/Basic-Web-Game-Backend/issues)
- Check the [documentation](https://github.com/tobenot/Basic-Web-Game-Backend#readme)
---
**Made with โค๏ธ by [tobenot](https://github.com/tobenot)**
*This project is maintained as an independent open-source effort to provide a solid foundation for web game backends.*
## Template Updates
- Use the bundled script to preview/apply template updates:
- Preview latest: `bash scripts/update-from-template.sh`
- Apply a specific tag with backup: `APPLY=1 bash scripts/update-from-template.sh vX.Y.Z`
- The template source and version are recorded in `template.lock`.
- Install a non-blocking pre-commit reminder:
```bash
bash scripts/install-git-hooks.sh
```
- Controlled areas (prefer updating via template): `.github/`, `scripts/`, `src/framework/`, template-marked blocks in `src/server.ts`, `tsconfig.json`, `vercel.json`, and docs listed in `MIGRATION.md`.