Garage-SDKs/docs/local-development.md

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):

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:

# 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:

    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.

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:

   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:

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.