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 installIt 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 directoryIf 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 installThe 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/schematicsng 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.0See 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
NOTEline 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.