Setting Up Shared Utilities

What you'll learn

• Generating a shared utilities package for your project
• Understanding the included DI setup, logging, and helpers
• Using common utilities across features and infrastructure
• Extending the utilities with project-specific helpers

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)

Step 1: Generate the Utilities Package

archipelago generate app_utilities

You will be prompted for:

• appName — MyApp (must match your monorepo app name)
• isForMonorepo — true

Or use a config file:

{
  "appName": "MyApp",
  "isForMonorepo": true
}

archipelago generate app_utilities --config utilities_config.json

Step 2: Understand the Generated Structure

The utilities package provides foundational helpers used across the entire workspace:

packages/
└── my_app_utilities/
    └── lib/
        ├── my_app_utilities.dart       # Barrel exports
        └── src/
            ├── di/
            │   ├── injector.dart        # GetIt singleton accessor
            │   └── module.dart          # Base DI module contract
            ├── logging/
            │   ├── app_logger.dart       # Structured logger
            │   └── log_level.dart        # Log level enum
            ├── extensions/
            │   ├── string_ext.dart       # String helpers
            │   ├── date_ext.dart         # DateTime helpers
            │   └── context_ext.dart      # BuildContext helpers
            └── helpers/
                ├── debouncer.dart        # Debounce utility
                └── result.dart           # Result<T, E> type

Step 3: Use Utilities in Features

Add the utilities package as a dependency in any feature:

# In a feature's pubspec.yaml
dependencies:
  my_app_utilities:
    path: ../../packages/my_app_utilities

Then use the provided helpers:

import 'package:my_app_utilities/my_app_utilities.dart';

// Structured logging
AppLogger.info('Payment processed', tag: 'PaymentUseCase');

// Result type for error handling
Future<Result<User, AppException>> getUser(String id) async {
  try {
    final user = await repository.findById(id);
    return Result.success(user);
  } catch (e) {
    return Result.failure(AppException.fromError(e));
  }
}

Key Customization Points

Customization	Where to Change
Add new extensions	lib/src/extensions/ — create new extension files
Change log output format	app_logger.dart — customize log formatting
Add new DI modules	lib/src/di/module.dart — extend the base module
Add platform-specific helpers	lib/src/helpers/ — add platform-aware utilities

Next Steps

• Generate the core infrastructure which depends on utilities
• Set up custom lint rules to enforce utility usage patterns