Automate Your Flutter Development with Code Generation

The Problem We All Face#

Picture this: You’re building a Flutter app, and you need to add a new feature. You create the folder structure, add the data layer, domain layer, presentation layer, set up dependency injection, configure routing, add localization files, register everything in your app’s main files… and 45 minutes later, you haven’t written a single line of business logic yet.

Sound familiar?

This repetitive process isn’t just time-consuming—it’s error-prone. Forget to register a route? Your navigation breaks. Typo in an import? Build fails. Different team members structure their features differently? Your codebase becomes inconsistent.

There’s a better way.

Enter Mason#

Mason is a code generation tool for Dart and Flutter projects, created by Felix Angelov (the same developer behind the BLoC pattern library). Think of it as “templates on steroids”—you define reusable code templates (called “bricks”), and Mason generates all the boilerplate code for you, complete with custom logic and automation.

But here’s where it gets interesting: Mason doesn’t just copy-paste files. It can:

Accept user input and transform it (snake_case to PascalCase, etc.)
Run custom Dart code before and after generation
Modify existing files to wire up your generated code
Execute shell commands like running build tools

In this tutorial, I’ll show you how to leverage Mason using real-world examples from a production Flutter app. By the end, you’ll know how to create your own bricks that can save your team hours of work every week.

Getting Started with Mason#

Installation#

First, install Mason CLI globally:

1
dart pub global activate mason_cli

Verify the installation:

1
mason --version

Your First Brick#

Let’s understand Mason’s basic concepts by looking at how it works. A Mason project has two key files:

mason.yaml - Your project’s brick registry:

1
bricks:
2
  feature:
3
    path: ./bricks/feature/
4
  component:
5
    path: ./bricks/component/

This file tells Mason which bricks are available in your project.

Basic Concepts#

Before we dive into complex examples, let’s clarify the terminology:

Brick: A template package that generates code
Template: The actual files and folders with placeholders
Variables: User inputs that get substituted into templates
Hooks: Dart scripts that run before/after generation
Mustache syntax: The {{variable}} placeholder format

A Simple Example#

Let’s create a basic brick to understand the flow:

1
mason new hello

This creates a brick structure:

1
bricks/hello/
2
├── brick.yaml
3
├── __brick__/
4
│   └── hello.txt
5
└── hooks/

The brick.yaml defines your brick:

1
name: hello
2
description: A simple hello brick
3
version: 0.1.0
4

5
vars:
6
  name:
7
    type: string
8
    prompt: What is your name?

The template file (__brick__/hello.txt) uses your variable:

1
Hello, {{name}}!
2
Welcome to Mason.

Run it:

1
mason make hello
2
# Prompt: What is your name? → John

Output (hello.txt):

1
Hello, John!
2
Welcome to Mason.

Simple, right? Now let’s see what’s possible with real-world examples.

Real-World Example: Feature Module Generation#

Let me show you a brick from a production Flutter app that generates complete feature modules. This is where Mason’s power really shines.

The Challenge#

In a well-architected Flutter app using clean architecture, creating a new feature requires:

Creating a package structure with multiple folders
Setting up localization files (potentially multiple languages)
Configuring dependency injection
Setting up routing
Registering the feature in the main app’s:
- pubspec.yaml
- Localization delegates
- Router configuration
- Dependency injection container
Running build tools

Doing this manually takes 30-45 minutes and is prone to errors. With Mason? Less than 30 seconds.

The Brick Structure#

Here’s the brick configuration (bricks/feature/brick.yaml):

1
name: feature
2
description: Generate a complete feature module
3
version: 0.1.0+1
4

5
environment:
6
  mason: ^0.1.1
7

8
vars:
9
  feature:
10
    type: string
11
    description: Your feature name
12
    prompt: What is the feature name? (in snake_case)

The template structure (bricks/feature/__brick__/):

1
packages/feature/{{feature}}/
2
├── l10n.yaml
3
├── pubspec.yaml
4
└── lib/
5
    ├── {{feature}}_feature_routes.dart
6
    ├── data/
7
    ├── domain/
8
    │   ├── model/
9
    │   ├── repository/
10
    │   └── usecase/
11
    ├── di/
12
    │   └── {{feature}}_feature_di.dart
13
    ├── l10n/
14
    │   ├── {{feature}}_ar.arb
15
    │   ├── {{feature}}_en.arb
16
    │   └── {{feature}}_fr.arb
17
    ├── page/
18
    └── ui/

Notice the {{feature}} placeholders in file and folder names? Mason will replace these with the user’s input.

Template Files with Logic#

Here’s a template file ({{feature}}_feature_di.dart):

1
import 'package:get_it/get_it.dart';
2

3
void register{{feature.pascalCase()}}FeatureDependencies(GetIt locator) {
4
  // register dependencies here
5
}

The {{feature.pascalCase()}} function transforms the input. If the user enters user_profile, the output becomes:

1
import 'package:get_it/get_it.dart';
2

3
void registerUserProfileFeatureDependencies(GetIt locator) {
4
  // register dependencies here
5
}

Mason includes built-in transformations:

{{variable.camelCase()}} → userProfile
{{variable.pascalCase()}} → UserProfile
{{variable.snakeCase()}} → user_profile
{{variable.constantCase()}} → USER_PROFILE
And more!

Running the Brick#

1
mason make feature

1
? What is the feature name? (in snake_case) notifications

Mason generates the entire structure in seconds. But we’re just getting started…

Advanced: Post-Generation Hooks#

Here’s where Mason becomes truly powerful. After generating files, we need to integrate them into the app. Instead of manual steps, we can automate everything with post-generation hooks.

What Are Hooks?#

Hooks are Dart scripts that run before (pre_gen.dart) or after (post_gen.dart) generation. They have full access to:

The file system
User’s input variables
Shell commands
Dart packages

A Production Hook Example#

Let’s look at the actual post-generation hook from the feature brick (bricks/feature/hooks/post_gen.dart):

1
import 'dart:io';
2
import 'package:recase/recase.dart';
3
import 'package:mason/mason.dart';
4

5
void run(HookContext context) async {
6
  final feature = context.vars['feature'];
7

8
  _insertFeatureInAppPubspec(feature);
9
  _insertFeatureInAppLocalizations(feature);
10
  _insertFeatureInAppFeatureRoutes(feature);
11
  _insertFeatureInAppServiceLocator(feature);
12

13
  await Process.run('bash', ['-c', 'melos bs']);
14
}

This hook automatically:

Adds the feature to pubspec.yaml
Registers localization delegates
Registers routes
Registers dependency injection
Runs the monorepo bootstrap command

The developer never touches these files manually.

The Insertion Pattern#

Here’s a clever pattern used in the hook for adding code to existing files:

1
void _insertFeatureInAppPubspec(feature) {
2
  final file = File('apps/my_app/pubspec.yaml');
3
  final lines = file.readAsLinesSync();
4

5
  _insertBeforeAnchor('#endregion Features', "  feature_$feature:", lines);
6

7
  file.writeAsStringSync(lines.join('\n'));
8
}
9

10
void _insertBeforeAnchor(String anchor, String insert, List<String> lines) {
11
  final index = lines.indexWhere((line) => line.contains(anchor));
12
  lines.insert(index, insert);
13
}

The pubspec.yaml file has “anchor” comments:

1
dependencies:
2
  #region Features
3
  feature_authentication:
4
  feature_home:
5
  #endregion Features

The hook finds the #endregion Features marker and inserts the new feature before it. This keeps the code organized and makes automation reliable.

Registering Localizations Automatically#

Another example from the same hook:

1
void _insertFeatureInAppLocalizations(feature) {
2
  final file = File('apps/my_app/lib/l10n/max_it_localizations.dart');
3
  final lines = file.readAsLinesSync();
4

5
  // Add import at the top
6
  lines.insert(0,
7
    "import 'package:feature_$feature/l10n/${feature}_localizations.dart';");
8

9
  // Add delegate
10
  final featurePascalCase = ReCase(feature).pascalCase;
11
  _insertBeforeAnchor(
12
    '// #endregion Features Delegates',
13
    "    ${featurePascalCase}Localizations.delegate,",
14
    lines,
15
  );
16

17
  // Add supported locales
18
  _insertBeforeAnchor(
19
    '// #endregion Features Supported Locales',
20
    "    ...${featurePascalCase}Localizations.supportedLocales,",
21
    lines,
22
  );
23

24
  file.writeAsStringSync(lines.join('\n'));
25
}

This single function:

Adds the import statement
Registers the localization delegate
Adds the supported locales

All without the developer lifting a finger.

Running Shell Commands#

The hook can also execute commands:

1
await Process.run('bash', ['-c', 'melos bs']);
2

3
// Or run build_runner for code generation
4
final generateCommand = 'dart run build_runner build --delete-conflicting-outputs';
5
await Process.run('bash', [
6
  '-c',
7
  "melos exec --depends-on build_runner --scope feature_$feature -- $generateCommand",
8
]);

This ensures all build steps complete automatically after generation.

Hook Dependencies#

Hooks can use Dart packages. Define them in bricks/feature/hooks/pubspec.yaml:

1
name: feature_hooks
2

3
environment:
4
  sdk: ^3.5.4
5

6
dependencies:
7
  mason: ^0.1.1
8
  recase: ^4.1.0

Now the recase package is available for string transformations in your hook.

Real-World Example 2: Page Generation with BLoC#

Let’s look at another brick from the same project that generates pages within features using the BLoC pattern.

The Brick Configuration#

1
name: page
2
description: Generate a BLoC-based page
3
version: 0.1.0+1
4

5
vars:
6
  feature:
7
    type: enum
8
    prompt: What is the feature name?
9
    values:
10
      - home
11
      - authentication
12
      - notifications
13
      - profile
14
  page:
15
    type: string
16
    prompt: What is the page name? (in snake_case)
17
  addFeatureRoute:
18
    type: boolean
19
    default: false
20
    prompt: Expose the page as a feature route?

Key differences from the feature brick:

Enum Variable: The feature variable is an enum, so users select from existing features
Boolean Variable: Conditional logic based on whether this is an app-level route
Multiple Variables: Three inputs that work together

The Generated Structure#

1
packages/feature/{{feature}}/lib/page/{{page}}/
2
├── {{page}}_bloc.dart
3
├── {{page}}_route.dart
4
├── {{page}}_screen.dart
5
├── mapper/
6
└── model/
7
    ├── {{page}}_event.dart
8
    └── {{page}}_state.dart

Template Example: BLoC Boilerplate#

Here’s what the {{page}}_screen.dart template might look like:

1
import 'package:flutter/material.dart';
2
import 'package:flutter_bloc/flutter_bloc.dart';
3
import '{{page}}_bloc.dart';
4
import 'model/{{page}}_state.dart';
5
import 'model/{{page}}_event.dart';
6

7
class {{page.pascalCase()}}Screen extends StatelessWidget {
8
  const {{page.pascalCase()}}Screen({super.key});
9

10
  @override
11
  Widget build(BuildContext context) {
12
    return BlocProvider(
13
      create: (context) => {{page.pascalCase()}}Bloc(),
14
      child: const _{{page.pascalCase()}}View(),
15
    );
16
  }
17
}
18

19
class _{{page.pascalCase()}}View extends StatelessWidget {
20
  const _{{page.pascalCase()}}View();
21

22
  @override
23
  Widget build(BuildContext context) {
24
    return Scaffold(
25
      appBar: AppBar(
26
        title: const Text('{{page.titleCase()}}'),
27
      ),
28
      body: BlocBuilder<{{page.pascalCase()}}Bloc, {{page.pascalCase()}}State>(
29
        builder: (context, state) {
30
          return const Center(
31
            child: Text('{{page.pascalCase()}} Screen'),
32
          );
33
        },
34
      ),
35
    );
36
  }
37
}

If the user enters user_settings, this generates a complete BLoC screen with proper naming.

Conditional Hook Logic#

The page brick’s hook uses conditional logic:

1
void run(HookContext context) async {
2
  final feature = context.vars['feature'];
3
  final page = context.vars['page'];
4
  final addFeatureRoute = context.vars['addFeatureRoute'] as bool;
5

6
  _insertScreenInFeatureRoutes(feature, page);
7

8
  if (addFeatureRoute) {
9
    _insertScreenInAppRoutes(feature, page);
10
  }
11

12
  _triggerBuildRunner(feature);
13
}

If addFeatureRoute is true, it performs additional integration. Otherwise, it skips that step.

Updating the Feature Brick Dynamically#

Here’s something clever—the feature brick’s hook automatically updates the page brick:

1
void _insertFeatureInPageBrick(feature) {
2
  final file = File('bricks/page/brick.yaml');
3
  final lines = file.readAsLinesSync();
4

5
  _insertBeforeAnchor('#endregion Feature list', "      - $feature", lines);
6

7
  file.writeAsStringSync(lines.join('\n'));
8
}

When you create a new feature, it automatically appears in the page brick’s feature dropdown. The bricks evolve with your project.

Best Practices & Patterns#

Here are some best practices we’ve identified based on the challenges we encountered in our project. These patterns help make our bricks more maintainable and consistent.

1. Use Region Markers for Insertion Points#

Instead of fragile line number-based insertion, use comments as anchors:

1
dependencies:
2
  #region Features
3
  feature_home:
4
  feature_auth:
5
  #endregion Features

Your hook looks for #endregion Features and inserts before it. This is:

Reliable (doesn’t break if other code changes)
Self-documenting (developers see the organization)
IDE-friendly (many editors support region folding)

2. Validate with Pre-Generation Hooks#

Use pre_gen.dart to check preconditions:

1
void run(HookContext context) {
2
  if (!File('pubspec.yaml').existsSync()) {
3
    throw Exception('Must run this brick from project root.');
4
  }
5

6
  final feature = context.vars['feature'];
7
  if (Directory('packages/feature/$feature').existsSync()) {
8
    throw Exception('Feature $feature already exists!');
9
  }
10
}

This prevents mistakes before generation starts.

3. Keep Templates Simple, Logic in Hooks#

Don’t overcomplicate templates with conditional logic. Keep templates clean and handle complexity in hooks.

Good:

1
// Template is clean
2
class {{name.pascalCase()}}Service {}
3

4
// Hook handles registration
5
void _registerInDI(name) {
6
  // complex registration logic
7
}

Bad:

1
// Too much logic in template
2
{{#if needsAuth}}
3
{{#if isAdmin}}
4
// complex nested conditionals
5
{{/if}}
6
{{/if}}

4. Make Hooks Idempotent When Possible#

If a brick can be run multiple times safely, it’s less error-prone:

1
void _addDependency(String dep) {
2
  final lines = file.readAsLinesSync();
3

4
  // Check if it already exists
5
  if (lines.any((line) => line.contains(dep))) {
6
    return; // Already added, skip
7
  }
8

9
  // Add it
10
  _insertBeforeAnchor('#endregion', dep, lines);
11
}

5. Version Control Considerations#

In .gitignore:

1
# Mason cache
2
.mason/
3

4
# Lock file (if using local paths)
5
mason-lock.json

But do commit your bricks:

1
✅ bricks/
2
✅ mason.yaml

Your team needs the brick templates.

Creating Your Own Bricks: A Step-by-Step Guide#

Ready to create a brick for your project? Here’s the process:

Step 1: Identify the Pattern#

Look for repetitive tasks in your codebase:

Do you create similar widgets repeatedly?
Is there a common service pattern?
Do you have boilerplate for API endpoints?

Step 2: Create the Brick#

1
mason new my_brick

This generates the starter structure.

Step 3: Design Your Variables#

Edit brick.yaml:

1
vars:
2
  name:
3
    type: string
4
    prompt: What is the name?
5
  type:
6
    type: enum
7
    prompt: Select type
8
    values:
9
      - basic
10
      - advanced
11
  includeTests:
12
    type: boolean
13
    default: true
14
    prompt: Include test files?

Step 4: Create Your Templates#

In __brick__/, create files with placeholders:

1
// __brick__/lib/{{name}}_service.dart
2
class {{name.pascalCase()}}Service {
3
  {{#includeTests}}
4
  // This appears only if includeTests is true
5
  {{/includeTests}}
6
}

Step 5: Test Locally#

1
mason make my_brick

Iterate on the templates until they’re right.

Step 6: Add Hooks (Optional)#

If you need automation, create hooks/post_gen.dart:

1
import 'dart:io';
2
import 'package:mason/mason.dart';
3

4
void run(HookContext context) async {
5
  final name = context.vars['name'];
6

7
  print('Generated ${name}!');
8

9
  // Add your automation here
10
}

Step 7: Add to mason.yaml#

1
bricks:
2
  my_brick:
3
    path: ./bricks/my_brick/

Step 8: Document It#

Add a README in your brick folder explaining:

What it generates
What variables it expects
What manual steps (if any) are needed

Commit the brick and teach your team to use it:

1
git add bricks/my_brick mason.yaml
2
git commit -m "feat: add my_brick for generating X"

Key Benefits & Takeaways#

After implementing Mason in production projects, here’s what teams typically experience:

1. Massive Time Savings#

Before Mason:

Creating a feature: 30-45 minutes
Creating a page: 15-20 minutes
Risk of mistakes: High

After Mason:

Creating a feature: 30 seconds
Creating a page: 15 seconds
Risk of mistakes: Near zero

Over a project with 20 features and 100 pages, that’s 50+ hours saved.

2. Consistent Architecture#

Every feature follows the exact same structure. New developers can navigate the codebase easily because everything is predictable.

3. Self-Documenting Codebase#

Your bricks become living documentation. Want to know the feature structure? Look at bricks/feature/__brick__/. Want to know integration points? Look at the hook.

4. Reduced Onboarding Time#

New team members don’t need to understand every integration point. They just run mason make feature and everything works.

5. Focus on Business Logic#

Instead of spending time on folder structure and wiring, developers immediately start working on the actual feature logic.

6. Scales with Complexity#

The more complex your architecture, the more Mason saves you. A simple app might save 20 hours per project. A complex enterprise app might save 200 hours.

7. Easy to Iterate#

Architecture changes? Update the brick, and all future features follow the new pattern. You can even provide migration bricks to update existing code.

Conclusion#

Mason transforms how you build Flutter applications. What starts as a simple templating tool becomes a powerful automation system that:

Eliminates repetitive boilerplate
Ensures architectural consistency
Reduces human error
Accelerates development
Makes your codebase more maintainable

The examples you’ve seen—the feature brick with 8 automated integration points, the page brick with conditional logic—are from a real production app. They save the team dozens of hours every month.

Start small: Create a brick for one repetitive pattern in your project. Maybe it’s a widget, a service, or a page template.

Grow your library: As you identify more patterns, add more bricks. Your brick collection becomes your team’s superpower.

Share with others: Open-source your bricks on BrickHub or blog about them. The Flutter community will thank you.

Mason isn’t just a tool—it’s an investment in your development workflow that pays dividends immediately and continues to pay off as your project grows.

Additional Resources#

Official Documentation: docs.brickhub.dev
Mason GitHub: github.com/felangel/mason
BrickHub: brickhub.dev - Public brick repository
Flutter Package of the Week: Mason on YouTube
Very Good Engineering Blog: Search for Mason articles

Try It Yourself#

Ready to get started? Install Mason and create your first brick:

1
# Install Mason
2
dart pub global activate mason_cli
3

4
# Create a new brick
5
mason new my_first_brick
6

7
# Customize it, then run it
8
mason make my_first_brick

Happy coding, and may your boilerplate be forever automated! 🧱

This tutorial uses examples from a production Flutter application to demonstrate real-world Mason usage. The patterns shown are battle-tested across dozens of features and hundreds of pages.