Metropolis Retro

🕹️ Metropolis Retro

“A high-speed strategic escape into the neon-soaked grid.”

Welcome to Metropolis Retro, an ultra-fast web application built for enthusiasts of chess, classic gaming, and vintage aesthetics. Hosted on Vercel and powered by Next.js with the Bun runtime, this platform merges timeless 64-square logic with a high-performance, retro-futuristic engine.

Basic Tests Workflow Status ls-lint Workflow Status

⚡ High-Performance Tech Stack

We utilize a modern, speed-first toolkit to ensure a lag-free experience for players and developers:

🛡️ Engineering Rigor

To maintain “Grandmaster” code quality, we employ a rigorous three-pillar pre-commit strategy:

  1. Standard Hooks: Automated linting, formatting, and syntax validation.
  2. Manual Verification: Curated checks for retro-theming accuracy.
  3. Audit-Based Security: Periodic hardening and dependency scanning to ensure a secure, production-ready environment.

🪝 prek hooks

🤝 Contributing

We welcome contributions from developers who want to help push Metropolis Retro to the next level. Whether you’re fixing a bug, adding a feature, or improving our retro aesthetic — all moves are welcome.

📋 Prerequisites

Before contributing, ensure you have the following installed:

Tool Version Purpose
Bun ≥ 1.3.11 JavaScript runtime, package manager & test runner
uv latest Python package manager for dev tooling (prek)
Python ≥ 3.13 Required by uv and pre-commit tooling
Node.js ≥ 24 Required by some prek hook dependencies
Git latest Version control

🚀 Getting Started

  1. Fork the repository on GitHub and clone your fork:

    git clone https://github.com/<your-username>/metropolis-retro.github.io.git
cd metropolis-retro.github.io

  2. Install all dependencies (Python tooling + Node/Bun packages):

    make install

    This runs uv sync (Python/prek tools) and bun install (JavaScript packages).

  3. Start the development server:

    make dev

    Open http://localhost:3000 in your browser.

🔧 Development Workflow

Command Description
make dev Start the Next.js dev server
make build Build the Next.js app for production
make lint Run ESLint on TypeScript/JavaScript files
make prek Run all prek hooks against all files
make prek-manual Run prek hooks with the manual stage
make build-games Build all game sub-projects
make clean Remove build artifacts and dependencies
make help List all available Make targets

✅ Code Quality Checks

All contributions must pass our three-pillar pre-commit strategy before merging:

  1. Standard hooks (make prek) — trailing whitespace, YAML/JSON validation, spell checking, secret detection, ESLint, markdownlint, and more.
  2. Manual hooks (make prek-manual) — file permission checks, image optimization.
  3. Audit hooks (prek run -a -c .pre-commit-config-audit.yaml) — security-focused dependency scanning.

Run the full standard suite locally before opening a pull request:

make prek

🌿 Branch & Pull Request Guidelines

  1. Create a feature branch from main:

    git checkout -b feat/your-feature-name

  2. Make your changes, commit with a clear message, then push:

    git push origin feat/your-feature-name
  3. Open a Pull Request against the main branch on GitHub.
  4. Ensure all CI checks pass (workflows run automatically on every PR).
  5. Request a review from a maintainer — see CODEOWNERS.

🎨 Code Style

This site is open source. Improve this page.