qbs 0.1.2

A command-line tool to switch between different configurations defined in a YAML file. This tool allows you to easily toggle between development, staging, production, or any custom environments using [...]

QBS (Quick Build Switch)

A command-line tool to switch between different configurations defined in a YAML file. This tool allows you to easily toggle between development, staging, production, or any custom environments using simple annotations in your code.

Features

• Simple Configuration: Define your environments in a simple YAML file
• Powerful Annotations: Use annotations to mark blocks of code for specific environments
• Smart Switching: Quickly switch between environments without manual code changes
• Supports Multiple File Types: Works with Dart, YAML, Gradle, Kotlin, Java, and more
• Customizable: Configure file extensions, comment styles, and exclusion patterns

Installation

dart pub global activate qbs

Getting Started

1. Create a Configuration File

Create a qbs.yaml file in your project root with your configuration definitions:

configurations:
  dev:
    name: "Development"
    description: "Development environment configuration"

  staging:
    name: "Staging"
    description: "Staging environment configuration"

  prod:
    name: "Production"
    description: "Production environment configuration"

default_config: dev

file_settings:
  supported_extensions:
    - .dart
    - .yaml
    - .yml
    - .gradle
    - .kt
    - .java

  comment_prefixes:
    yaml: "#"
    dart: "//"
    gradle: "//"
    default: "//"

annotations:
  start_format: "@if({config})"
  end_format: "@endif({config})"

exclude_directories:
  - .git
  - .dart_tool
  - build

exclude_files:
  - qbs.yaml
  - "*.g.dart"

2. Add Annotations to Your Code

Add annotations to conditionally include code for specific environments:

import 'package:flutter/material.dart';

void main() {
  //@if(dev)
  print('Development mode is active');
  //@endif(dev)

  //@if(prod)
  // print('Production mode is active');
  //@endif(prod)

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(),
    );
  }
}

3. Switch Between Configurations

List all available configurations:

qbs --list-configs

Switch to a specific configuration:

qbs dev       # Switch to development config
qbs prod      # Switch to production config
qbs staging   # Switch to staging config

Usage

Basic Commands

# Switch to a specific configuration
qbs [configuration-name]

# List all available configurations
qbs --list-configs
qbs -l

# Use verbose output
qbs --verbose dev
qbs -v prod

# Use quiet mode (minimal output)
qbs --quiet staging
qbs -q staging

# Use a custom config file
qbs --config my-config.yaml dev
qbs -c custom.yaml prod

# Show help
qbs --help
qbs -h

Annotation Format

By default, QBS uses the following annotation format:

//@if(config-name)
Code that will be enabled when the config is active
//@endif(config-name)

The comment style (//, #, etc.) is determined by the file extension and can be customized in your configuration file.

Advanced Configuration

File Settings

Configure which file extensions to process and how comments are formatted:

file_settings:
  supported_extensions:
    - .dart
    - .yaml
    - .yml
    - .gradle

  comment_prefixes:
    yaml: "#"
    dart: "//"
    gradle: "//"
    default: "//"

Exclusions

Exclude specific directories or file patterns:

exclude_directories:
  - .git
  - .dart_tool
  - build
  - .idea

exclude_files:
  - qbs.yaml
  - pubspec.lock
  - "*.g.dart"
  - "*.freezed.dart"

Custom Annotation Format

Customize the annotation format if needed:

annotations:
  start_format: "BEGIN-{config}"
  end_format: "END-{config}"

Medium articles by the author

You can always read the articles I write on my devmuaz account which I write pretty great flutter content out there.

Acknowledgments

Special thanks to Mohamed Khatib for being the main inspiration behind this package. His insights and discussions were invaluable in shaping QBS into what it is today.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

If you find this package useful for you and liked it, give it a like ❤️ and star the repo ⭐️ it would mean a lot!