Word Games is Dumb and Stoopid but Fam Likes em

A family-friendly word game website built with Next.js.

Quick Start

This project uses Docker for development. No local Node.js installation required.

# Start the development server
docker compose up

# Open in browser
open http://localhost:3000

Available Games

Guess What the Dog Wants

A hangman-style word puzzle where players decode what a dog is trying to communicate through barks.

How it works:

1. The dog "barks" a clue where each word is encoded as dog sounds (bark, woof, arf, grr, ruff, yip, howl)
2. The bark length matches the word length (e.g., "Please" becomes "Barrrrk")
3. Players guess what category the dog wants: Walk, Food, Pets/Cuddles, Go Outside, Play Fetch, Water, or Treats
4. Wrong guesses let players reveal a letter from the clue
5. The game ends when the correct category is guessed
6. Score = number of wrong guesses (lower is better)

Where Does the Comma Go?

A punctuation game where a bouncing comma moves through a sentence and players must stop it in the right spot.

How it works:

1. A sentence is displayed with its comma(s) removed
2. A comma bounces back and forth between each word boundary
3. Players click or press Space to place the comma at the current position
4. Some sentences have multiple commas — players must find all of them to win
5. Wrong guesses are counted (lower is better)

Development

# Start dev server (with debugger enabled)
docker compose up

# Run tests
docker compose run --rm app npm run test:run

# Run linting
docker compose run --rm app npm run lint

# Run linting and tests together
docker compose run --rm app npm run check

# Build for production
docker compose run --rm app npm run build

# Stop containers
docker compose down

Debugging

All interactive game logic runs as client components in the browser. Use your IDE's browser debugging support to hit breakpoints in components, hooks, and game logic.

WebStorm / IntelliJ (recommended)

1. Run docker compose up in your terminal and wait for the dev server to be ready.
2. Go to Run → Edit Configurations → Add (+) → JavaScript Debug.
3. Set the URL to http://localhost:3000.
4. Click OK, then select the new configuration and click Debug (the bug icon).
5. WebStorm launches a browser and connects to its DevTools protocol — breakpoints set in your source files will be hit.

VS Code

1. Run docker compose up in your terminal.
2. Add a launch configuration in .vscode/launch.json:

   {
     "type": "chrome",
     "request": "launch",
     "name": "Debug in Chrome",
     "url": "http://localhost:3000",
     "webRoot": "${workspaceFolder}"
   }

3. Press F5 to launch the browser and start debugging.

Chrome / Edge DevTools

Open http://localhost:3000 in Chrome or Edge, press F12, and use the Sources tab. Your source files appear with full source map support.

Node.js server debugging (advanced)

The dev server also starts with the Node.js inspector enabled on ports 9229 and 9230 for debugging the Next.js server process itself (e.g., next.config.ts, middleware). This is rarely needed for a static export app. To use it, create an Attach to Node.js configuration targeting port 9230 and add a path mapping from /app (the Docker container path) to your local project root.

Tech Stack

• Next.js 16 with App Router
• React 19
• Tailwind CSS 4
• TypeScript 5
• Vitest for testing
• Node.js 24 LTS
• Docker Compose for development

Project Structure

src/
├── app/                      # Next.js pages and layouts
├── components/               # React components
├── lib/                      # Core game logic
├── hooks/                    # Custom React hooks
├── data/                     # Game data
└── __tests__/               # Tests

CI/CD

The project uses GitHub Actions for continuous integration and deployment:

CI Workflow (ci.yml)

Runs on all pull requests and includes:

• Build and test job (linting, tests, build)
• Preview deployment to Netlify (skipped for Dependabot PRs)

Note: Dependabot PRs and fork PRs skip the Netlify deployment step since GitHub doesn't provide secrets to Dependabot or fork PRs for security reasons. The workflow checks the PR author and verifies secrets are available before attempting deployment.

Deploy Workflow (deploy.yml)

Runs on version tags (v*) or manual workflow dispatch and deploys to Netlify production. Does not run on every merge to main.

Generating the Changelog

Run the script to generate or update CHANGELOG.md from GitHub releases:

./scripts/generate-changelog.sh              # Writes to CHANGELOG.md
./scripts/generate-changelog.sh docs/CHANGES.md  # Custom output path

Requirements: GitHub CLI (gh) installed and authenticated.

This script was generated by the smp-github Claude Code plugin.

Future Ideas

• User authentication and score tracking
• Leaderboard
• More word games
• Daily challenge mode
• Difficulty levels