gh-cskiro-claudex-devops-tools/skills/react-project-scaffolder/modes/enterprise-mode.md

Enterprise Mode - Next.js + Full Tooling

Mode Overview

Purpose: Production-ready web applications with comprehensive tooling and testing

Target Users:

• Building SaaS products
• Enterprise dashboards and admin panels
• Content-heavy websites with SEO needs
• Applications requiring server-side rendering
• Teams needing consistent standards

Setup Time: ~60 seconds (after npm install)

Philosophy: Production-ready from day one. Industry-standard tooling with Connor's quality standards built in.

---

Tech Stack

Framework:
  - Next.js 14+ (App Router, React Server Components)
  - React 18+
  - TypeScript 5+ (strict mode)

Testing:
  - Vitest (Testing Trophy approach)
  - React Testing Library
  - jsdom (DOM simulation)
  - 80% coverage threshold

Code Quality:
  - ESLint (Next.js config + strict rules)
  - Prettier (consistent formatting)
  - Husky (pre-commit hooks)
  - lint-staged (staged files only)

CI/CD:
  - GitHub Actions
  - Automated testing on PR
  - Build validation
  - Type checking

Standards:
  - Conventional Commits
  - Branch naming conventions
  - Comprehensive documentation

---

Workflow

Step 1: Validate Prerequisites

# Check Node.js version (>= 18)
node --version

# Check npm version (>= 9)
npm --version

# Check git is installed
git --version

If validation fails: Provide clear upgrade instructions with links

Step 2: Ask Configuration Questions

Only ask essential questions with smart defaults:

Question 1: Project Name

• "What should I name your project?"
• Validation: kebab-case, 3-50 chars, no existing directory
• Example: my-awesome-app

Question 2: Testing Setup

• "Include testing infrastructure? (Vitest + React Testing Library)"
• Default: YES
• Explain: "Recommended for production apps. Adds ~30s to setup."

Question 3: CI/CD Workflows

• "Include GitHub Actions CI/CD?"
• Default: YES
• Explain: "Automated testing on every PR. Requires GitHub repository."

Question 4: Source Directory

• "Use src/ directory for better organization?"
• Default: YES
• Explain: "Keeps root clean. Next.js best practice."

Step 3: Scaffold with Next.js

npx create-next-app@latest {project-name} \
  --typescript \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*" \
  --no-tailwind

cd {project-name}

Why these flags?

• --typescript: Connor requires TypeScript
• --eslint: Linting from start
• --app: Use App Router (modern approach)
• --src-dir: Clean project structure
• --import-alias: Absolute imports with @/
• --no-tailwind: Let user choose styling (can add later)

Step 4: Apply Connor's TypeScript Standards

Update tsconfig.json:

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    },

    /* Connor's Strict Mode Additions */
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noImplicitOverride": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Step 5: Set Up Testing (if selected)

5.1 Install Dependencies

npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event @vitest/coverage-v8

5.2 Create vitest.config.ts

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: './src/__tests__/setup.ts',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'src/__tests__/',
        '**/*.config.ts',
        '**/*.config.js',
        '.next/',
      ],
      // Connor's 80% threshold
      lines: 80,
      functions: 80,
      branches: 80,
      statements: 80,
    },
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

5.3 Create Test Setup File

src/__tests__/setup.ts:

import '@testing-library/jest-dom';
import { cleanup } from '@testing-library/react';
import { afterEach } from 'vitest';

// Cleanup after each test
afterEach(() => {
  cleanup();
});

5.4 Create Example Test

src/__tests__/page.test.tsx:

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import Page from '@/app/page';

describe('Home Page', () => {
  it('should render welcome message when page loads', () => {
    render(<Page />);

    // Testing Trophy approach: Test user-visible behavior
    const heading = screen.getByRole('heading', { level: 1 });
    expect(heading).toBeInTheDocument();
  });

  it('should have semantic HTML structure for accessibility', () => {
    const { container } = render(<Page />);

    // Check for main landmark
    const main = container.querySelector('main');
    expect(main).toBeInTheDocument();
  });
});

5.5 Update package.json Scripts

Add to scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit",
    "test": "vitest --run",
    "test:watch": "vitest",
    "test:coverage": "vitest --coverage",
    "test:low": "vitest --maxWorkers=2 --run",
    "test:ui": "vitest --ui"
  }
}

Step 6: Configure Code Quality Tools

6.1 Extend ESLint Configuration

Update .eslintrc.json:

{
  "extends": [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "no-console": "warn",
    "no-var": "error",
    "eqeqeq": ["error", "always"],
    "prefer-const": "error",
    "@typescript-eslint/no-unused-vars": [
      "error",
      { "argsIgnorePattern": "^_" }
    ],
    "@typescript-eslint/no-explicit-any": "error"
  }
}

6.2 Add Prettier

Create .prettierrc:

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false
}

Create .prettierignore:

node_modules
.next
out
build
dist
coverage
*.lock

Install Prettier:

npm install -D prettier eslint-config-prettier

Update .eslintrc.json to include Prettier:

{
  "extends": [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ]
}

6.3 Set Up Husky + lint-staged

npx husky-init && npm install
npm install -D lint-staged

Update .husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

Create .lintstagedrc.js:

module.exports = {
  '*.{ts,tsx}': [
    'eslint --fix',
    'prettier --write',
    () => 'tsc --noEmit', // Type check
  ],
  '*.{json,md}': ['prettier --write'],
};

Update package.json:

{
  "scripts": {
    "prepare": "husky install"
  }
}

Step 7: Set Up CI/CD (if selected)

Create .github/workflows/ci.yml:

name: CI

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x]

    steps:
      - uses: actions/checkout@v4

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Type check
        run: npm run type-check

      - name: Run tests
        run: npm run test:coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        if: matrix.node-version == '20.x'
        with:
          file: ./coverage/coverage-final.json
          flags: unittests

      - name: Build project
        run: npm run build
        env:
          NODE_ENV: production

Step 8: Create Project Documentation

8.1 Update README.md

# {project-name}

Production-ready Next.js application with comprehensive testing and tooling.

## Features

- ⚡ Next.js 14+ with App Router
- 🔷 TypeScript (strict mode)
- 🧪 Testing Trophy approach (Vitest + RTL)
- ✅ 80% test coverage threshold
- 🎨 ESLint + Prettier
- 🪝 Husky pre-commit hooks
- 🔄 GitHub Actions CI/CD
- 📝 Conventional Commits

## Getting Started

### Prerequisites

- Node.js 18+
- npm 9+

### Installation

\`\`\`bash
npm install
\`\`\`

### Development

\`\`\`bash
npm run dev
\`\`\`

Visit [http://localhost:3000](http://localhost:3000)

## Project Structure

\`\`\`
src/
├── app/                    # Next.js App Router
│   ├── page.tsx            # Home page
│   ├── layout.tsx          # Root layout
│   └── globals.css         # Global styles
├── components/             # React components
│   ├── ui/                 # UI components
│   └── features/           # Feature components
├── lib/                    # Utility functions
│   └── utils.ts
└── __tests__/              # Test files
    ├── setup.ts            # Test configuration
    └── page.test.tsx       # Example test
\`\`\`

## Available Commands

### Development
- \`npm run dev\` - Start dev server (http://localhost:3000)
- \`npm run build\` - Build for production
- \`npm run start\` - Start production server

### Code Quality
- \`npm run lint\` - Lint code with ESLint
- \`npm run type-check\` - Check TypeScript types

### Testing
- \`npm run test\` - Run all tests
- \`npm run test:watch\` - Run tests in watch mode
- \`npm run test:coverage\` - Run tests with coverage report
- \`npm run test:low\` - Run tests (low CPU usage)

## Testing Strategy

This project follows the **Testing Trophy** approach:

- **70% Integration Tests**: User workflows and component interactions
- **20% Unit Tests**: Complex business logic
- **10% E2E Tests**: Critical user journeys

### Writing Tests

Test file naming: \`[component-name].test.tsx\`

Test structure:
\`\`\`typescript
describe('Component Name', () => {
  it('should [behavior] when [condition]', () => {
    // Arrange, Act, Assert
  });
});
\`\`\`

Use semantic queries (React Testing Library):
1. \`getByRole()\` - Most preferred
2. \`getByLabelText()\` - Form elements
3. \`getByText()\` - User-visible content
4. \`getByTestId()\` - Last resort only

### Coverage Requirements

Minimum 80% coverage for:
- Lines
- Functions
- Branches
- Statements

## Git Workflow

### Branch Naming

- \`feature/description\` - New features
- \`bugfix/description\` - Bug fixes
- \`chore/description\` - Maintenance tasks

### Commit Messages

Follow [Conventional Commits](https://www.conventionalcommits.org/):

\`\`\`
feat: add user authentication
fix: resolve login redirect issue
test: add tests for auth flow
docs: update API documentation
chore: update dependencies
\`\`\`

### Pre-commit Checks

Husky automatically runs before each commit:
- ESLint (auto-fix enabled)
- Prettier (auto-format)
- TypeScript type checking
- Staged files only (fast)

## Deployment

### Vercel (Recommended)

\`\`\`bash
npm install -g vercel
vercel
\`\`\`

### Docker

\`\`\`bash
docker build -t {project-name} .
docker run -p 3000:3000 {project-name}
\`\`\`

## Environment Variables

Create \`.env.local\`:

\`\`\`env
# Example variables
NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://...
\`\`\`

## CI/CD

GitHub Actions runs on every PR:
1. Install dependencies
2. Lint code
3. Type check
4. Run tests with coverage
5. Build project

## Tech Stack Details

### Why Next.js?
- Server-side rendering for SEO
- API routes for backend logic
- Optimized image handling
- Industry standard (Netflix, TikTok)

### Why Vitest?
- 10x faster than Jest
- Compatible with Vite
- Great TypeScript support
- Modern testing features

## Contributing

1. Create a feature branch
2. Make changes with tests
3. Ensure all checks pass
4. Submit PR with description

## License

MIT

---

Built with [react-project-scaffolder](https://github.com/yourusername/react-project-scaffolder)

8.2 Create CONTRIBUTING.md

# Contributing Guidelines

## Development Standards

### Code Quality
- TypeScript strict mode (all flags enabled)
- No \`console.log\` in production code
- No \`any\` types
- Explicit return types for functions

### Testing
- Write tests for new features
- Maintain 80% coverage minimum
- Follow Testing Trophy approach
- Use semantic queries in tests

### Commits
- Follow Conventional Commits format
- Keep commits atomic and focused
- Write descriptive commit messages

## Development Workflow

1. **Create branch**: \`git checkout -b feature/your-feature\`
2. **Make changes**: Edit code + add tests
3. **Run checks**: \`npm run lint && npm run test\`
4. **Commit**: \`git commit -m "feat: your feature"\`
5. **Push**: \`git push origin feature/your-feature\`
6. **Create PR**: Submit for review

## Pre-commit Checks

Husky runs these automatically:
- ESLint (fixes issues automatically)
- Prettier (formats code)
- TypeScript (type checking)

If checks fail, fix issues before committing.

## Testing Guidelines

### What to Test
- User-visible behavior
- Business logic
- Error handling
- Edge cases

### What NOT to Test
- Implementation details
- External libraries
- Trivial functions

### Example Test

\`\`\`typescript
import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

describe('LoginForm', () => {
  it('should submit form when user enters valid credentials', async () => {
    const user = userEvent.setup();
    const onSubmit = vi.fn();

    render(<LoginForm onSubmit={onSubmit} />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /submit/i }));

    expect(onSubmit).toHaveBeenCalledWith({
      email: 'test@example.com',
      password: 'password123',
    });
  });
});
\`\`\`

## Questions?

Open an issue or reach out to the maintainers.

Step 9: Initialize Git

git init
git add .
git commit -m "feat: initial Next.js enterprise setup with testing and CI/CD

- Next.js 14 with App Router
- TypeScript strict mode
- Vitest + React Testing Library (80% coverage)
- ESLint + Prettier + Husky
- GitHub Actions CI/CD
- Comprehensive documentation"

Step 10: Verify Setup

# Verify all files
ls -la

# Check dependencies installed
npm list --depth=0

# Verify TypeScript config
cat tsconfig.json | grep "strict"

# Verify tests can run
npm run test

# Verify build works
npm run build

Step 11: Provide User Instructions

Display to user:

✅ Enterprise project "{project-name}" created successfully!

📁 Location: ./{project-name}

🚀 Next steps:

  1. cd {project-name}
  2. npm install
  3. npm run dev

Your dev server will start at http://localhost:3000

📚 What you have:
  ✓ Next.js 14 with App Router
  ✓ TypeScript strict mode
  ✓ Vitest + React Testing Library (80% coverage)
  ✓ ESLint + Prettier + Husky
  ✓ GitHub Actions CI/CD
  ✓ Testing Trophy approach
  ✓ Comprehensive documentation

🧪 Test your setup:
  npm run test           # Run all tests
  npm run lint           # Check code quality
  npm run type-check     # Verify types

📋 Pre-commit hooks active:
  - Linting (auto-fix)
  - Formatting (auto-format)
  - Type checking

🔄 CI/CD ready:
  - Push to GitHub to activate workflows
  - Automated testing on every PR

💡 Tips:
  - Follow Testing Trophy: 70% integration, 20% unit, 10% e2e
  - Use semantic queries: getByRole() > getByLabelText() > getByText()
  - Write tests alongside features (TDD approach)
  - Keep commits following Conventional Commits format

📖 Documentation:
  - README.md - Project overview and commands
  - CONTRIBUTING.md - Development guidelines

🎯 Production-ready from day one!

---

File Structure Output

{project-name}/
├── .github/
│   └── workflows/
│       └── ci.yml              # GitHub Actions CI/CD
├── .husky/
│   └── pre-commit              # Pre-commit hooks
├── .vscode/ (optional)
│   └── settings.json           # Editor config
├── src/
│   ├── app/
│   │   ├── page.tsx            # Home page
│   │   ├── layout.tsx          # Root layout
│   │   ├── globals.css         # Global styles
│   │   └── favicon.ico         # Favicon
│   ├── components/
│   │   ├── ui/                 # UI components
│   │   └── features/           # Feature components
│   ├── lib/
│   │   └── utils.ts            # Utilities
│   └── __tests__/
│       ├── setup.ts            # Test setup
│       └── page.test.tsx       # Example test
├── public/                     # Static files
├── .eslintrc.json              # ESLint config
├── .prettierrc                 # Prettier config
├── .prettierignore             # Prettier ignore
├── .gitignore                  # Git ignore
├── .lintstagedrc.js            # lint-staged config
├── vitest.config.ts            # Vitest config
├── tsconfig.json               # TypeScript config
├── next.config.js              # Next.js config
├── package.json                # Dependencies
├── README.md                   # Documentation
└── CONTRIBUTING.md             # Guidelines

---

Success Criteria

• Next.js project scaffolded with App Router
• TypeScript strict mode enabled (all flags)
• Vitest + RTL configured with 80% threshold
• Example test passes
• ESLint + Prettier configured
• Husky pre-commit hooks working
• GitHub Actions workflow created
• README and CONTRIBUTING.md generated
• Git initialized with commit
• npm run dev starts successfully
• npm run test passes
• npm run build completes
• Setup time < 90 seconds (excluding npm install)

---

Troubleshooting

Issue: Husky pre-commit hook fails Solution: Run npm run lint -- --fix to auto-fix issues

Issue: Tests fail with module resolution errors Solution: Check vitest.config.ts has correct path aliases

Issue: Type errors in strict mode Solution: This shouldn't happen - review generated code

Issue: Build fails Solution: Run npm run type-check to see TypeScript errors

Issue: Coverage below 80% Solution: Add more tests or adjust threshold temporarily

---

Why This Tech Stack?

Next.js over Vite:

• Server-side rendering for SEO
• Built-in routing
• API routes for backend
• Image optimization
• Battle-tested at scale (Netflix, Uber)

Vitest over Jest:

• 10x faster test execution
• Better TypeScript support
• Modern ESM support
• Compatible with Vite ecosystem

Husky + lint-staged:

• Catch issues before commit
• Fast (only staged files)
• Team consistency
• Industry standard

GitHub Actions:

• Free for public repos
• Integrated with GitHub
• Easy to configure
• Extensive marketplace

---

Remember: This mode is production-ready. Every tool included is standard in industry and aligned with Connor's "production-ready from day one" philosophy.