Mini Sudoku is a lightweight, browser-based puzzle game that offers two distinct modes of operation:

• 🔧 Development Mode: A clean, distraction-free Sudoku game that runs instantly with zero configuration
• 🚀 Production Mode: Full-featured experience with user authentication, cloud statistics, and progress tracking

Built with vanilla JavaScript and Tailwind CSS v4, the game is designed to be easily deployable, highly customizable, and friendly to both players and developers. The 6×6 grid (instead of traditional 9×9) makes it perfect for quick gaming sessions while maintaining the classic Sudoku challenge.

• Zero Setup Required - Clone and play immediately in dev mode
• Dual-Mode Architecture - Switch between local-only and cloud-powered with one environment variable
• Modern UI/UX - Beautiful gradients, dark mode, smooth animations, responsive design
• Firebase Integration - Optional authentication, cloud storage, and real-time sync
• Mobile-Friendly - Touch-optimized controls and responsive layout
• Lightweight - No heavy frameworks, pure vanilla JavaScript
• Customizable - Modular codebase, easy to extend and modify

• Easy: 14 cells removed (~39% empty), perfect for beginners
• Medium: 18 cells removed (~50% empty), balanced challenge
• Hard: 22 cells removed (~61% empty), brain-teaser mode

• Backtracking algorithm ensures solvable puzzles
• Randomized patterns for unique games
• Proper 2×3 box validation (6 boxes total in 6×6 grid)

Mini Sudoku follows classic Sudoku rules on a 6×6 grid:

1. Row Rule: Each row must contain numbers 1-6 with no repeats
2. Column Rule: Each column must contain numbers 1-6 with no repeats
3. Box Rule: Each 2×3 box must contain numbers 1-6 with no repeats

• Real-Time Validation - Instant feedback on incorrect moves with visual highlighting
• Timer - Tracks elapsed time from game start
• Mistake Counter - Tracks number of incorrect moves
• Game Actions:
  • New Game: Start fresh puzzle with confirmation
  • Check: Validate current solution
  • Hint: Reveal one correct cell
  • Solve: Auto-complete puzzle (for learning)
• Input Methods:
  • Click/tap to select cells
  • Keyboard input (1-6, Backspace, Delete)
  • Touch-optimized number pad for mobile
  • Erase button with visual feedback
• Visual Feedback:
  • Cell selection highlighting
  • Initial cells marked with distinct styling
  • User-entered numbers in accent color
  • Proper 2×3 box borders with bold lines
• Victory Modal - Shows completion time and mistakes

• User Authentication - Email/Password and Google OAuth sign-in
• Statistics Dashboard - Games played, win rate, streaks, best times
• Game History - Track all completed games with timestamps
• Cross-Device Sync - Progress saved to Firebase Firestore
• User Profile - Display name, avatar, and email

• Node.js (v14 or higher) - For npm and Vite
• Git - For cloning the repository
• Modern Browser - Chrome, Firefox, Safari, or Edge

git clone https://github.com/gvenugo3/mini-sudoku
cd mini-sudoku

npm install

This installs:

• Tailwind CSS v4
• PostCSS and Autoprefixer
• Jest (for testing)
• Firebase SDK
• Vite (development server)

npm run dev

The app will start on http://localhost:8000 and open automatically in your browser.

That's it! The game runs in Development Mode by default. No Firebase setup needed! 🎉

By default, the app runs in development mode, which provides:

• ✅ Full Sudoku game functionality
• ✅ All difficulty levels (Easy, Medium, Hard)
• ✅ Timer and mistakes tracking
• ✅ Number pad and keyboard input
• ✅ Theme toggle (light/dark)
• ✅ Victory modal
• ✅ Toast notifications
• ❌ No authentication required
• ❌ No dashboard or statistics
• ❌ No Firebase dependency

(To track your progress)

💡 Quick Start: Don't want to go through the complete setup? Try the live demo to see all features in action!

Enable full features with Firebase integration:

1. Go to Firebase Console
2. Click "Add Project"
3. Follow the setup wizard
4. Add a web app to your project

2a. Enable Authentication

1. Go to Authentication → Sign-in method
2. Enable "Email/Password"
3. Enable "Google" (optional, for Google sign-in)

2b. Create Firestore Database

1. Go to Firestore Database
2. Click "Create database"
3. Start in production mode
4. Choose a location (e.g., us-central1)

2c. Configure Firestore Security Rules

Go to Firestore Database → Rules and paste:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // User data: authenticated users can only access their own data
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }

    // Game history: users can only access their own games
    match /users/{userId}/games/{gameId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

Click "Publish" to save the rules.

2d. Get Firebase Credentials

1. Go to Project Settings → General
2. Scroll to "Your apps"
3. Click your Web app
4. Copy the configuration values

1. Create .env.local file in the project root:

# Application Mode: 'dev' or 'production'
VITE_APP_MODE=production

# Firebase Configuration (Required for production mode)
VITE_FIREBASE_API_KEY=your_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FIREBASE_MEASUREMENT_ID=your_measurement_id

2. Replace placeholders with your actual Firebase credentials

⚠️ Security Notes:

• .env.local is in .gitignore - your credentials are safe
• NEVER commit credentials to version control
• Firebase credentials stay in .env.local ONLY

# Stop current server (Ctrl+C), then:
npm run dev

Check the console:

🚀 Running in PRODUCTION mode
🔥 Firebase app initialized
✅ Firebase initialized successfully

Hard refresh browser:

• Mac: Cmd + Shift + R
• Windows/Linux: Ctrl + Shift + F5

After switching, verify these features work:

• ✅ Dashboard sidebar appears (desktop) or hamburger menu (mobile)
• ✅ "Sign In to Save Progress" button visible
• ✅ Authentication modal opens
• ✅ Email/Password sign-up and sign-in work
• ✅ Google OAuth sign-in works (if enabled)
• ✅ Dashboard shows statistics after login
• ✅ Game history populates after completing games
• ✅ Sign out works correctly

The app uses Vite environment variables to switch between development and production modes.

⚠️ IMPORTANT: All configuration is in .env.local file!

1. Edit .env.local - Change VITE_APP_MODE value
2. Restart dev server - Stop (Ctrl+C) and run npm run dev again
3. Vite reads the environment - Injects variables at build time

All configuration in ONE file: .env.local

.env.local (you edit this)
    ↓
Vite reads environment variables
    ↓
import.meta.env.VITE_APP_MODE available in code
    ↓
UI adjusts based on mode

1. Edit .env.local and set:

VITE_APP_MODE=production

# Add your Firebase credentials
VITE_FIREBASE_API_KEY=...
VITE_FIREBASE_AUTH_DOMAIN=...
# ... (all other Firebase config)

2. Restart dev server:

npm run dev

3. Hard refresh browser (Cmd + Shift + R or Ctrl + Shift + F5)

1. Edit .env.local and change:

VITE_APP_MODE=dev

2. Restart dev server:

npm run dev

3. Hard refresh browser

Console should show:

🔧 Running in DEV mode
🔧 Dev mode: Skipping Firebase initialization

The dashboard and authentication will be completely hidden.

⚠️ Remember: Restart the dev server whenever you change .env.local!

All variables go in .env.local file:

# Required: App Mode
VITE_APP_MODE=dev                                    # or 'production'

# Required for Production Mode: Firebase Credentials
VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FIREBASE_MEASUREMENT_ID=your_measurement_id

Important Notes:

• All variables must have VITE_ prefix to be accessible in the browser
• Restart dev server after changing .env.local
• .env.local is gitignored - safe for credentials
• Never commit credentials to version control

Firebase errors in dev mode?

• This is expected! Dev mode skips Firebase initialization
• Check console for "🔧 Dev mode: Skipping Firebase initialization"

Port 8000 already in use?

# Find and kill process
lsof -ti:8000 | xargs kill
# Or change port in vite.config.js

Google sign-in not working?

• Ensure domain is added to Firebase Console → Authentication → Settings → Authorized domains
• Enable Google provider in Firebase Console → Authentication → Sign-in method
• Check browser console for specific error messages

Contributions are welcome and appreciated! Whether you're fixing bugs, adding features, improving documentation, or reporting issues, your help makes this project better.

Found a bug? Please open an issue with:

• Clear title: Describe the issue briefly
• Steps to reproduce: How to trigger the bug
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Environment: Browser, OS, dev/prod mode
• Screenshots: If applicable

Have an idea? Open an issue with:

• Feature description: What you want added
• Use case: Why it's useful
• Possible implementation: Ideas on how to build it (optional)

Process:

1. Fork the repository

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/mini-sudoku.git
   cd mini-sudoku

3. Create a branch for your feature

   git checkout -b feature/amazing-feature

4. Make your changes

   • Follow the code style guidelines below
   • Write/update tests if needed
   • Update documentation if needed

5. Test your changes

   npm test
   npm run dev
   # Test manually in browser

6. Commit with a clear message

   git add .
   git commit -m "feat: Add amazing feature"

   Use conventional commits:

   • feat: - New feature
   • fix: - Bug fix
   • docs: - Documentation
   • style: - Code style (formatting)
   • refactor: - Code refactoring
   • test: - Adding tests
   • chore: - Maintenance

7. Push to your fork

   git push origin feature/amazing-feature

8. Open a Pull Request

   • Go to the original repository
   • Click "New Pull Request"
   • Select your branch
   • Describe your changes clearly

JavaScript:

• Use ES6+ features (arrow functions, destructuring, etc.)
• 2-space indentation
• camelCase for variables/functions
• PascalCase for classes
• Descriptive variable names
• Add JSDoc comments for functions

Example:

/**
 * Validates if a number placement is legal
 * @param {number} row - Row index (0-5)
 * @param {number} col - Column index (0-5)
 * @param {number} num - Number to place (1-6)
 * @returns {boolean} True if placement is valid
 */
function isValidMove(row, col, num) {
  // Implementation
}

HTML/CSS:

• Use Tailwind utility classes
• Semantic HTML5 tags
• Accessible markup (ARIA labels where needed)
• Mobile-first responsive design

Git Commits:

• Clear, concise commit messages
• Use conventional commit format
• One logical change per commit
• Reference issue numbers when applicable

• Write tests for new features
• Ensure existing tests pass (npm test)
• Test in multiple browsers
• Test in both dev and prod modes
• Test responsive behavior on mobile

• Update README.md if adding features
• Add JSDoc comments for new functions
• Include code examples where helpful

• Be respectful and constructive
• Welcome newcomers
• Give credit where due
• Focus on the code, not the person
• Help others learn and grow

Thank you for contributing! 🙏

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 Mini Sudoku Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

• Classic Sudoku - The timeless puzzle game that inspired this project
• LinkedIn - For professional networking and learning resources