Mason Brick Development Skill

This skill guides the creation, modification, and removal of Mason bricks, ensuring test coverage and CI workflow integration.

When to Use

Trigger this skill when:

• Creating a new Mason brick template
• Updating an existing brick's structure or variables
• Removing a brick from the project
• User asks to "create a brick", "add a mason template", "update brick", or "remove brick"

Project Structure

Bricks are organized in three locations:

bricks/                    # Mason template definitions
├── brick_name/
│   ├── brick.yaml         # Brick configuration and variables
│   ├── __brick__/         # Template files with Mustache syntax
│   └── hooks/             # Optional pre/post generation hooks

test_bricks/               # Brick tests (one folder per brick)
├── brick_name/
│   └── brick_name_test.dart

.github/workflows/
└── brick-test.yml         # Parallel CI jobs for each brick

Creating a New Brick

Step 1: Create Brick Directory

mkdir -p bricks/new_brick/__brick__

Step 2: Create brick.yaml

name: new_brick
description: Description of what this brick generates
version: 0.1.0+1

environment:
  mason: ^0.1.1

vars:
  name:
    type: string
    description: The name for the generated component
    prompt: What is the name?

  # Add more variables as needed
  optional_var:
    type: boolean
    description: Optional feature flag
    default: true

Step 3: Create Template Files

In __brick__/, create files using Mustache syntax:

__brick__/
├── {{name.snakeCase()}}/
│   ├── lib/
│   │   └── {{name.snakeCase()}}.dart
│   ├── pubspec.yaml
│   └── README.md

Use these Mustache helpers:

• {{name}} - raw value
• {{name.snakeCase()}} - snake_case
• {{name.pascalCase()}} - PascalCase
• {{name.camelCase()}} - camelCase
• {{name.paramCase()}} - param-case
• {{#flag}}...{{/flag}} - conditional block
• {{^flag}}...{{/flag}} - inverted conditional

Step 4: Create Brick Test

Create test_bricks/new_brick/new_brick_test.dart:

import 'dart:io';
import 'package:mason/mason.dart';
import 'package:path/path.dart' as path;
import 'package:test/test.dart';

void main() {
  group('New Brick Tests', () {
    late Directory tempDir;

    setUp(() async {
      tempDir = await Directory.systemTemp.createTemp('new_brick_test_');
    });

    tearDown(() async {
      if (await tempDir.exists()) {
        await tempDir.delete(recursive: true);
      }
    });

    test('generates correct structure', () async {
      final brick = Brick.path(path.join('..', '..', 'bricks', 'new_brick'));

      final generator = await MasonGenerator.fromBrick(brick);
      await generator.generate(
        DirectoryGeneratorTarget(tempDir),
        vars: {'name': 'test_name'},
      );

      // Verify generated files exist
      final file = File(path.join(tempDir.path, 'test_name', 'pubspec.yaml'));
      expect(await file.exists(), isTrue);
    });

    // Add more tests for different variable combinations
  });
}

Step 5: Add Workflow Job

Add a new job to .github/workflows/brick-test.yml:

  new-brick:
    name: Test new_brick
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: flutter-actions/setup-flutter@v4

      - name: Cache dependencies
        uses: actions/cache@v5
        with:
          path: |
            ~/.pub-cache
            .dart_tool
          key: ${{ runner.os }}-pub-${{ hashFiles('**/pubspec.lock') }}
          restore-keys: ${{ runner.os }}-pub-

      - name: Install tools
        run: dart pub global activate melos

      - name: Prepare project
        run: |
          melos run prepare
          mason get

      - name: Test new_brick brick
        run: dart run test_bricks/new_brick/new_brick_test.dart

Step 6: Register Brick

Add to root mason.yaml:

bricks:
  new_brick:
    path: bricks/new_brick

Then run mason get to register.

Updating an Existing Brick

When modifying a brick:

1. Update brick.yaml if adding/removing variables
2. Update template files in __brick__/
3. Update tests in test_bricks/brick_name/ to cover changes
4. Run test locally: dart run test_bricks/brick_name/brick_name_test.dart
5. Increment version in brick.yaml

Removing a Brick

When removing a brick, update all three locations:

1. Remove brick directory: rm -rf bricks/brick_name
2. Remove test directory: rm -rf test_bricks/brick_name
3. Remove workflow job from .github/workflows/brick-test.yml
4. Remove from mason.yaml
5. Update CLAUDE.md if the brick was documented

Testing Locally

# Register bricks
mason get

# Test a specific brick
dart run test_bricks/brick_name/brick_name_test.dart

# Test brick generation manually
mason make brick_name -o /tmp/test_output --var1=value1

Existing Bricks Reference

Checklist

When creating/updating a brick:

• brick.yaml has name, description, version, and vars
• Template files use correct Mustache syntax
• Test file exists in test_bricks/brick_name/
• Tests cover main generation paths
• Workflow job added/updated in brick-test.yml
• Brick registered in mason.yaml
• Run mason get to verify registration
• Run test locally before committing