Upgrading
An Arkstack application has two parts that age differently. The @arkstack/* packages are ordinary npm dependencies you can update. The files create-arkstack copied from a starter template (src/core, src/config, src/routes and so on) now belong to your project, and an update to the packages doesn't touch them. Upgrading means updating the packages and then bringing over the template changes your app needs.
Each release has one version number for every @arkstack/* package and every template. See Versioning and Releases for how versions are chosen.
Find your current version
Your Arkstack version is the version of the @arkstack/* packages in package.json:
{
"dependencies": {
"@arkstack/common": "^0.21.0",
"@arkstack/driver-express": "^0.21.0"
}
}The installed version is in node_modules/@arkstack/common/package.json.
Upgrade steps
Read the release notes for every version between yours and the target in the changelog, and the matching sections in Version notes below.
Update every
@arkstack/*package to the same version. Mixing versions is not supported.shpnpm up "@arkstack/*@^0.22.0"shnpm i @arkstack/common@^0.22.0 @arkstack/console@^0.22.0 # ...every @arkstack package you useshyarn up "@arkstack/*@^0.22.0"Update the companion libraries the release was tested with. Their versions are in the
catalogsection ofpnpm-workspace.yamlat the release tag: resora, kanun, arkormx, clear-router, parasito and your runtime (express, h3 or fastify).Compare the template at your old and new versions (see below) and copy over the changes your app needs.
Publish any new stubs or migrations the release added with
pnpm ark publish --list, then run your migrations.Run your type check, tests and a production build.
Upgrade one minor version at a time when you are several versions behind. Breaking changes only land in minor releases, and each one has notes below.
Comparing template versions
Every release is tagged in the arkstack repository by its version, without a v prefix. The templates live in templates/express, templates/h3 and templates/fastify.
Download both versions of your template and compare them:
npx giget gh:arkstack-hq/arkstack/templates/express#0.21.0 .upgrade/old
npx giget gh:arkstack-hq/arkstack/templates/express#0.22.0 .upgrade/new
diff -ru .upgrade/old .upgrade/newOr, in a clone of the repository:
git diff 0.21.0 0.22.0 -- templates/expressA few things to keep in mind when reading the diff:
- The template's
package.jsonusesworkspace:^andcatalog:versions. Use the versions from step 2 and 3 instead. - Lean projects don't have the database, API and auth files that
create-arkstackremoves, so skip changes to them. - Inertia files come from
packages/inertia/stubs. Compare that folder for changes to the Inertia setup. - Formatting-only changes, like the move to Prettier in 0.20.0, can be ignored.
Version notes
These notes cover what an existing application has to do. New features that need no change are in the changelog.
Unreleased
Plugins need no change to install or to add ark commands. To let them hook into the driver setup through driver:prepare, replace the four driver calls in boot() in src/core/app.ts with driver.prepare():
// Load public assets, middleware, routes and the error handler
await this.driver.prepare(this.app, {
publicPath: path.join(Arkstack.rootDir(), 'public'),
middleware: config('middleware') as never,
})On H3 the template passes publicPath: 'public'. On Fastify, keep the call inside the if (!this.prepared) guard. See Plugins.
0.21 to 0.22
No changes are needed for Express and H3 apps.
- Fastify is a new runtime with its own template. There is no migration path from Express or H3 to Fastify; see Fastify Runtime to start one.
- Update resora to
^1.3.36,@resora/plugin-clear-routerto^1.0.73and clear-router to^2.9.4. - Since resora 1.3.35 (Arkstack 0.21.1), resora's CLI is imported from
resora/cli, and@h3ravel/musketis an optional peer dependency. Templates already list musket. If your code importedCliApp,MakeResourceorInitCommandfromresora, import them fromresora/cli.
0.20 to 0.21
0.21 adds localization with @arkstack/lang. To use it:
Install
@arkstack/lang.Register its helpers in
src/core/bootstrap.ts:tsimport '@arkstack/lang/setup'Add the locale middleware to the
beforelist insrc/config/middleware.ts. UselocaleMiddleware()on Express andh3LocaleMiddleware()on H3, both from@arkstack/lang.Add your translations under
src/lang/{locale}, starting withsrc/lang/en/messages.ts.
0.19 to 0.20
Hook.set(),Hook.unset(),Hook.getAll()and calling a hook throughHook.get(name, pos, ...args)are deprecated. UseHook.on(),Hook.off(),Hook.all()andHook.emit(). The old names still work.@arkstack/commonnow re-exportsHookfrom@arkstack/foundry. If you declare typed hook names by augmentingHookRegistry, augment@arkstack/foundry; an augmentation of@arkstack/commonno longer has any effect.- On H3, remove the
// @ts-expect-erroraboveapplyMiddleware()insrc/core/app.ts. Config types no longer need it since 0.19.1, and TypeScript reports the unused directive. - The templates are formatted with Prettier. Reformatting your app is optional.
0.18 to 0.19
src/config/notifications.tsgained settings for the new realtime transports:realtime.push, the Firebasewebblock, thefirebase-databasetransport and thepollingtransport. Copy the parts you use from the template.UserNotificationCenter.send()andNotification.db().broadcast()now broadcast on the user's channel instead of their push tokens. Apps on thefirebasetransport still reach devices, because device push stays on unlessdrivers.realtime.pushisfalse.- On H3, import
H3Middlewarefrom@arkstack/driver-h3/typesinsrc/core/app.ts. - Since 0.18.9,
env()returns a number only when the value reads exactly as that number. Values such as'0x1f','007'or'1e5'are now returned as strings. Convert them yourself if your config relied on the old behaviour.
