Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

flutter-feature-scaffold

/flutter-feature-scaffold

Dodaje nowe funkcje do aplikacji Flutter w układzie feature-first Clean Architecture (data, domain, presentation) z Riverpod 3 bez generowania kodu, z układem folderów, regułami warstw i skryptem szkieletu.

Licencja
MIT
Ostatnia zmiana repozytorium
02.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/check_boundaries.sh, scripts/scaffold_feature.sh

Co robi i kiedy

Dodaje nowe funkcje do aplikacji Flutter w układzie feature-first Clean Architecture (data, domain, presentation) z Riverpod 3 bez generowania kodu, z układem folderów, regułami warstw i skryptem szkieletu.

Oryginalny opis (EN)

Use when adding a new feature or module to a Flutter app that follows feature-first Clean Architecture (data / domain / presentation) with Riverpod 3 and no code generation for providers, when deciding which layer or folder a file belongs in, or when reviewing dependency direction between layers. Provides the folder layout, per-layer rules, barrel conventions, build order and a scaffold script.

Jak działa

  1. Layout
  2. Dependency direction
  3. Per-layer rules
  4. Build order for a new feature
  5. Scaffold script
  6. Checking the boundaries
  7. Review checklist
Sekcje z nagłówków SKILL.md, w oryginale · 201 linii, 1 121 słów
Podgląd SKILL.md
---
name: flutter-feature-scaffold
description: Use when adding a new feature or module to a Flutter app that follows feature-first Clean Architecture (data / domain / presentation) with Riverpod 3 and no code generation for providers, when deciding which layer or folder a file belongs in, or when reviewing dependency direction between layers. Provides the folder layout, per-layer rules, barrel conventions, build order and a scaffold script.
---

# Feature-first Clean Architecture for Flutter

## Layout

```text
lib/
├── app/            bootstrap, root widget, environment
├── core/           cross-cutting contracts + adapters (network, analytics,
│                   error_tracking, storage, errors, config, logging…)
├── shared/         reusable UI & utils with no business meaning
│                   (routing, theme, widgets, extensions)
├── features/       one folder per business capability
└── l10n/

features/<feature>/
├── <feature>.dart            barrel: exports domain, di, presentation (NOT data)
├── data/                     no Riverpod, no Flutter widgets
│   ├── datasources/          <x>_remote_data_source.dart, <x>_endpoints.dart
│   ├── models/               JSON-aware classes (fromJson / toEntity)
│   └── repositories/         <x>_repository_impl.dart
├── di/
│   └── <feature>_providers.dart   dataSource + repository providers
├── domain/
│   ├── entities/             immutable value classes (Equatable)
│   ├── repositories/         abstract interface class contracts
│   ├── services/             pure domain logic spanning entities
│   └── usecases/             only when logic is shared or non-trivial
└── presentation/
    ├── pages/
    ├── widgets/              includes <Feature>Listeners (side effects)
    ├── providers/            Notifier / AsyncNotifier / FutureProvider
    └── state/                state classes when a notifier needs more than a value
```

Every folder has a barrel named after it (`entities.dart`,
`datasources.dart`, …) that exports its files. Import barrels, not files,
across folders.

## Dependency direction

```text
presentation ──▶ di ──▶ data
      │           │       │
      └──────▶ domain ◀───┘
```

- **Domain** imports nothing from Flutter, Dio, Firebase, Riverpod or any
  platform SDK. Plain Dart + `equatable`.
- **Data** implements domain contracts. It is the only layer that knows JSON,
  endpoints and the `ApiClient`. It does **not** import Riverpod: wiring is
  not its job, so it stays testable in plain Dart.
- **`di/`** is the composition point: the only place that sees `data/` and
  `domain/` together. It builds the data source and repository and exposes
  the repository as its **contract** type (`Provider<FavoriteRepository>`).
- **Presentation** imports `domain/` and `di/`, **never `data/`**. It does not
  call an `ApiClient`, parse JSON or touch SDKs.
- Between features, depend on the other feature's **domain** (or `di/`) only.
  If two features need the same model, promote it to `core/` instead of
  reaching into another feature's `data/` or `presentation/`.

Why `di/` and not "a provider next to the impl": a provider in `data/` forces
presentation to import `data/` just to `ref.watch` it, and the rule
"presentation never imports data" gains an exception that people stretch
(first the provider, then "just this one model"). A dedicated file keeps the
rule absolute, so a script can check it. It also keeps `data/` free of
Riverpod.

Call chain: `Widget → (Async)Notifier → Repository contract → RepositoryImpl
→ RemoteDataSource → ApiClient`. Never skip a layer.

## Per-layer rules

**Entities** — immutable, `extends Equatable`, `const` constructor, no JSON.
Drop wire-only fields (`userId` the client already knows) in `toEntity`.
`Equatable` also makes `ref.watch(p.select(...))` work by value.

**Repository contract** — `abstract interface class`, methods return
`AsyncResult<Entity>` / `AsyncResult<Unit>` (see `flutter-result-errors`).
Signatures use entities and value objects, never models or SDK types.

**Models** — live only in `data/models/`. Factory `fromJson` (via
`json_serializable`), `toEntity()`, and `fromEntity` when the model is sent
back. Entities never import models. Models never leave the repository.

**Endpoints** — one `abstract final class <X>Endpoints` of path constants and
path-building static methods, so URLs are not string literals in data sources.

**Remote data source** — `abstract interface class` + `Impl` that
`with RemoteDataSourceGuard`, takes an `ApiClient`, returns `AsyncResult<Model>`.
No provider in this file.

**Repository impl** — takes the data source, converts models → entities with
`result.map(...)`, passes failures through. No provider in this file.

**`di/<feature>_providers.dart`** — the providers for the two above:

```dart
final favoriteRemoteDataSourceProvider = Provider<FavoriteRemoteDataSource>(
  (ref) => FavoriteRemoteDataSourceImpl(ref.watch(apiClientProvider)),
);

/// Exposes the CONTRACT, never the implementation. Tests override this.
final favoriteRepositoryProvider = Provider<FavoriteRepository>(
  (ref) => FavoriteRepositoryImpl(ref.watch(favoriteRemoteDataSourceProvider)),
);
```

In a test, override the contract and `data/` is never touched:

```dart
ProviderContainer(overrides: [
  favoriteRepositoryProvider.overrideWithValue(FakeFavoriteRepository()),
]);
```

**Providers (presentation)** — one responsibility each. Pick by role:

| Need | Use |
|---|---|
| Immutable dependency (repo, service, client) | `Provider` |
| Async read-only data | `FutureProvider` |
| Continuous stream (auth state, connectivity) | `StreamProvider` |
| Mutable sync state (filters, selected tab) | `NotifierProvider` |
| Mutable async state (a screen's store, a session) | `AsyncNotifierProvider` |
| One user action in flight | `SubmissionNotifier` + `autoDispose` |

Declare providers explicitly. No `riverpod_generator`, no `@riverpod`, no
`StateNotifier`. Business rules that belong in the domain do not live in
providers.

**Pages and widgets** — no JSON, no SDKs, no business rules. Side effects
(navigation, snackbars, analytics) are declared with `ref.listen` in a
`<Feature>Listeners` widget with a `child` parameter that wraps the page;
widgets only `watch` declarative state.

## Build order for a new feature

1. Entity (`domain/entities`)
2. Repository contract (`domain/repositories`)
3. Model with `toEntity` (`data/models`) — then `dart run build_runner build`
4. Endpoints class (`data/datasources`)
5. Remote data source
6. Repository impl
7. `di/` providers (data source + repository, exposed as the contract)
8. Presentation provider (`AsyncNotifier` whose `build` reads the repository
   through `di/` and calls `getOrThrow()`)
9. Submission notifier for each user action
10. `<Feature>Listeners` widget
11. Page + widgets, registered in the router
12. Tests: data source with a fake `ApiClient`, repository mapping, notifier
    with the repository contract overridden, widget test with fakes
13. Run `scripts/check_boundaries.sh`

## Scaffold script

`scripts/scaffold_feature.sh` creates steps 1–8 as compilable stubs with all
barrels, and never overwrites existing files:

```bash
# from the Flutter project root
bash <path-to-skill>/scripts/scaffold_feature.sh favorites --entity Favorite
```

- First argument: feature folder name, `snake_case`.
- `--entity Name`: PascalCase entity (default: the feature name in PascalCase).
- `--package name`: override the package name (default: read from `pubspec.yaml`).

Afterwards: add fields to the entity and model, fill the endpoints, run
`dart run build_runner build` and `dart fix --apply` (the stubs' import order
is not lint-sorted), then continue from step 9.

## Checking the boundaries

`scripts/check_boundaries.sh` is plain `grep`, so it needs no Dart toolchain
and fits in any CI step. Run it from the project root:

```bash
bash <path-to-skill>/scripts/check_boundaries.sh        # default: lib/features
```

It exits 1 and lists every violation of these rules, or prints `OK`:

1. `presentation/` never imports `data/`
2. `domain/` imports no framework or SDK, nor `data/`, `presentation/`, `di/`
3. `data/` imports neither `presentation/`, `di/` nor Riverpod
4. A feature never imports another feature's `data/` or `presentation/`
5. Feature code imports no third-party SDK directly

Run it after every scaffold, and in CI so the boundary cannot erode.

## Review checklist

- [ ] `check_boundaries.sh` prints `OK`
- [ ] `domain/` has no imports from `flutter`, `dio`, `flutter_riverpod`, SDKs
- [ ] `di/` exposes the repository as its contract type, not the `Impl`
- [ ] Repositories return entities, not models; no thrown exceptions
- [ ] Each folder has a barrel; cross-folder imports use barrels
- [ ] Providers are explicit (no codegen) and each has one job
- [ ] Side effects live in the feature's `Listeners` widget
Pliki w paczce (3)
  • SKILL.md 9 KB
  • scripts/check_boundaries.sh 3 KB
  • scripts/scaffold_feature.sh 10 KB

Wersje

W bazie nie ma innych skilli o nazwie flutter-feature-scaffold.

Migawka bazy z 13.11.2026 · wersja paczki 28b7ac596dd8 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100flutter-clean-architect
    Projektuje, szkieletuje, refaktoryzuje i audytuje kod Flutter w Clean Architecture z warstwami domain, infrastructure i presentation, ręcznym Riverpod DI i kontraktami repozytoriów, bez warstwy usecase.
  • 100flutter-architecture
    Podaje wzorce architektury aplikacji Flutter: struktura feature-first, clean architecture i zarządzanie stanem (Bloc, Riverpod, Provider), wstrzykiwanie zależności i dobór podejścia.
  • 100feature
    Buduje nową funkcję Flutter od końca do końca w warstwach domeny, danych i prezentacji, z Riverpod 3, stanami i testami.
  • 100flutter-feature-based-clean-architecture
    Organizuje aplikacje Flutter w modułową architekturę clean opartą na funkcjach, z warstwami domain, data i presentation w katalogu lib/features.
  • 100clean-arch-overview
    Wyjaśnia strukturę aplikacji Flutter w Clean Architecture z Bloc: kształty funkcji, warstwy, kierunek zależności i miejsce na kod.
  • 100clean-arch-new-feature
    Prowadzi przez dodanie nowej funkcji lub ekranu do aplikacji Flutter w Clean Architecture z Bloc: kolejne warstwy, testy i wybór kształtu.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.