roundtable-mlh-boilerplate

Production-ready CLI to scaffold official, organizer-approved hackathon starter projects for RoundtableXMLH.

🎯 Overview

create-roundtable-mlh-boilerplate is an official hackathon boilerplate generator. When participants run:

npx create-roundtable-mlh-boilerplate

(No project name needed in the command — the interactive wizard prompts for it automatically!)

it automatically scaffolds a clean, standardized, full-stack boilerplate, initializes a local Git repository, and commits only the official organizer-provided boilerplate code.

⚖️ Fair-Play Guarantee

To guarantee competition integrity:

• Zero Business Logic: Contains no hackathon-specific application features, pre-built pages, or solution logic.
• Clean Git History: The initial Git commit contains exclusively the organizer starter template, providing judges with a verifiable baseline.
• Organizer Approved: Preconfigured with standard client/server structure, linting, and health check endpoints.

🚀 Quick Start

Generate a new hackathon project without pre-installing any packages:

npx create-roundtable-mlh-boilerplate

Expected Output

🚀 Creating Hackathon Project...

✓ Project name validated
✓ Boilerplate copied
✓ Git repository initialized
✓ Initial boilerplate commit created

Project created successfully!

Next steps:

  cd team-alpha
  npm install

Start building your hackathon project!

⚠️ Only the official hackathon boilerplate is provided.
⚠️ Do not use pre-existing project code.

📦 What's Included in the Boilerplate

<project-name>/
├── client/                 # Frontend client (Vite + Modern JS)
│   ├── public/             # Static public assets
│   ├── src/
│   │   ├── components/     # UI component skeleton
│   │   ├── styles/         # CSS design tokens & style resets
│   │   └── main.js         # Frontend bootstrap
│   ├── index.html          # HTML entry point
│   └── package.json
├── server/                 # Backend API (Node.js + Express)
│   ├── src/
│   │   ├── config/         # Database connector skeleton (Postgres/Mongo/SQLite)
│   │   ├── controllers/    # API controllers (healthController)
│   │   ├── routes/         # API routes (/api/health)
│   │   └── index.js        # Express application entry point
│   ├── .env.example        # Environment variable definitions
│   └── package.json
├── .eslintrc.json          # Shared ESLint configuration
├── .prettierrc             # Standard code formatting rules
├── .gitignore              # Pre-configured ignore rules (node_modules, .env, dist)
├── package.json            # Root workspace configuration
└── README.md               # Team guidelines & instructions

🛠️ CLI Options

| Flag | Description | | :--- | :--- | | -y, --yes | Skip interactive questionnaire and use defaults | | -h, --help | Display usage instructions and options | | -v, --version | Display current package version |

📋 Interactive Questionnaire

When run interactively in a terminal, roundtable-mlh-boilerplate walks participants through an organizer-approved questionnaire:

1. Project name (kebab-case): Target folder & package name (e.g. team-alpha)
2. Team name: Name of the participating team (e.g. Alpha Wolves)
3. One-line tagline (max 80 chars): Elevator pitch for the project
4. Team members: Comma-separated list of team member names
5. Problem statement (max 300 chars): Target problem statement
6. Frontend framework: Choose Next.js 14, React (Vite), or Vanilla HTML/JS
7. Backend framework: Choose Express, Fastify, or None (Frontend only)
8. Database: Choose MongoDB, PostgreSQL, SQLite, or None
9. Authentication: Choose JWT, Session-based, or None
10. Add-ons: Select optional setups like Docker setup, TailwindCSS, Socket.io
11. Install dependencies now?: Automatically run npm install inside the project

🧪 Local Testing Before Publishing

You can test roundtable-mlh-boilerplate locally before publishing it to the npm registry:

1. Clone & Enter Repository

cd roundtable-mlh-boilerplate

2. Run Automated Test Suite

npm test

3. Test Directly with Node

node ./bin/cli.js test-project

4. Test via Global Link (npm link)

Register the CLI command globally on your development machine:

npm link

Now execute it anywhere as if installed from npm:

roundtable-mlh-boilerplate my-hackathon-team

Inspect the generated project:

cd my-hackathon-team
git log -1 --stat

When finished testing, remove the global link:

npm unlink -g roundtable-mlh-boilerplate

🚢 Publishing to NPM

1. Verify Package Contents

Check what will be included in the published bundle:

npm pack --dry-run

Ensure only bin/, src/, template/, and necessary metadata files are listed.

2. Log in to npm

npm login

3. Publish

npm publish --access public

Once published, participants anywhere in the world can run:

npx create-roundtable-mlh-boilerplate

🧩 Architecture

roundtable-mlh-boilerplate/
├── bin/
│   └── cli.js         # Main CLI executable entry point
├── src/
│   ├── args.js        # Argument and flag parser
│   ├── validate.js    # Project name and directory validation
│   ├── copy.js        # Template copier with placeholder resolution
│   ├── git.js         # Cross-platform Git initialization & commit engine
│   └── ui.js          # Terminal styling, banners, and formatters
├── template/          # Official hackathon boilerplate files
├── test/              # Comprehensive automated test suite
├── package.json       # CLI package manifest
└── README.md          # Documentation

• Zero Runtime Dependencies: Uses Node.js built-in standard library (node:fs, node:path, node:child_process, node:url) for instantaneous execution via npx with zero download delays.
• Cross-Platform: Tested on Windows, macOS, and Linux.
• Fault-Tolerant: If Git is not installed or configured on a participant's machine, the project is safely preserved and an informative warning is displayed.

📄 License

MIT © Hackathon Organizer Team