scaffold-feature-module

Scaffold a feature module

Stand up one feature the same way every time: a folder lib/features/<feature>/ whose presentation/ holds a dumb View, its 1:1 Notifier/AsyncNotifier ViewModel, leaf widgets/, and scoped providers (feature-local models live in an optional domain/). A feature is a folder, not a package. It reads shared repositories from lib/data/ and shared foundation from lib/core/, routes every write through them, and depends only downward — never sideways into another feature. (The single-package tree is owned by project-structure-and-packages.)

Agnostic core (holds under any state library): the View is dumb; one ViewModel per feature owns private mutable state and exposes intent methods that assign a new immutable value; reads derive from the repository (the single source of truth), writes go through one repository method (the single write path, persist-before-publish); the feature depends on abstractions and navigates by route ID. The Riverpod-first "how" below wires that with Notifiers, scoped StreamProviders, and providers-as-DI.

Read the reference for the task at hand:

• references/anatomy-and-wiring.md — the fixed folder shape, the Notifier + scoped stream, watch/read/listen, family+autoDispose vs keepAlive, the single write path, and the ViewModel test.
• references/routing-and-l10n.md — typed go_router registration (path params, not state.extra) and the ARB parity workflow.
• references/add-persisted-record.md — the optional model → table → DAO → repository chain when the feature reads a brand-new record (defers to persistence-drift).

Run scripts/scaffold_feature.sh <feature> to generate the skeleton, then scripts/verify_feature.sh before a PR.

Non-negotiable rules

1. A feature is a FOLDER, never a new package. lib/features/<feature>/, lower_snake_case, named for the screen (tasks, task_detail, settings, onboarding). A new folder is a normal addition; a new package is a deliberate boundary decision (see project-structure-and-packages). Do not invent numbered-folder or fixed-package-count conventions. The app package does not use lib/src/ — that is a multi-package convention (see project-structure-and-packages).
2. Fixed anatomy, one primary public type per file. Under lib/features/<feature>/presentation/: <feature>_screen.dart (the dumb View), <feature>_notifier.dart (the 1:1 Notifier/AsyncNotifier ViewModel — file name = its primary declaration, per naming-conventions), widgets/ (leaf views), and <feature>_providers.dart (providers scoped to this feature, never global). A feature-local model lives in an optional domain/<feature>.dart. Predictable shape = a reviewer finds any piece in one second.
3. The View is dumb; the ViewModel is 1:1. The View reads exactly one controller and renders — only show/hide ifs, layout, animation, and navigation. No repository call, no try/catch business logic, no unit math or formatting in build(). Logic lives in the ViewModel.
4. A feature NEVER imports another feature. Share via a foundation layer (core/data), or navigate by route ID. Dependencies point down only — a lint/grep gate fails a cross-feature import. Sideways coupling turns two features into one un-deletable knot.
5. Read the store only through repository providers; wrap .watch() in a scoped StreamProvider. Never touch Drift, secure storage, or a platform channel from a widget or ViewModel. Scope the stream by its key (an owner/parent id, a time window) so one write never re-emits app-wide.
6. ref.watch in build, ref.read in callbacks, ref.listen for one-shot effects (SnackBar, navigate). Watching in a callback re-subscribes; reading in build misses rebuilds. (See state-management-riverpod for the full split.)
7. Per-key state is family + autoDispose; singletons are keepAlive. Any provider scoped to a specific entity/session is family-keyed on a stable equatable value and autoDisposed so it dies with its screen. Never an un-keyed "current thing" provider; never autoDispose the app-scope db/service singletons.
8. Every mutation is one repository method — the single write path, persist-before-publish. A command on the ViewModel calls a named repository method that commits, then the stream re-emits and the UI rebuilds. No optimistic republish, no setState, no manual cache poke, no "save later".
9. Derive, don't store. Counts, totals, filtered lists, streaks are computed from the source of truth (a derived/stream provider), never a second stored counter that drifts out of sync.
10. Repositories map rows → value objects; the ViewModel passes value objects. A Drift row, companion, or Map never reaches a ViewModel or widget. Measured quantities are value objects (see value-objects-money-and-units) — never a bare double for money.
11. Errors are typed values surfaced as AsyncValue. Repositories return a sealed Result/ Failure; the ViewModel maps it to AsyncData/AsyncError; the View switches exhaustively and localizes the Failure at the presentation edge — never a raw exception string. (See error-handling-typed-results.)
12. Register in the ONE go_router with a typed route; identity rides in path params. Add a TypedGoRoute/GoRouteData; carry deep-linkable identity in path params (:taskId), never state.extra (null on cold start/OS restore). Full-screen add/edit flows set parentNavigatorKey: rootNavigatorKey. The router itself — shell/branch structure, redirect/auth guards, deep links, transitions — is owned by navigation-and-routing; this feature only registers its route into it.
13. Navigate from the View or a router redirect — never from the ViewModel. The controller publishes state; the View or a redirect decides what is on screen. A controller that pushes a route couples logic to navigation and breaks headless tests.
14. Inject "now"; never call DateTime.now() in a feature. The ViewModel reads a Clock provider so a whole flow is assertable with a pinned fake clock. (See async-safety.)
15. Directional geometry and localized strings only. EdgeInsetsDirectional/AlignmentDirectional — never .left/.right, Alignment.centerLeft, or TextAlign.left. Every user-facing string comes from gen-l10n across all locale ARBs with key + placeholder parity. (See i18n-rtl-l10n.)
16. Test the ViewModel by faking the repository, not the Notifier. ProviderContainer.test() + overrideWith a fake repository and clockProvider.overrideWithValue(Clock.fixed(t)); no widget pump; verify wiring and UI-state mapping only. (See testing-strategy.)