ImBenjiandClaude Opus 5.5
21c380595f
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013F4NWNvYcdeSgqbWMT1VQ7
147 lines
4.5 KiB
Markdown
147 lines
4.5 KiB
Markdown
# Local development
|
|
|
|
How to edit the SDKs and an app at the same time, and see the change in the
|
|
running app straight away — no push, no tag, no `ref:` bump while you iterate.
|
|
|
|
|
|
## The setup
|
|
|
|
Your app keeps depending on the SDKs the normal way, as pinned git deps (see
|
|
[Install](../README.md#install)):
|
|
|
|
```yaml
|
|
dependencies:
|
|
garage_ui:
|
|
git:
|
|
url: https://git.imbenji.dev/IMBENJI.NET/Garage-SDKs.git
|
|
path: garage_ui
|
|
ref: b2692019197e60d44ddd3ecab4917caf71ff45c3 # v0.1.0
|
|
```
|
|
|
|
Leave that alone. Clone this repo somewhere, then next to the app's
|
|
`pubspec.yaml` add a `pubspec_overrides.yaml` that points the packages you're
|
|
working on at the local checkout:
|
|
|
|
```yaml
|
|
# local garage sdks, so edits hot reload without a push. gitignored, never commit
|
|
dependency_overrides:
|
|
garage_ui:
|
|
path: ../Garage-SDKs/garage_ui
|
|
```
|
|
|
|
The path is relative to the app's folder, so adjust it to wherever your checkout
|
|
actually lives. If there's a space anywhere in it, quote it:
|
|
|
|
```yaml
|
|
path: "../../Documents/Projects/Garage Services/SDKs/garage_ui"
|
|
```
|
|
|
|
pub reads `pubspec_overrides.yaml` on its own, you dont pass it anything. Run
|
|
`flutter pub get` and you should see a line per override:
|
|
|
|
```
|
|
! garage_ui 0.1.0 from path ../Garage-SDKs/garage_ui (overridden in ./pubspec_overrides.yaml)
|
|
```
|
|
|
|
If that line isn't there, the override isn't active — check the path.
|
|
|
|
|
|
## Overriding auth, entitlements or iap
|
|
|
|
`garage_entitlements` and `garage_iap` both depend on `garage_auth` by path
|
|
(`path: ../garage_auth` in their pubspecs). So the moment you override either
|
|
one, the local copy pulls in a local `garage_auth` too — and your app is still
|
|
asking for the git one. pub sees `garage_auth` from two sources and refuses.
|
|
|
|
The rule: **if you override `garage_entitlements` or `garage_iap`, override
|
|
`garage_auth` as well.**
|
|
|
|
```yaml
|
|
dependency_overrides:
|
|
garage_auth:
|
|
path: ../Garage-SDKs/garage_auth
|
|
garage_entitlements:
|
|
path: ../Garage-SDKs/garage_entitlements
|
|
garage_ui:
|
|
path: ../Garage-SDKs/garage_ui
|
|
```
|
|
|
|
`garage_ui` doesnt depend on any of the others, so it can be overridden on its
|
|
own.
|
|
|
|
|
|
## Hot reload
|
|
|
|
- Changed `pubspec_overrides.yaml` (added, removed, or edited a path)? Run
|
|
`flutter pub get`, then do a full restart of the app. Hot reload wont pick up
|
|
a dependency swap.
|
|
- After that, edits inside the SDK checkout behave like your own app code. Save
|
|
and hot reload.
|
|
- Same caveats as app code: if the change is in something that only runs once
|
|
(`main()`, initial state, a `const` widget tree), hot restart instead.
|
|
|
|
|
|
## Gitignore it
|
|
|
|
Add this to the app's `.gitignore`:
|
|
|
|
```
|
|
pubspec_overrides.yaml
|
|
```
|
|
|
|
The path in it only exists on your machine. Commit it and every other checkout
|
|
breaks, and so does any CI job or Docker image build, because none of them have
|
|
your local SDK checkout sitting next to the app.
|
|
|
|
While the override is active, `pubspec.lock` records the path source instead
|
|
of the git one. Thats expected. Just dont ship a lockfile in that state — see
|
|
below.
|
|
|
|
Also: never edit the copies under `~/.pub-cache/git`. pub treats that folder as
|
|
disposable and will overwrite or delete it without asking, and your app isn't
|
|
necessarily even reading from the copy you changed. Edit a real checkout and
|
|
override to it.
|
|
|
|
|
|
## Shipping an SDK change
|
|
|
|
Once the change works locally:
|
|
|
|
1. Commit and push it in this repo.
|
|
2. Tag a new version, e.g. `v0.1.1`, and push the tag.
|
|
3. In each app that should get it, bump `ref:` to the new tag's full commit hash. Do it on purpose,
|
|
per app — dont float `main`.
|
|
4. Check the app builds **without** the override. Move it aside, resolve against
|
|
the real tag, and analyze:
|
|
|
|
```sh
|
|
mv pubspec_overrides.yaml pubspec_overrides.yaml.off
|
|
flutter pub get
|
|
flutter analyze
|
|
```
|
|
|
|
This is the step that catches a forgotten push, a tag on the wrong commit, or
|
|
a `ref:` you missed. It also puts `pubspec.lock` back on the git source.
|
|
5. Deploy, then move the override back if you're carrying on.
|
|
|
|
|
|
## Running the SDKs' own tests
|
|
|
|
These have tests:
|
|
|
|
```sh
|
|
cd garage_entitlements && flutter test
|
|
cd garage_iap && flutter test
|
|
cd garage_ui && flutter test
|
|
```
|
|
|
|
`garage_auth` has no `test/` dir yet.
|
|
|
|
There are two examples, both minimal wiring references rather than full apps:
|
|
|
|
- `garage_auth/example/main.dart` — a single file showing `GarageAuth` wired
|
|
into an app. It has no pubspec of its own.
|
|
- `garage_iap/example` — a small package wiring `garage_auth` + `garage_iap`
|
|
together by path. `flutter pub get` and `flutter analyze` in there is a quick
|
|
way to check the two still fit together.
|