This is a Next.js 15+ TypeScript monorepo for the Mozilla "Billionaire Blast-Off" microsite. It features a HeroUI component library, Tailwind CSS v4 with a customized plugin, and the Flags SDK for feature flags.

• Project Overview
• Documentation
• Features
• Prerequisites
• Getting Started
• Environment Variables
• Project Structure
• Packages Overview
• Available Scripts
• Architecture & Technologies
• Quality Gates
• Contributing
• License

Project name: Mozilla Billionaire Blast-Off
Slack/Comms: #platform or project channel
Live URLs: preview via Vercel; production via Vercel/AWS (per project)

Summary: "Billionaire Blast-Off" is an interactive microsite designed to promote Firefox’s “Open What You Want” positioning through a satirical, Gen Z–friendly creative lens. Users can build their own billionaire avatar and learn about data privacy in a playful way. The project is built on a white-label Next.js starter that provides a production-ready foundation for quickly shipping client sites. The primary goal is to drive awareness, not data collection, with no PII being stored.

Goals / Success Metrics:

• Volume of avatars generated.
• Engagement with playpen actions.
• Return rate (users revisiting via hash/URL).
• Social sharing (tracked via outbound links, not user IDs).

For more in-depth information, please see the following documents:

• Product Requirements Document (PRD): Detailed information on campaign goals, user experience flow, success metrics, and constraints.
• Engineering Playbook: A comprehensive guide to the technical architecture, database schema, security measures, and deployment process.
• Frontend Documentation
• Architecture Documentation
• Environments Documentation

• Avatar Builder: Users can create a custom billionaire avatar by answering a 7-question quiz or get a randomly generated one. Avatars and bios are generated via an LLM API.
• Unique Avatar URL: Each user receives a unique "all-access pass" link (e.g., /a/{hash}) to their generated avatar, which they can share.
• Interactive Story: The experience guides users through a narrative about data privacy and corporate accountability.
• Avatar Gallery & Playpen: Users can perform actions with their avatar, such as taking a space selfie or doing a TikTok dance.
• Bento Grid Layout: The site uses a modern bento grid layout for its components.

• Node.js >= 18.x
• pnpm >= 7.x
• Git CLI

1. Clone the repository:

   git clone [git@github.com:mozilla/build-a-b.git](git@github.com:mozilla/build-a-b.git) cd build-a-b

2. Install dependencies:

   pnpm install

3. Copy environment variables:

   cp .env.example .env.local

4. Update .env.local with your environment-specific configuration.

All environment variables are defined in .env.example. Do not commit secrets; use your hosting provider's secret store for production credentials.

build-a-b/ ├─ apps/ │ ├─ web/ # Next.js application (frontend) │ │ └─ .env.example # Web-level .env is required for build │ └─ game/ # Vite/React SPA (embedded game) ├─ packages/ # shared packages (ui, config, utils) ├─ .env.example ├─ package.json └─ README.md 

• Next.js (App Router), TypeScript, Turbopack, Tailwind v4, HeroUI.
• Flags SDK for feature management.

• Vite/React SPA built with Rolldown for performance.
• Automatically builds and embeds into the Next.js app at /assets/game/ during the build process.
• Accessible via the /game route in the deployed Next.js application.

Root scripts:

pnpm dev # Start web and game (local) pnpm build # Build all packages (game builds automatically during web prebuild) pnpm start # Start web in production pnpm lint pnpm format pnpm test

Web package:

pnpm --filter web dev pnpm --filter web build # Automatically builds game app first via prebuild hook pnpm --filter web start pnpm --filter web lint

Game package:

pnpm --filter game dev # Run game in dev mode at http://localhost:5173 pnpm --filter game build # Build game (happens automatically during web build)

• Monorepo: pnpm workspaces + Turbo
• Frontend: Next.js (App Router), Server Components where applicable
• Styling: Tailwind v4, HeroUI component wrappers
• Feature flags: Vercel Flags SDK
• Game: Vite/React SPA with Rolldown (embedded via build process)

The apps/game Vite application is automatically integrated into the Next.js build process:

Local Development:

• Run pnpm --filter game dev to develop the game independently at http://localhost:5173
• Game uses base path / for local development
• Game is NOT automatically available in the Next.js dev server (run separately)

Production Build:

1. When pnpm build or pnpm --filter web build runs, the web app's prebuild hook executes first
2. The game is built with Vite using base path /assets/game/ (configured in vite.config.ts)
3. Build output from apps/game/dist/ is copied to apps/web/public/assets/game/
4. Next.js serves the game as static files
5. Next.js middleware (in apps/web/src/middleware.ts) rewrites /game requests to /assets/game/index.html

Accessing the Game:

• Local dev: http://localhost:5173 (separate Vite server)
• Production/deployed: https://yourdomain.com/game (served by Next.js)

All asset URLs (images, JS, CSS) are automatically prefixed with /assets/game/ in production builds.

These commands should run successfully in CI for PRs:

1. Type check: pnpm typecheck (tsc --noEmit)
2. Format: pnpm format
3. Lint: pnpm lint
4. Tests: pnpm test
5. Build: pnpm build

• Follow Conventional Commits. Fork → feature branch → PR.
• Include tests, stories, and docs for new components.
• Use ADRs (/adr) for architectural changes.

MIT © Mondo Robot