create-react-adam 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# create-react-adam
+
+Create opinionated React apps with TypeScript, Vite, Wouter, and Tailwind CSS.
+
+## Quick Start
+
+```bash
+npx create-react-adam@latest my-app
+cd my-app
+npm run dev
+```
+
+## CLI Options
+
+- `--dir <path>` - Create the project in a specific directory
+
+  ```bash
+  npm create react-adam@latest my-app --dir ~/projects
+  ```
+
+- `--with-e2e` - Include E2E testing setup without prompting
+
+  ```bash
+  npm create react-adam@latest my-app --with-e2e
+  ```
+
+- `--no-e2e` - Skip E2E testing setup without prompting
+  ```bash
+  npm create react-adam@latest my-app --no-e2e
+  ```
+
+## What's Included
+
+### Core Stack
+
+- **React** - Latest version with TypeScript support
+- **Vite** - Lightning-fast development server with HMR
+- **Wouter** - Minimalist client-side routing (~1.3kB)
+- **Tailwind CSS 4** - Utility-first CSS
+- **React Icons** - Popular icon library
+
+### Code Quality Tools
+
+#### ESLint
+
+Configured with a modern flat config (`eslint.config.js`) that includes:
+
+- **TypeScript ESLint** - Recommended and strict presets for type-safe code
+- **React Hooks** - Ensures correct hooks usage patterns
+- **React Refresh** - Validates fast refresh compatibility
+- **JSX Accessibility** - Enforces accessibility best practices (a11y)
+- **Prettier integration** - Disables conflicting formatting rules
+
+Why ESLint? It catches bugs early, enforces consistent code patterns, and integrates seamlessly with TypeScript. The strict preset helps maintain high code quality standards.
+
+#### Prettier
+
+Configured with two powerful plugins:
+
+- **prettier-plugin-organize-imports** - Automatically sorts and removes unused imports
+- **prettier-plugin-tailwindcss** - Sorts Tailwind class names consistently
+
+Why Prettier? It eliminates debates about code style by automatically formatting code. The organize-imports plugin keeps imports clean, and the Tailwind plugin ensures class names follow the recommended ordering.
+
+### Optional E2E Testing
+
+When you include E2E testing (via prompt or `--with-e2e` flag), you get:
+
+- **Playwright** - Modern, reliable E2E testing framework
+- **Allure Reports** - Beautiful, detailed test reports
+- Pre-configured test setup with example tests
+- HTML reports and Allure integration
+
+### Dependency Management
+
+- **Exact version pinning** - All dependencies use exact versions (no `^` or `~`)
+- **`.npmrc` configuration** - Ensures `save-exact=true` for all future installs
+- **Renovate-friendly** - Compatible with automated dependency updates
+
+### GitHub Actions Workflows
+
+Two CI workflows are included in the generated projects:
+
+1. **Code Checks** (`.github/workflows/check.yml`)
+
+   - TypeScript type checking
+   - Prettier formatting validation
+   - ESLint linting
+   - Production build verification
+
+2. **E2E Tests** (`.github/workflows/e2e.yml`) - if E2E is included
+   - Runs Playwright tests in CI
+   - Uploads test reports as artifacts
+   - Configures Allure results
+
+## Available Scripts
+
+### Development
+
+#### `npm run dev`
+
+Starts the Vite development server with hot module replacement.
+
+#### `npm run build`
+
+Builds the app for production to the `dist` folder. Runs TypeScript compiler and Vite build.
+
+#### `npm run preview`
+
+Previews the production build locally.
+
+### Code Quality
+
+#### `npm run lint`
+
+Runs ESLint and automatically fixes issues where possible.
+
+#### `npm run lint:check`
+
+Runs ESLint without fixing issues. Useful for CI environments.
+
+#### `npm run format`
+
+Formats all files with Prettier, organizing imports and sorting Tailwind classes.
+
+#### `npm run format:check`
+
+Checks if files are formatted correctly without modifying them. Useful for CI environments.
+
+### E2E Testing (if included)
+
+#### `npm run test:e2e`
+
+Runs all Playwright E2E tests headlessly.
+
+#### `npm run test:e2e:ui`
+
+Opens Playwright's interactive UI mode for debugging tests.
+
+#### `npm run test:e2e:report`
+
+Generates and opens the Allure test report.
+
+### Troubleshooting
+
+#### `npm run itDoesNotWork`
+
+Runs basic troubleshooting checks:
+
+- Installs dependencies
+- Checks if Vite dev server is running
+- Provides helpful diagnostic information
+
+## Project Structure
+
+```
+my-app/
+├── src/
+│   ├── pages/          # Page components
+│   │   ├── Home/
+│   │   └── About/
+│   ├── App.tsx         # Main app with routing
+│   ├── main.tsx        # Entry point
+│   └── app.css         # Tailwind directives
+├── e2e/                # E2E tests (optional)
+├── .github/            # GitHub Actions workflows
+└── package.json
+```
+
+## Why This Stack?
+
+- **Modern**: Latest versions of React, Vite, and Tailwind
+- **Lightweight**: Minimal dependencies, under 1MB node_modules (before dev deps)
+- **Type-safe**: Full TypeScript support with strict checking
+- **Fast**: Vite's instant HMR and optimized builds
+- **Accessible**: Built-in a11y linting ensures inclusive UIs
+- **Maintainable**: Automated formatting and linting prevent technical debt
+- **CI-ready**: Workflows for testing and validation out of the box
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readdir, mkdir, readFile, writeFile, copyFile, stat, rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import { spawn } from 'child_process';
+import * as readline from 'readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const args = process.argv.slice(2);
+
+function parseArgs(args) {
+  const parsed = {
+    projectName: null,
+    flags: {}
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const nextArg = args[i + 1];
+      if (nextArg && !nextArg.startsWith('--')) {
+        parsed.flags[key] = nextArg;
+        i++;
+      } else {
+        parsed.flags[key] = true;
+      }
+    } else if (!parsed.projectName) {
+      parsed.projectName = arg;
+    }
+  }
+
+  return parsed;
+}
+
+function validateProjectName(name) {
+  if (!name) {
+    return 'Project name is required';
+  }
+  if (!/^[a-z0-9-_]+$/i.test(name)) {
+    return 'Project name can only contain letters, numbers, hyphens, and underscores';
+  }
+  return null;
+}
+
+async function copyDirectory(src, dest, excludePaths = []) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+
+    const shouldExclude = excludePaths.some(excludePath => {
+      if (entry.isDirectory() && entry.name === excludePath) {
+        return true;
+      }
+      return srcPath.endsWith(`/${excludePath}`) || srcPath.endsWith(`\\${excludePath}`);
+    });
+
+    if (shouldExclude) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath, excludePaths);
+    } else {
+      await copyFile(srcPath, destPath);
+    }
+  }
+}
+
+function askQuestion(query) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(query, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function replaceInFile(filePath, replacements) {
+  let content = await readFile(filePath, 'utf-8');
+  for (const [key, value] of Object.entries(replacements)) {
+    content = content.replace(new RegExp(key, 'g'), value);
+  }
+  await writeFile(filePath, content, 'utf-8');
+}
+
+function runCommand(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: 'inherit'
+    });
+
+    child.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed with exit code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+async function main() {
+  const { projectName, flags } = parseArgs(args);
+
+  const validationError = validateProjectName(projectName);
+  if (validationError) {
+    console.error(`Error: ${validationError}`);
+    console.log('\nUsage: npm create react-adam@latest <project-name> [options]');
+    console.log('\nOptions:');
+    console.log('  --dir <path>       Create the project in a specific directory');
+    console.log('  --with-e2e         Include E2E testing setup (Playwright + Allure)');
+    console.log('  --no-e2e           Skip E2E testing setup');
+    console.log('  --with-utils       Include utility functions (classNames, Storage, useUrlState)');
+    console.log('  --no-utils         Skip utility functions');
+    process.exit(1);
+  }
+
+  const baseDir = flags.dir || flags.directory || process.cwd();
+  const projectPath = join(baseDir, projectName);
+
+  if (existsSync(projectPath)) {
+    console.error(`Error: Directory "${projectName}" already exists`);
+    process.exit(1);
+  }
+
+  let includeE2E = false;
+  if (flags['with-e2e']) {
+    includeE2E = true;
+  } else if (flags['no-e2e']) {
+    includeE2E = false;
+  } else {
+    const answer = await askQuestion('Include E2E testing setup (Playwright + Allure)? (y/N): ');
+    includeE2E = answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
+  }
+
+  let includeUtils = false;
+  if (flags['with-utils']) {
+    includeUtils = true;
+  } else if (flags['no-utils']) {
+    includeUtils = false;
+  } else {
+    const answer = await askQuestion('Include utility functions (classNames, Storage, useUrlState)? (y/N): ');
+    includeUtils = answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
+  }
+
+  console.log(`Creating a new Adam React app in ${projectPath}...`);
+
+  const templatePath = join(__dirname, '..', 'template');
+  const excludePaths = [];
+  
+  if (!includeE2E) {
+    excludePaths.push('e2e', 'playwright.config.ts', '.e2e-deps.json');
+  }
+
+  if (!includeUtils) {
+    excludePaths.push('utils');
+  }
+
+  await copyDirectory(templatePath, projectPath, excludePaths);
+
+  if (!includeUtils) {
+    await copyFile(
+      join(projectPath, 'src', 'pages', 'Home', 'index.no-utils.tsx'),
+      join(projectPath, 'src', 'pages', 'Home', 'index.tsx')
+    );
+    await copyFile(
+      join(projectPath, 'src', 'pages', 'About', 'index.no-utils.tsx'),
+      join(projectPath, 'src', 'pages', 'About', 'index.tsx')
+    );
+    await rm(join(projectPath, 'src', 'pages', 'Home', 'index.no-utils.tsx'));
+    await rm(join(projectPath, 'src', 'pages', 'About', 'index.no-utils.tsx'));
+  } else {
+    await rm(join(projectPath, 'src', 'pages', 'Home', 'index.no-utils.tsx'));
+    await rm(join(projectPath, 'src', 'pages', 'About', 'index.no-utils.tsx'));
+  }
+
+  const replacements = {
+    '__PROJECT_NAME__': projectName
+  };
+
+  await replaceInFile(join(projectPath, 'package.json'), replacements);
+  await replaceInFile(join(projectPath, 'index.html'), replacements);
+  await replaceInFile(join(projectPath, 'README.md'), replacements);
+
+  if (includeE2E) {
+    const e2eDepsPath = join(projectPath, '.e2e-deps.json');
+    const packageJsonPath = join(projectPath, 'package.json');
+    
+    const e2eDeps = JSON.parse(await readFile(e2eDepsPath, 'utf-8'));
+    const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf-8'));
+    
+    packageJson.scripts = { ...packageJson.scripts, ...e2eDeps.scripts };
+    packageJson.devDependencies = { ...packageJson.devDependencies, ...e2eDeps.devDependencies };
+    
+    await writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
+    await rm(e2eDepsPath);
+  }
+
+  console.log('\nInstalling dependencies...');
+  await runCommand('npm', ['install'], projectPath);
+
+  console.log('\n✓ Success! Created', projectName, 'at', projectPath);
+  console.log('\nInside that directory, you can run several commands:\n');
+  console.log('  npm run dev');
+  console.log('    Starts the development server.\n');
+  console.log('  npm run build');
+  console.log('    Builds the app for production.\n');
+  console.log('  npm run preview');
+  console.log('    Previews the production build.\n');
+  console.log('  npm run lint');
+  console.log('    Runs the linter.\n');
+  
+  if (includeE2E) {
+    console.log('  npm run test:e2e');
+    console.log('    Runs E2E tests with Playwright.\n');
+    console.log('  npm run test:e2e:ui');
+    console.log('    Opens Playwright UI mode.\n');
+    console.log('  npm run test:e2e:report');
+    console.log('    Generates and opens Allure report.\n');
+  }
+  
+  console.log('We suggest that you begin by typing:\n');
+  console.log(`  cd ${projectName}`);
+  console.log('  npm run dev\n');
+}
+
+main().catch((error) => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});
+

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-react-adam",
+  "version": "0.1.0",
+  "description": "Create opinionated React apps with TypeScript, Vite, Wouter, and Tailwind CSS",
+  "type": "module",
+  "bin": {
+    "create-react-adam": "./bin/index.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+    "react",
+    "vite",
+    "typescript",
+    "wouter",
+    "tailwindcss",
+    "create-react-app",
+    "scaffolding"
+  ],
+  "author": "Adam",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adamjsturge/create-react-adam.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adamjsturge/create-react-adam/issues"
+  },
+  "homepage": "https://github.com/adamjsturge/create-react-adam#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "quick-make": "npm link && cd ./tmp && npx create-react-adam test-app-$(date +%Y%m%d-%H%M%S) --with-e2e --with-utils",
+    "qm": "npm run quick-make",
+    "itDoesNotWork": "echo 'Wrong Directory'",
+    "cleanup": "rm -rf ./tmp/* && rm -rf ./template/node_modules && rm -rf ./template/dist && rm -rf ./template/package-lock.json && echo 'Template Dev Files Deleted, you must run npm install in the template directory for those features'",
+    "dev": "npm run cleanup && TIMESTAMP=$(date +%Y%m%d-%H%M%S) && npm link && cd ./tmp && npx create-react-adam test-app-$TIMESTAMP --with-e2e --with-utils && cd test-app-$TIMESTAMP && npm run dev"
+  }
+}
+

package/template/.e2e-deps.json

@@ -0,0 +1,11 @@
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:report": "allure generate ./allure-results --clean && allure open"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.48.0",
+    "allure-playwright": "3.0.3"
+  }
+}

package/template/.github/renovate.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "packageRules": [
+    {
+      "matchManagers": ["npm"],
+      "groupName": "JavaScript Dependencies",
+      "groupSlug": "javascript-dependencies",
+      "schedule": ["at any time"]
+    },
+    {
+      "matchManagers": ["github-actions"],
+      "groupName": "GitHub Actions Dependencies",
+      "groupSlug": "github-actions-dependencies",
+      "schedule": ["at any time"]
+    },
+    {
+      "matchManagers": ["nvm"],
+      "groupName": "Node Version Manager Dependencies",
+      "groupSlug": "nvm-dependencies",
+      "schedule": ["at any time"]
+    }
+  ]
+}

package/template/.github/workflows/check.yml

@@ -0,0 +1,36 @@
+name: Template Code Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24.11.0"
+          cache: "npm"
+
+      - name: Install CLI dependencies
+        run: npm install
+
+      - name: Run TypeScript check
+        run: npx tsc --noEmit
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Run linting
+        run: npm run lint:check
+
+      - name: Run build
+        run: npm run build

package/template/.github/workflows/e2e.yml

@@ -0,0 +1,48 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24.11.0"
+          cache: "npm"
+
+      - name: Install CLI dependencies
+        run: npm install
+
+      - name: Install Playwright browsers
+        working-directory: ./e2e/
+        run: npx playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        working-directory: ./e2e/
+        run: npm run test:e2e
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: playwright-report
+          path: ./e2e/playwright-report/
+          retention-days: 30
+
+      - name: Upload Allure results
+        uses: actions/upload-artifact@v5
+        if: always()
+        with:
+          name: allure-results
+          path: ./e2e/allure-results/
+          retention-days: 30

package/template/.nvmrc

@@ -0,0 +1,2 @@
+24.11.0
+

package/template/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "plugins": ["prettier-plugin-organize-imports", "prettier-plugin-tailwindcss"]
+}

package/template/README.md

@@ -0,0 +1,83 @@
+# **PROJECT_NAME**
+
+A React application created with create-react-adam.
+
+## Getting Started
+
+```bash
+npm run dev
+```
+
+This will start the development server at `http://localhost:5173`.
+
+## Available Scripts
+
+### `npm run itDoesNotWork`
+
+Runs basic troubleshooting checks:
+
+- Installs dependencies
+- Checks if Vite dev server is running
+- Provides helpful diagnostic information
+
+### `npm run dev`
+
+Starts the development server with hot module replacement.
+
+### `npm run build`
+
+Builds the app for production. The build artifacts will be stored in the `dist/` directory.
+
+### `npm run preview`
+
+Previews the production build locally.
+
+### `npm run lint`
+
+Runs ESLint to check for code quality issues.
+
+### `npm run format`
+
+Formats all files with Prettier, organizing imports and sorting Tailwind classes.
+
+## Tech Stack
+
+- **React** - UI library
+- **TypeScript** - Type safety
+- **Vite** - Build tool and dev server
+- **Wouter** - Lightweight routing
+- **Tailwind CSS** - Utility-first CSS framework
+- **ESLint & Prettier** - Code quality and formatting
+
+## Project Structure
+
+```
+src/
+  ├── pages/          # Page components
+  │   ├── Home/index.tsx
+  │   └── About/index.tsx
+  ├── App.tsx         # Main app with routes
+  ├── main.tsx        # Entry point
+  └── app.css         # Global styles (Tailwind imports)
+```
+
+## Adding New Pages
+
+1. Create a new component in `src/pages/`
+2. Import and add a route in `src/App.tsx`
+
+Example:
+
+```tsx
+import NewPage from "./pages/NewPage";
+
+// In the Switch component:
+<Route path="/new" component={NewPage} />;
+```
+
+## Learn More
+
+- [React Documentation](https://react.dev)
+- [Vite Documentation](https://vitejs.dev)
+- [Wouter Documentation](https://github.com/molefrog/wouter)
+- [Tailwind CSS Documentation](https://tailwindcss.com)