QBS (Quick Build Switch) #

A command-line tool to switch between different configurations in Dart and Flutter projects. 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.

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!