Tools and Utilities

Relevant source files

This document provides an overview of the development tools and utilities built into the Flutter Mobile Project Template. It covers the tools that help manage dependencies, generate code, and streamline common development tasks. For specific information about build configurations and environment setup, see Development Environment.

Melos Workspace Management

The template uses Melos to manage the monorepo workspace, enabling efficient handling of multiple packages and applications within a single repository.

Melos Configuration and Commands

The template includes an extensive set of predefined Melos commands configured in the root pubspec.yaml file. Below are the key command categories:

Category	Commands	Description
Bootstrap	`melos bootstrap`	Sets up the workspace, installs dependencies, and runs post-bootstrap hooks
Code Generation	`melos gen`, `melos gen:build`, `melos gen:l10n`	Runs code generation tools like build_runner and Flutter localization
Testing	`melos test`, `melos test:flutter`, `melos test:dart`	Runs tests across all packages
Code Quality	`melos fix`, `melos fix:custom`	Applies fixes using Dart and custom linters
Dependency Management	`melos upgrade`, `melos upgrade:major`	Updates package dependencies
GitHub Integration	`melos gen:labeler`, `melos gen:labels`	Generates GitHub automation configuration

Bootstrap Process

The bootstrap process (pubspec.yaml47-73) is particularly important as it:

Ensures all packages use compatible SDK versions
Sets common dependencies with synchronized versions
Runs post-bootstrap hooks to update linting rules and GitHub configuration

Sources: pubspec.yaml5-73 pubspec.yaml75-82

Code Generation Tools

The template includes various code generation tools to automate repetitive tasks and maintain consistency across the codebase.

Build Runner Integration

The template uses the standard Dart build_runner package for code generation, with the following generators:

Riverpod Generator: Generates providers using the @riverpod annotation
Freezed: Generates immutable data classes with equality and serialization support
JSON Serializable: Provides JSON encoding/decoding for data models
Flutter Gen: Generates type-safe access to assets

You can run the build_runner with:

melos gen:build

This command will run build_runner in all packages that depend on it.

Sources: pubspec.yaml101-107

Localization Generation

The template supports internationalization using Flutter's built-in localization system. The gen:l10n command generates the necessary localization classes from ARB files:

melos gen:l10n

This runs flutter gen-l10n in all packages that depend on flutter_localizations.

Sources: pubspec.yaml108-114

GitHub Automation

The template includes custom tools for automating GitHub workflows:

Label Generator

The gen:labels command (tools/gen_labels.dart) generates labels for GitHub issues and pull requests in .github/labels.yml, including package-specific labels.

Labeler Configuration Generator

The gen:labeler command (tools/gen_labeler.dart) creates the .github/labeler.yml configuration that automatically applies the appropriate labels to pull requests based on which files are changed.

Sources: tools/gen_labels.dart1-149 tools/gen_labeler.dart1-108 pubspec.yaml115-120

Utility Scripts

The template provides several utility scripts to help with common development tasks.

YAML Diff Tool

The diff_yaml.dart tool (tools/diff_yaml.dart) compares YAML files to:

Show differences between the current and reference branch's pubspec.lock file
Identify inconsistencies between version specifications in pubspec.yaml and pubspec.lock

This is particularly useful for reviewing dependency changes during code reviews.

Usage:

dart run tools/diff_yaml.dart <reference-branch> pubspec.yaml pubspec.lock

Sources: tools/diff_yaml.dart1-220

Helper Utilities

The template includes several helper utilities used by the main scripts:

Path Utilities: Functions for working with file paths and Git repository paths
Command Runner: A wrapper for running shell commands with error handling
Logger: Provides consistent formatted logging for script output
Label Utilities: Helper functions for label generation scripts

Sources: tools/utils/command_runner.dart1-32 tools/utils/logger.dart1-25 tools/utils/label.dart1-27 tools/utils/constants.dart1-3

Dependency and Environment Management

Dependency Management with Melos

The upgrade and upgrade:major commands help manage dependencies across the entire workspace:

# Regular upgrade
melos upgrade

# Major version upgrade (potentially breaking changes)
melos upgrade:major

These commands run dart pub upgrade and dart pub upgrade --major-versions respectively on all packages.

Sources: pubspec.yaml122-133

Package and Environment Control

The template uses mise for environment management (previously known as rtx), ensuring consistent Flutter and Dart SDK versions across the development team. The template also includes scripts for updating platform-specific dependencies:

# Update iOS Cocoapods repositories
melos pod:repo_update:ios

# Update macOS Cocoapods repositories
melos pod:repo_update:macos

Sources: pubspec.yaml215-225

Mason Bricks

The template uses Mason for code generation templates (called "bricks"). Mason is a template generator that helps maintain consistency when creating new components, features, or files.

Mason is configured as a development dependency:

# Install a brick
mason add <brick-name>

# Generate code from a brick
mason make <brick-name>

Sources: pubspec.yaml29 .gitignore14-19

Spelling and Markdown Linting Tools

The template includes tools for ensuring consistent documentation and spelling:

cspell: Spell checking with custom dictionaries for Dart and Flutter
markdownlint: Linting for Markdown documentation files

These tools help maintain high-quality documentation and comments throughout the codebase.

Sources: package.json1-8 .markdownlint-cli2.jsonc1-22