StackFast Full-Stack Builder

A Full-Stack JavaScript Tech Stack Builder that helps developers select compatible tools for building modern web applications with intelligent recommendations and real-time validation.

Features

• 🎯 Smart Tool Selection: Choose from curated categories of modern JavaScript tools
• ⚡ Real-Time Validation: Instant compatibility checking with explainable scoring
• 💡 Intelligent Suggestions: Context-aware recommendations based on your selections
• 📦 Recipe-Based Export: Generate working project configurations with proper setup guides
• 🎨 Clean UI: Built with React, TypeScript, and Tailwind CSS
• ♿ Accessible: WCAG 2.1 AA compliant with keyboard navigation

Tech Stack

• Frontend: React 18 + TypeScript
• Build Tool: Vite
• Styling: Tailwind CSS + shadcn/ui
• State Management: React Context API
• Performance: Web Workers for rules evaluation
• Testing: Vitest + React Testing Library
• Validation: Zod

Getting Started

Prerequisites

• Node.js 18+ or Bun
• npm, yarn, or pnpm

Installation

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Start development server
npm run dev

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm test - Run tests once
• npm run test:watch - Run tests in watch mode
• npm run type-check - Check TypeScript types
• npm run lint - Lint code

Project Structure

stackfast-full-stack-builder/
├── src/
│   ├── components/        # React UI components
│   ├── engine/           # Rules engine, suggestion engine, export generator
│   ├── data/             # TypeScript modules (recipes, suggestions)
│   ├── templates/        # Export templates
│   ├── context/          # React Context providers
│   ├── hooks/            # Custom React hooks
│   ├── lib/              # Utility functions
│   └── types/            # TypeScript type definitions
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   ├── snapshots/        # Snapshot tests
│   └── performance/      # Performance benchmarks
├── public/
│   └── catalog/          # Static catalog data (JSON)
└── package.json

Architecture

StackFast is a client-side only application with no backend dependencies:

• Data-Driven: All compatibility rules and tool metadata are defined in JSON
• Web Workers: Performance-critical rule evaluation runs in a Web Worker
• Local Storage: User selections persist in browser localStorage
• Static Catalog: Tool catalog is versioned and cached for offline use

How It Works

1. Tool Selection

• Choose from 10 categories: Frontend, Runtime, Hosting, Database, ORM, Auth, Payments, Email, Storage, Styling
• Each category has cardinality rules (exactly-one, at-most-one, zero-or-one)
• UI prevents invalid selections at the interaction layer

2. Compatibility Checking

• Rules engine evaluates 30+ compatibility rules in real-time
• Scoring algorithm: Base 50, +40 max bonus, -70 max penalty, clamped to [0-100]
• Rule types: conflicts, synergies, requirements, capability compatibility, category coverage
• All diagnostics include rule provenance (ruleId, ruleVersion)

3. Smart Suggestions

• Context-aware recommendations based on current selections
• Priority levels: High, Medium, Low
• Examples: Frontend → Database, Database → ORM, Next.js → Vercel

4. Export Generation

• Recipe-based system generates working project configurations
• Outputs: package.json, .env.example, README.md, config files, export-log.json
• Deterministic recipe ordering ensures consistent results
• Includes setup instructions and caveats for warnings

Development

Adding New Tools

1. Update Tool Catalog (public/catalog/v1/tools.json):

{
  "id": "my-tool",
  "name": "My Tool",
  "categoryId": "database",
  "description": "A great database",
  "languages": ["javascript", "typescript"],
  "supports": {
    "runtime": ["node", "bun"]
  },
  "integrations": ["prisma", "drizzle"],
  "pricing": {
    "model": "free-tier",
    "note": "Free up to 1GB",
    "lastVerified": "2024-01-15"
  },
  "docsUrl": "https://example.com/docs"
}

2. Add Compatibility Rules (public/catalog/v1/rules.json):

{
  "id": "my-tool-synergy",
  "version": "1.0.0",
  "kind": "synergy",
  "toolA": "my-tool",
  "toolB": "prisma",
  "reason": "First-class integration with Prisma",
  "weight": 8
}

3. Create Export Recipe (src/data/recipes/my-tool.ts):

import type { ExportRecipe } from '@/types';

export const myToolRecipe: ExportRecipe = {
  id: 'my-tool',
  version: '1.0.0',
  appliesWhen: (tools) => tools.some(t => t.id === 'my-tool'),
  targets: {
    packageJson: {
      deps: { 'my-tool': '^1.0.0' },
      devDeps: {},
      scripts: { 'db:start': 'my-tool start' },
    },
    files: [
      {
        path: 'my-tool.config.js',
        templateId: 'my-tool-config',
        mergeStrategy: 'create',
      },
    ],
    env: {
      example: {
        MY_TOOL_URL: 'postgresql://localhost:5432/mydb',
      },
    },
    postInstallSteps: [
      'Run `npm run db:start` to start the database',
    ],
  },
};

4. Register Recipe (src/data/recipes/index.ts):

import { myToolRecipe } from './my-tool';

export const recipes = [
  // ... existing recipes
  myToolRecipe,
];

Updating the Catalog

The catalog is versioned and cached for 24 hours. To update:

1. Modify files in public/catalog/v1/
2. Update manifest.json with new updatedAt timestamp
3. Users can click "Refresh Catalog" to clear cache and reload

Running Tests

# Run all tests
npm test

# Run specific test file
npm test -- rules-engine.test.ts

# Run with coverage
npm test -- --coverage

# Run in watch mode during development
npm run test:watch

Performance Benchmarks

# Run performance tests
npm test -- performance/benchmarks.test.ts

Expected targets:

• Rule evaluation: <50ms (laptop), <100ms (mobile)
• Export generation: <200ms
• Bundle size: <500KB gzipped

Accessibility Testing

# Run accessibility tests
npm test -- integration/user-flows.test.tsx

Manual testing:

• Keyboard navigation (Tab, Enter, Escape)
• Screen reader (NVDA, JAWS, VoiceOver)
• High contrast mode
• Zoom to 200%

Deployment

See DEPLOYMENT.md for detailed deployment instructions.

Quick deploy to Vercel:

npm install -g vercel
vercel --prod

Architecture Decisions

Why Client-Side Only?

• No backend maintenance or costs
• Instant deployment to static hosting
• Works offline after initial load
• Privacy-first (no data leaves browser)

Why Web Workers?

• Keeps UI responsive during rule evaluation
• Handles 40+ tools without blocking main thread
• Graceful fallback to main thread if unavailable

Why TypeScript Recipes?

• Type-safe recipe definitions
• Function-based appliesWhen logic for flexibility
• Easy to test and maintain
• May migrate to JSON with DSL post-MVP

Why Zod?

• Runtime validation of catalog data
• Type inference for TypeScript
• Clear error messages for invalid data

Troubleshooting

Build Errors

Error: Cannot find module '@/components/...'

• Solution: Check tsconfig.json has correct path aliases

Error: Worker is not defined

• Solution: Ensure typeof window !== 'undefined' guards are in place

Runtime Errors

Error: Catalog fails to load

• Solution: Check public/catalog/v1/manifest.json exists and is valid
• Solution: Clear browser cache and localStorage

Error: Export fails with "No recipes found"

• Solution: Ensure selected tools have corresponding recipes
• Solution: Check recipe appliesWhen logic

Performance Issues

Slow rule evaluation

• Check if Web Worker is loading (should see worker file in Network tab)
• Verify no excessive re-renders with React DevTools
• Profile with Chrome DevTools Performance tab

Contributing

We welcome contributions! Please follow these guidelines:

1. Code Style: Follow TypeScript strict mode and ESLint rules
2. Testing: Add tests for new features (unit + integration)
3. Accessibility: Ensure WCAG 2.1 AA compliance
4. Documentation: Update README and inline comments
5. Standards: See .kiro/steering/stackfast-standards.md for detailed guidelines

Contribution Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Run type check (npm run type-check)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Roadmap

• Add more tools and categories
• Migrate recipes to JSON with declarative DSL
• Add stack presets (e.g., "E-commerce", "SaaS")
• Add global undo/redo
• Add dark mode
• Add internationalization (i18n)
• Add analytics dashboard for popular stacks
• Add community-contributed recipes

FAQ

Q: Can I use this for production projects? A: Yes! The exported configurations are production-ready with proper setup instructions.

Q: How often is the catalog updated? A: The catalog is versioned and can be updated independently of the app. Check the header for the last update date.

Q: Can I add my own tools? A: Yes! Fork the repo and add your tools to the catalog. See "Adding New Tools" above.

Q: Does this work offline? A: Yes, after the initial load. The catalog is cached in localStorage for 24 hours.

Q: Is my data private? A: Yes! All data stays in your browser. No selections or exports are sent to any server.

Q: Can I export to other formats besides ZIP? A: Currently only ZIP is supported. TAR support is planned for a future release.

License

MIT License - see LICENSE for details

Acknowledgments

• Built with React
• UI components from shadcn/ui
• Icons from Lucide
• Validation with Zod

Support

• 📖 Documentation
• 🐛 Report Bug
• 💡 Request Feature
• 💬 Discussions