Upgrading — Noderyx Documentation

01

What the updater touches

The updater changes only the noderyx-framework dependency in package.json and package-lock.json. Your application is left alone.

Not modified: app/ controllers, models, middleware, observers, commands.
Not modified: resources/views/, routes, database/, public/.
Not modified: .env or noderyx.config.js.
Modified: the framework dependency and the lockfile entry for it.

02

Preview first

A dry run reports the intended change without modifying manifests or installing anything.

TERMINAL

npx noderyx update --dry-run
npx noderyx update 0.2.1 --dry-run

03

Update to the latest release

The npm script and the direct command do the same thing.

TERMINAL

npm run framework:update
# or
npx noderyx update

04

Pin an exact version

Provide a version or an npm dist-tag. Use an exact version in production when deployments must be repeatable.

TERMINAL

npx noderyx update 0.2.1
npx noderyx update next

05

The safety sequence

Every update follows the same seven steps, and stops at the first failure.

Read the current framework dependency.
Run the project's test script, when one is defined.
Back up package.json and package-lock.json.
Install the requested release.
Verify that noderyx-framework imports successfully.
Run the project tests again against the new version.
Keep the update only when verification succeeds.

NOTE

If installation, the import check, or the post-update tests fail, the previous manifest and lockfile are restored and reinstalled automatically.

06

Backups

Manifests are copied before anything is installed, timestamped so several attempts never overwrite each other.

PROJECT

.noderyx/update-backups/2026-08-02T04-02-27-428Z/
  package.json
  package-lock.json

NOTE

Newly generated projects already ignore this directory in Git.

07

Projects without tests

The import check still runs, but it can only prove the framework loads—not that your application still behaves. Tests can be skipped explicitly when you must.

TERMINAL

npx noderyx update --no-test

NOTE

Add tests for your important routes before a major-version upgrade. The updater protects dependencies, not untested behavior.

08

Locally linked frameworks

Projects created with --local use a file: dependency. The normal update command refreshes it while keeping the configured path, which is the fastest loop when you are fixing the framework itself.

TERMINAL

npm run framework:update

09

A release workflow that holds up

For a production application, the update itself is the smallest part of the job.

Commit or back up the application first.
Run npx noderyx update --dry-run.
Update in a branch or a staging environment.
Run the complete test suite.
Start the app and exercise its critical routes by hand.
Rebuild every delivery target you ship: web, mobile, native.
Deploy only after verification succeeds.

TERMINAL

npm test
npm run build
npm run build:mobile
npm run build:native

10

Recovering manually

Automatic rollback normally handles this. If a process was interrupted mid-update, restore the newest backup and reinstall.

TERMINAL

# copy package.json and package-lock.json back from
# .noderyx/update-backups/<newest>/ then:
npm install --ignore-scripts

NOTE

Application source never needs restoring, because the updater never changes it.

11

Major versions

Major releases may intentionally change framework APIs. Read the release notes first, upgrade one major version at a time, and add tests for important user flows before starting.

NOTE

The updater detects failing tests and protects dependency state, but it cannot prove that untested behavior is compatible.