Updating an app

Every @ng-native/* package is released together, at one version. When a release changes something an app has to change too, such as an import path, it ships a migration that makes the change for you. The migrations live in @ng-native/migrate, and all three ways to update run the same ones:

The app is in Update with
An Nx workspace nx migrate @ng-native/nx@latest
An Angular CLI workspace ng update @ng-native/schematics
A plain Expo app (or both) npx @ng-native/migrate@latest

Start from a clean git working tree, so git diff shows exactly what the update changed.

A plain Expo app

An app made with create-expo-app --template @ng-native/template has neither Nx nor the Angular CLI. Run the migrations with npx, before installing the new versions:

npx @ng-native/migrate@latest
npm install

It reads the @ng-native/* version the app's package.json lists, runs every migration newer than that version, oldest first, and moves the @ng-native/* versions in package.json to the new release. It prints each migration it runs, each file it changed (UPDATE), and anything left for you to do (NOTE). Run the install it names afterwards.

npx @ng-native/migrate@latest --dry-run       # print what would change, write nothing
npx @ng-native/migrate@latest --from 0.2.0    # the version the app was on
npx @ng-native/migrate@latest apps/mobile     # an app in another directory

If the new versions are already installed, package.json already lists them, and the command finds nothing to migrate. Pass the version the app was on with --from to run the migrations since then.

An Nx workspace

nx migrate @ng-native/nx@latest
pnpm install
nx migrate --run-migrations
pnpm install

The first command moves every @ng-native/* package in the root package.json and writes the migrations the update crosses into migrations.json, without changing any code yet, so you can read the list first. --run-migrations runs them and prints what is left to do as next steps. See Nx for the workspace setup.

An Angular CLI workspace

ng update @ng-native/schematics

ng update moves every @ng-native/* package in the root package.json, installs them, and runs the migrations the update crosses. What is left to do is printed as a warning. To run the migrations again for an update already installed, name the versions:

ng update @ng-native/schematics --migrate-only --from 0.2.0 --to 0.3.0

See Angular CLI for the workspace setup.

What the migrations do

Migration Runs on What it changes
sync-app-versions Every update Moves the @ng-native/* versions in every package.json in the workspace, an app's own included, to the new release. A ^ or ~ stays; a workspace: or file: link and a peer range are left alone.
split-store-and-player Updating to 0.3.0 Imports Storage from @ng-native/expo/async-storage, SecureStorage from @ng-native/expo/secure-store, audioPlayer from @ng-native/expo/audio and videoPlayer from @ng-native/expo/video, which used to come from @ng-native/expo/store and @ng-native/expo/player. A namespace import, export *, require(), import() or a test's vi.mock of the old entry point is left as it was, with a note.
engine-node-tag Updating to 0.14.0 Reads an engine node's element tag as tag, which was name, on EngineNode, StyleTarget, ViewNameNode and NamedHostNode from @ng-native/fabric and BrowserNode from @ng-native/web. A .name is rewritten only where the code shows what it is read from is one of those: a name typed as one, a node's parent or children, or the nativeElement of an ElementRef<EngineNode>. Each other nativeElement.name, each name read from a node cast to another type (node as { name?: string }, which still compiles), and each .name it cannot place in a file that imports one of those types, is left as it was, with a note.
engine-node-fields Updating to 0.17.0 Reads an engine node's children, text, kind, host and sheet as childList, nodeText, nodeKind, engine and templateSheet, on EngineNode, HostNode, StyleTarget and ViewNameNode from @ng-native/fabric and BrowserNode from @ng-native/web. A read is rewritten only where the code shows what it is read from is one of those, as for engine-node-tag. Each other read from a nativeElement, each read from a node cast to another type, and each it cannot place in a file that imports one of those types, is left as it was, with a note. A node's props keep their names, props['text'] included, and are left alone.
library-typecheck-declaration-map Updating to 0.17.1 Sets declarationMap to false in each tsconfig.typecheck.json that @ng-native/nx:library wrote (one that extends the library's tsconfig.lib.json and has Angular compiler options; an app's is left alone), where Nx's TypeScript preset turns declaration maps on and ngc stopped with TS5069. A config that sets declarationMap itself is left as it is, and one with comments is left with a note.
native-typecheck-target Updating to 0.17.1 Gives each Angular Native project in angular.json a typecheck target, which ng run <project>:typecheck runs: ngc on the project's code and templates, after loading its Metro config. A project with a typecheck target of its own keeps it. An angular.json with comments or trailing commas is left as it is, with a note saying what to add. Nx and plain Expo apps, which have no angular.json, are left alone.
stop-watching-conditions Updating to 0.17.2 Keeps what watchConditions(app.engine) returns in each file that imports it from @ng-native/device, as const stopWatching = watchConditions(app.engine);, and stops it as the app is destroyed with app.applicationRef.onDestroy(stopWatching). Only a call that is a statement of its own and reads its engine off a named app is rewritten. One given an engine some other way (watchConditions(engine), this.engine), or in a file that already has a stopWatching, is left as it was, with a note.
vitest-tsconfig-paths Updating to 0.18.1 In each vitest.config.mts that runs ngNative() and imports nxViteTsPaths from @nx/vite, as @ng-native/nx wrote it in a workspace with tsconfig path aliases, imports tsconfigPaths from vite-tsconfig-paths in its place, since from Nx 24 nxViteTsPaths is a stub that resolves nothing and a test importing a library fails with Cannot find package. Adds vite-tsconfig-paths to the root package.json when it lists none. Another Vitest config is left as it is.

A migration changes only what it can change safely. Where it finds something it cannot rewrite on its own, it leaves the file as it was and prints a note saying which file and line to change, and how. A migration that runs a second time changes nothing.

What is left to do by hand

  • Install. Run the install the update prints, so the new versions are in node_modules.
  • The notes. Make each change a NOTE line or a printed next step asks for.
  • Rebuild the native app when the update adds or moves a native module: a development build and Expo Go carry only the native modules they were built with. See Deployment.
  • Read the changelog for the release, on the releases page, for changes no migration covers.

Angular components as native iOS and Android views, built and shipped with Expo.

An alpha. MIT licensed. Sponsor its development.

An independent project, not affiliated with or endorsed by Google, the Angular team or Expo. Angular is a trademark of Google LLC.