create-package

Package Creation Skill

This skill defines the process for adding a new local package to the root Dart pub workspace, following the pattern established by packages/app_ui (UI kit) and packages/framework (foundation utilities).

1. When to Create a Package vs. a Feature/Infrastructure Domain

Create a new workspace package only when the code is genuinely reusable outside the app itself, or needs a hard dependency boundary (e.g. it must not depend on Flutter, or must not depend on other app code). If the code is app-specific business logic, use create-feature or create-infrastructure instead — most new work belongs in lib/src/, not a new package.

2. Directory Structure

packages/<name>/
├── lib/
│   ├── <name>.dart          # Public barrel — only export what's public API
│   └── src/
│       └── ...              # Implementation, not exported directly
├── test/
│   └── ...                  # Mirrors lib/src/
├── analysis_options.yaml
└── pubspec.yaml

• Package name: snake_case, matching the directory name.
• Never import a package's src/ internals from outside the package — only the barrel file is the public contract.

3. pubspec.yaml

Use resolution: workspace (not a version constraint on the SDK environment beyond what the app requires) so the package resolves against the root workspace's single lockfile:

name: <name>
description: "<One-line description>"
version: 0.0.1
publish_to: 'none'

environment:
  sdk: ^3.12.0
  flutter: ">=3.44.0"

resolution: workspace

dependencies:
  flutter:
    sdk: flutter

dev_dependencies:
  flutter_test:
    sdk: flutter
  very_good_analysis: ^10.2.0

• Only add flutter: as a dependency if the package actually needs Flutter (widgets, Color, etc.). A pure-Dart package (like a data model or algorithm library) should omit it to keep the dependency surface minimal — framework includes it today only because ScaleBinding/ViewProps need Flutter types; don't treat that as a requirement.
• If the package needs codegen (build_runner + a generator such as riverpod_generator, dart_mappable_builder, or chopper_generator), add both as dev_dependencies — melos run generate already targets every package via packageFilters: dependsOn: build_runner, so no script changes are needed.
• Never add a dependency on another local package (app_ui, framework, or the root app) unless it is a deliberate, one-directional layering decision — app_ui and framework do not depend on each other today.