Adding a New Framework

Complete guide to integrating a new React framework (e.g., Rsbuild, Parcel, esbuild) into React Kickstart. Use Vite and Next.js as reference implementations.

Before You Start: Familiarize yourself with the existing Vite and Next.js implementations in src/generators/frameworks/ to understand the patterns and conventions.

🎯 Overview

Adding a new framework involves several integration points across the React Kickstart codebase. This guide provides a comprehensive checklist to ensure your framework is fully integrated.

Key Integration Points:

Generator implementation
Dependency management
Configuration generation
Prompt system integration
Quality assurance testing

📋 Complete Integration Checklist

Create Framework Generator

Location: src/generators/frameworks/<your-framework>/

Create your-framework-generator.js that extends BaseGenerator and implements:

class YourFrameworkGenerator extends BaseGenerator {
  async createPackageConfiguration(projectPath, projectName, userChoices) {
    // Create package.json with framework-specific dependencies and scripts
  }
 
  async createFrameworkConfiguration(projectPath, userChoices) {
    // Create framework-specific config files (e.g., webpack.config.js, rollup.config.js)
  }
 
  async createProjectFiles(projectPath, projectName, userChoices) {
    // Create core project files (HTML entry, source files)
  }
 
  async createFrameworkSpecificFiles(projectPath, userChoices) {
    // Create framework-specific files and directory structure
  }
}

Framework-Specific Considerations:

HTML Entry: If your framework needs an HTML entry (like Vite), call createHtmlFile() and createSourceFiles()
Internal Routing: If it manages routing internally (like Next.js), skip HTML and rely on createSourceFiles() with framework-specific variations

Register Framework for Selection

File: src/generators/index.js

Add a case for your new framework in the generator selection switch:

function selectGenerator(framework) {
  switch (framework) {
    case "vite":
      return new ViteGenerator();
    case "nextjs":
      return new NextjsGenerator();
    case "your-framework":
      return new YourFrameworkGenerator();
    default:
      throw new Error(`Unsupported framework: ${framework}`);
  }
}

Add to Prompt Flow

File: src/prompts/steps/framework-step.js

Add your framework as a selectable option:

getChoices() {
  return [
    {
      name: 'Vite (Fast development with instant HMR)',
      value: 'vite'
    },
    {
      name: 'Next.js (Full-stack React framework)',
      value: 'nextjs'
    },
    {
      name: 'Your Framework (Description of benefits)',
      value: 'your-framework'
    }
  ]
}

Special Sub-Options: If your framework has special sub-options (like Next.js app/pages router), add a new step and wire it in src/prompts/prompt-flow.js and FrameworkStep.getNextStep().

Configure Dependencies and Scripts

Files to Update:

src/builders/dependencies.js

Extend the frameworks object with your framework's packages and versions:

export const frameworks = {
  vite: {
    '@vitejs/plugin-react': '^4.0.0',
    'vite': '^4.4.0'
  },
  nextjs: {
    'next': '^14.0.0'
  },
  'your-framework': {
    'your-framework': '^1.0.0',
    'your-framework-plugin-react': '^1.0.0'
  }
}

Generate Framework Configuration

File: src/builders/configuration-builder.js

Add a case to generateFrameworkConfig() for your framework:

async generateFrameworkConfig(projectPath, framework, userChoices) {
  switch (framework) {
    case 'vite':
      await this.generateViteConfig(projectPath, userChoices)
      break
    case 'nextjs':
      await this.generateNextConfig(projectPath, userChoices)
      break
    case 'your-framework':
      await this.generateYourFrameworkConfig(projectPath, userChoices)
      break
  }
}
 
async generateYourFrameworkConfig(projectPath, userChoices) {
  const config = {
    // Your framework-specific configuration
    entry: './src/index.tsx',
    output: {
      path: path.resolve(projectPath, 'build'),
      filename: 'bundle.js'
    },
    // Add React plugin, TypeScript support, etc.
  }
 
  const configPath = path.join(projectPath, 'your-framework.config.js')
  await CORE_UTILS.writeFile(configPath, `module.exports = ${JSON.stringify(config, null, 2)}`)
}

Handle Source and HTML Files

File: src/features/source-files/file-generator.js

Update createSourceFiles() and createHtmlFile() to handle your framework:

createSourceFiles(projectPath, framework, userChoices) {
  // Handle framework-specific entry filename or directory layout
  if (framework === 'your-framework') {
    const entryFile = userChoices.typescript ? 'index.tsx' : 'index.jsx'
    // Create framework-specific entry point
  }
 
  // ... existing logic
}

Content Generation

File: src/templates/frameworks/index.js

Add content generation strategy for your framework:

function createContentGenerator(framework, routingType) {
  switch (framework) {
    case "vite":
      return new ViteContentGenerator();
    case "nextjs":
      return routingType === "app"
        ? new NextjsAppRouterGenerator()
        : new NextjsPagesRouterGenerator();
    case "your-framework":
      return new YourFrameworkContentGenerator();
    default:
      throw new Error(`Unsupported framework: ${framework}`);
  }
}

Framework-Specific Features

Update feature modules to handle your framework:

src/features/routing/index.js

Add routing setup for your framework:

async setupRouting(projectPath, framework, userChoices) {
  if (framework === 'your-framework' && userChoices.routing === 'your-router') {
    await this.setupYourFrameworkRouting(projectPath, userChoices)
  }
  // ... existing logic
}

Project Information and Documentation

Files to Update:

// src/utils/core/project-analysis.js
getFrameworkInfo(framework) {
  switch (framework) {
    case 'your-framework':
      return {
        name: 'Your Framework',
        defaultPort: 8080,
        buildDir: 'build',
        docsUrl: 'https://your-framework.dev'
      }
    // ... other cases
  }
}
 
// src/utils/ui/completion.js
getFrameworkDocumentation(framework) {
  switch (framework) {
    case 'your-framework':
      return {
        docs: 'https://your-framework.dev/docs',
        defaultPort: 8080,
        buildDir: 'build'
      }
    // ... other cases
  }
}

Quality Assurance Integration

File: qa-automation/test-matrix-generator.js

Add your framework to the test matrix:

const CONFIG_OPTIONS = {
  framework: ["vite", "nextjs", "your-framework"],
  typescript: [true, false],
  styling: ["tailwind", "styled-components", "css"],
  // ... other options
};
 
// Add framework-specific conditional options if needed
const CONDITIONAL_OPTIONS = {
  "your-framework": {
    routing: ["your-router", "none"],
    // Framework-specific options
  },
};

Run Quality Assurance Tests

Validate your framework integration:

# Generate test matrix including your framework
node qa-automation/test-matrix-generator.js
 
# Run critical tests
node qa-automation/test-runner.js critical 10
 
# Run standard tests
node qa-automation/test-runner.js standard 25
 
# Run edge case tests
node qa-automation/test-runner.js edge 15

⚠️

Critical: Ensure all tests pass before submitting your framework integration. Fix any failures to maintain React Kickstart's reliability.

🧪 Testing Your Integration

Manual Testing

Test your framework with different combinations:

# Basic test
node bin/react-kickstart.js test-app --yes --framework your-framework
 
# With TypeScript
node bin/react-kickstart.js test-app --yes --framework your-framework --typescript
 
# Full-featured test
node bin/react-kickstart.js test-app --yes --framework your-framework --typescript --styling tailwind --state redux --testing vitest

Automated Testing

Run the QA automation suite:

# Generate comprehensive test matrix
node qa-automation/test-matrix-generator.js
 
# Run all test suites
npm run qa:critical
npm run qa:standard
npm run qa:edge

Validation Checklist

Verify your integration:

Project generates successfully
Dependencies install correctly
Build process works (npm run build)
Development server starts (npm run dev)
All selected features integrate properly
TypeScript support works (if enabled)
Testing framework runs (if enabled)
Linting and formatting work
Deployment configuration is correct

🎯 Framework-Specific Considerations

Build Tool Integration

Different frameworks have different build tool requirements:

Webpack-based frameworks (Create React App, custom Webpack): - Create webpack.config.js - Handle loaders for TypeScript, CSS, assets - Configure dev server settings - Set up hot module replacement

TypeScript Integration

Ensure proper TypeScript support:

// In your generator
if (userChoices.typescript) {
  // Create tsconfig.json
  await configBuilder.generateTypeScriptConfig(projectPath, userChoices);
 
  // Add TypeScript dependencies
  const tsDeps = this.getTypeScriptDependencies(framework);
  // Handle framework-specific TypeScript setup
}

Testing Framework Compatibility

Consider testing framework compatibility:

Vitest: Works well with Vite-like build tools
Jest: May need additional configuration for modern frameworks
Framework-specific: Some frameworks have their own testing solutions

🚀 Best Practices

Follow Existing Patterns: Study the Vite and Next.js implementations to understand established patterns and conventions.

Code Organization

Consistent Structure: Follow the same directory structure as existing frameworks
Clear Separation: Keep framework-specific code in dedicated modules
Reusable Components: Leverage existing builders and utilities where possible

Error Handling

Graceful Failures: Provide clear error messages for framework-specific issues
Cleanup: Ensure partial project cleanup on generation failure
Validation: Validate framework-specific requirements before generation

Documentation

Update README: Add your framework to the main project README
Code Comments: Document framework-specific logic and decisions
Examples: Provide usage examples in the CLI reference

📚 Next Steps

After Integration:

Submit Pull Request - Follow the Contributing Guide
Update Documentation - Add framework-specific documentation
Community Feedback - Gather feedback from early users
Iterate and Improve - Refine based on real-world usage

Related Guides:

Adding Features → - Add new capabilities to existing frameworks
Architecture Overview → - Understand the overall system design
Contributing → - Contribution guidelines and workflow

Ready to Contribute? Your framework integration will help expand React Kickstart's capabilities and serve the broader React community!

Extension Overview Adding Styling Options