🏰 Boilerbuilder

A Boilerbuilder, to boilerbuild aesthetics projects! 💪

📜 Overview

Welcome to Boilerbuilder, your go-to CLI tool for creating, managing, and maintaining modern frontend projects with ease! Boilerbuilder streamlines the development workflow by providing a comprehensive set of commands to scaffold new projects, migrate existing ones, and keep dependencies up-to-date using curated templates from the cloud.

Built with developer productivity in mind, Boilerbuilder eliminates the repetitive setup tasks and ensures consistency across your projects by leveraging a centralized template system hosted on GitHub.

✨ Key Features

• 🏗️ Project Scaffolding: Create new projects instantly from curated templates
• 🔄 Smart Migration: Migrate existing projects to updated templates while preserving your code
• 📦 Dependency Management: Keep your project dependencies synchronized with template standards
• 🌐 Cloud-Based Templates: Access templates dynamically from GitHub repository
• 🎯 Interactive CLI: User-friendly prompts for seamless project configuration
• 🔧 Flexible Architecture: Modular design supporting multiple project types
• 💾 Backup System: Automatic backup creation during migration processes

🏗️ Architecture

Boilerbuilder is organized into a clean, modular structure with enhanced reliability and maintainability:

boilerbuilder/
├── src/                      # ✨ Refactored implementation
│   ├── index.js              # CLI entry point with Commander.js
│   ├── config/               # Configuration and validation
│   │   ├── constants.js      # Centralized constants and messages
│   │   └── validation.js     # Input validation schemas
│   ├── commands/             # Command implementations
│   │   ├── createProject.js  # Project creation logic
│   │   ├── migrateProject.js # Project migration functionality
│   │   └── updateDependencies.js # Dependency update management
│   ├── services/             # Business logic services
│   │   ├── templateService.js    # Template management
│   │   ├── fileService.js        # File operations
│   │   ├── gitService.js         # Git operations
│   │   └── validationService.js  # Input validation
│   └── utils/                # Pure utility functions
│       ├── errorHandler.js   # Consistent error handling
│       ├── logger.js         # Logging utilities
│       └── pathUtils.js      # Path manipulation utilities
├── tests/                    # 🧪 E2E testing suite
│   ├── e2e-test.sh          # Main test runner (bash)
│   ├── helpers/             # Test utilities
│   │   ├── assert.sh        # Assertion functions
│   │   └── cleanup.sh       # Test cleanup utilities
│   └── fixtures/            # Test data
├── .temp/                   # Test projects (gitignored)
└── package.json             # Package configuration with test scripts

🔄 Command Flow

graph TD
    A[boilerbuilder CLI] --> B{Command Type}
    
    B -->|Default/birl| C[Create New Project]
    B -->|update| D[Update Dependencies]
    B -->|migrate| E[Migrate Project]
    
    C --> F[Fetch Available Templates]
    F --> G[User Selection]
    G --> H[Download Template]
    H --> I[Setup Project]
    I --> J[Success Message]
    
    D --> K[Read package.json]
    K --> L[Compare with Remote]
    L --> M[Show Differences]
    M --> N[Apply Updates]
    
    E --> O[Backup Current Code]
    O --> P[Download New Template]
    P --> Q[Restore User Code]
    Q --> R[Update Configuration]
    
    style C fill:#e1f5fe
    style D fill:#f3e5f5
    style E fill:#fff3e0

🚀 Getting Started

📋 Prerequisites

• Node.js v18 or higher
• npm or yarn package manager
• Git (for template downloading)

📦 Installation

Install Boilerbuilder globally to use it anywhere:

npm install -g boilerbuilder

Or use it directly with npx:

npx boilerbuilder

🛠️ Quick Start

Create your first project:

# Interactive mode - will prompt for project name and type
boilerbuilder

# Direct mode - specify name and type
boilerbuilder --name my-awesome-project --type react-spa-vite

🛠️ Usage

🏗️ Creating a New Project

The main command creates a new project from available templates:

# Interactive mode
boilerbuilder

# With options
boilerbuilder --name <project-name> --type <template-type>

Example:

boilerbuilder --name my-react-app --type react-spa-vite

Interactive Flow:

? Nome do projeto: my-awesome-project
? Tipo do projeto: (Use arrow keys)
❯ react-spa-vite
  react-lib-vite
  next-app
  ts-lib-vite
  vue-lib-vite
  vue-spa-vite

📦 Updating Dependencies

Keep your project dependencies synchronized with the latest template standards:

cd your-project
boilerbuilder update

Requirements:

• The command detects the project type from package.json keywords[0]
• Your project's package.json must have the template name in the first keyword

Example package.json configuration:

{
  "name": "my-project",
  "keywords": ["react-spa-vite"],
  "dependencies": {
    // your dependencies
  }
}

Features:

• Compares current dependencies with template versions
• Shows detailed diff table with current vs. new versions
• Identifies missing dependencies from template
• Highlights dependencies not present in template
• Interactive confirmation before applying changes

Example Output:

Dependências para atualizar:
┌──────────────────────────────┬────────────────────┬────────────────────┐
│ Dependência                  │ Versão Atual       │ Versão Nova        │
├──────────────────────────────┼────────────────────┼────────────────────┤
│ react                        │ ^18.2.0            │ ^18.3.1            │
│ @types/react                 │ ^18.2.15           │ ^18.3.3            │
│ vite                         │ ^4.4.5             │ ^5.3.4             │
└──────────────────────────────┴────────────────────┴────────────────────┘

? Deseja atualizar as dependências automaticamente? (y/N)

🔄 Migrating Existing Projects

Migrate your existing project to a newer template while preserving your custom code:

cd your-existing-project
boilerbuilder migrate

Migration Process:

1. Detection: Automatically detects project type from package.json
2. Confirmation: Asks for confirmation or allows template selection
3. Backup: Creates src_backup and public_backup folders
4. Template Download: Downloads the latest template
5. Code Restoration: Restores your custom code from backups
6. Configuration Update: Updates package.json with your project name

Safety Features:

• Automatic backup of src/ and public/ directories
• Preserves .git and .github folders
• Maintains project name in package.json
• Non-destructive process with rollback capability

📦 Available Templates

Boilerbuilder dynamically fetches available templates from the GitHub repository. Current templates include:

• react-spa-vite: React Single Page Application with Vite
• react-lib-vite: React Library template with Vite
• next-app: Next.js Application template
• ts-lib-vite: TypeScript Library template with Vite
• vue-lib-vite: Vue.js Library template with Vite
• vue-spa-vite: Vue.js Single Page Application with Vite

Templates are maintained in the boilerplates repository and updated automatically.

⚙️ Commands Reference

Main Command (Default)

boilerbuilder [options]

Options:

• --name <name>: Specify project name
• --type <type>: Specify template type
• --version: Show version information
• --help: Display help information

Update Command

boilerbuilder update

Functionality:

• Reads current package.json
• Fetches remote template package.json
• Compares dependency versions
• Shows interactive diff table
• Applies updates with user confirmation

Migrate Command

boilerbuilder migrate

Functionality:

• Detects current project type
• Creates automatic backups
• Downloads latest template
• Restores user code
• Updates project configuration

🧩 Development

To contribute to Boilerbuilder or run it locally:

🔧 Setup

1. Clone the repository:

   git clone https://github.com/BoilerBuilder/boilerbuilder.git
   cd boilerbuilder

2. Install dependencies:

   yarn install

3. Check for existing global links:

   # Check if boilerbuilder is already linked
   npm list -g --depth=0 | grep boilerbuilder
   # or
   which boilerbuilder

4. Remove existing link (if found):

   npm unlink -g boilerbuilder

5. Link for local development:

   npm link

6. Test the CLI:

   boilerbuilder --help
   boilerbuilder --version
      
   # Run E2E tests to validate functionality
   npm test
      
   # Test specific functionality
   boilerbuilder --name test-project --type react-spa-vite

🔗 Link Management

Development Workflow:

# Complete setup from scratch
git clone https://github.com/BoilerBuilder/boilerbuilder.git
cd boilerbuilder
yarn install

# Check and remove existing links
npm list -g --depth=0 | grep boilerbuilder
npm unlink -g boilerbuilder  # if exists

# Create development link
npm link

# Test your changes
boilerbuilder --name test-project --type react-spa-vite

# Clean up when done
npm unlink -g boilerbuilder

Troubleshooting:

• Dependencies fail: Ensure yarn is installed: npm install -g yarn
• Link not found: Check PATH includes npm global bin directory
• Permission errors: May need to configure npm/yarn permissions
• Wrong version: Always unlink before relinking for development

🏃‍♂️ Development Workflow

1. Make your changes in the src/ directory
2. Test locally using npm link
3. Submit a pull request

📁 Project Structure Details

• src/index.js: Main CLI entry point with Commander.js and enhanced error handling
• src/commands/createProject.js: Project creation logic with interactive prompts
• src/commands/migrateProject.js: Project migration functionality with backup system
• src/commands/updateDependencies.js: Dependency update management with diff tables
• src/services/: Business logic services for templates, files, git operations, and validation
• src/utils/: Pure utility functions for error handling, logging, and path operations
• src/config/: Configuration constants and validation schemas
• tests/: Comprehensive E2E testing suite with bash scripts

🧪 Testing

Boilerbuilder includes comprehensive E2E tests to ensure reliability and maintain backward compatibility:

Running Tests

# Run all E2E tests
npm test

# Run with verbose output for debugging
npm run test:verbose

# Clean up test files
npm run test:cleanup

# List current test projects
npm run test:list

# For CI/CD environments
npm run test:ci

Test Coverage

The testing suite validates all core functionality:

• ✅ Project Creation: Tests all available templates from the repository
• ✅ Migration Process: Validates user code preservation during template updates
• ✅ Dependency Updates: Verifies version comparison and update mechanisms
• ✅ Backward Compatibility: Ensures old command syntax continues to work
• ✅ Error Handling: Tests graceful failure scenarios and edge cases
• ✅ CLI Interface: Validates help, version, and interactive prompts

Test Environment

• Isolation: Tests run in dedicated .temp/ directory (gitignored)
• Cleanup: Automatic cleanup after test completion
• Safety: No impact on existing projects or global state
• Speed: Bash-based tests with zero additional dependencies

Enhanced Reliability

Recent architectural improvements provide:

• 🔒 Robust Error Handling: Consistent error patterns across all operations
• 🧪 Comprehensive Testing: E2E validation ensures stability
• 🏗️ Modular Architecture: Clean, maintainable codebase
• 🔄 Backward Compatibility: All existing workflows preserved and tested

📚 Template System

🌐 Remote Template Management

Boilerbuilder uses a centralized template system:

• Repository: https://github.com/BoilerBuilder/boilerplates
• Structure: /templates/{template-name}/
• Configuration: templates.js file lists available templates
• Updates: Templates are fetched dynamically on each use

🔧 Template Structure

Each template follows this structure:

templates/
└── template-name/
    ├── package.json      # Dependencies and scripts
    ├── src/             # Source code
    ├── public/          # Static assets
    └── ...              # Template-specific files

📝 Adding New Templates

To add a new template to the system:

1. Create template folder in the boilerplates repository
2. Add template name to templates.js
3. Ensure package.json includes proper keywords for detection
4. Test template creation and migration

❓ Troubleshooting

Common Issues

1. Template Download Fails

Não foi possível buscar os templates:

• Solution: Check internet connection and GitHub repository access
• Fallback: Uses default react-spa-vite template

2. Migration Issues

Erro ao migrar o projeto:

• Solution: Ensure write permissions in project directory
• Check: Verify src/ and public/ directories exist

3. Dependency Update Issues

Erro ao atualizar dependências:

• Solution: Run command from project root directory
• Verify: Ensure package.json exists and is valid JSON

4. Template Download Issues

Erro ao baixar o template [template-name] : [error details]

• Solution: Check Git installation and network connectivity
• Alternative: Verify GitHub repository accessibility

5. Update Command Not Finding Project Type

Tipo de projeto não encontrado.

• Solution: Add the template name to your package.json keywords
• Example: Add "keywords": ["react-spa-vite"] to your package.json
• Note: The first keyword should match one of the available templates

💡 Best Practices

1. Always backup your project before migration
2. Test in development environment first
3. Review changes before confirming updates
4. Keep templates updated by running commands regularly
5. Use version control to track changes

🤝 Contributing

We welcome contributions to Boilerbuilder! Here's how you can help:

🐛 Reporting Issues

1. Check existing issues on GitHub
2. Provide detailed reproduction steps
3. Include system information (Node.js version, OS)
4. Share relevant error messages

🔧 Development Contributions

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following the existing code style
4. Test your changes thoroughly
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📝 Documentation

Help improve documentation by:

• Adding usage examples
• Fixing typos or unclear explanations
• Translating to other languages
• Creating video tutorials

📃 License

Boilerbuilder is released under the ISC License. See the LICENSE file for more details.

💬 Support

If you have questions, issues, or feature requests:

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Start a discussion
• 📧 Direct Contact: [email protected]

Happy coding with Boilerbuilder! 🎉
BIIRRRLLLL!!! 💪

Made with ❤️ by Gabriel Mule