# Upgrading @gauntlet packages (/docs/ship/upgrading)



Platform upgrades are deliberate events, not routine dependency bumps. All `@gauntlet/*` packages [version in lockstep](/docs/concepts/package-ecosystem), so you move the whole set to one new version, verify, and release.

<Steps>
  <Step>
    ## Check the changelog [#check-the-changelog]

    Read the [changelog](/docs/changelog) for every version between yours and the target. Look specifically for breaking changes and native-dependency changes. The latter decide whether this upgrade needs a store release.
  </Step>

  <Step>
    ## Bump the whole set [#bump-the-whole-set]

    Update **every** `@gauntlet/*` entry in `package.json` to the target version, plus the Appbrew-published `@app-brew/*` native modules and build tooling, which carry the same platform version. Then:

    ```bash
    pnpm install
    ```

    Never leave a mixed set. One package ahead of the rest is unsupported.
  </Step>

  <Step>
    ## Rebuild native projects [#rebuild-native-projects]

    ```bash
    pnpm clean-ios && pnpm run-ios
    pnpm run-android
    ```

    iOS pod installs and Android Gradle builds pick up native changes here. If either fails, check [Troubleshooting](/docs/ship/troubleshooting) before assuming the upgrade is broken.
  </Step>

  <Step>
    ## Verify the app [#verify-the-app]

    Boot on both platforms and walk the core flows: home, product page, add to cart, checkout entry, plus every custom block and integration your app relies on. Custom blocks compile against the new `@gauntlet/types` — fix any type errors they surface.

    <Callout type="warn" title="Moving to 0.27.0">
      Two removals bite at compile time: the PLP product-card registration
      helpers are gone (register cards by variant instead), and a custom
      `ICatalogProvider` now needs three more methods. Details in the
      [0.27.0 notes](/docs/changelog/0-27-0#breaking).
    </Callout>
  </Step>

  <Step>
    ## Release [#release]

    If the upgrade changed native code (it usually does), [request a store release](/docs/ship/app-releases). Config-only follow-ups ship from the dashboard as usual.
  </Step>
</Steps>

<Callout type="info" title="When to upgrade">
  Appbrew will tell you when a platform version matters for your app: a fix
  you need, an integration you want, or a deprecation. You don't have to take
  every release. When you do upgrade, move the whole set.
</Callout>