@trackunit/migrations

Coordinator library that discovers installed @trackunit/* packages, updates their versions, and runs pending migrations.

How it works

Each published @trackunit/* package can declare a "migrations" field in its package.json pointing to a migrations.json manifest. This library recursively scans node_modules (including nested/transitive dependencies) to find all such packages, then follows a two-step flow modeled after nx migrate:

1. migrate -- discovers packages, updates package.json versions, writes pending migrations to trackunit-migrations.json
2. run-migrations -- executes the pending migrations from that file, then clears the list

Version state is tracked in trackunit-migrations.json so migrations that have already been applied are not re-run.

flowchart TD
  subgraph step1 [Step 1: nx g @trackunit/migrations:migrate]
    scan["Recursively scan node_modules\nfor @trackunit/* packages"]
    scan --> checkField{"package.json\nhas migrations field?"}
    checkField -->|No| skipPkg[Skip package]
    checkField -->|Yes| loadManifest["Load migrations.json"]
    loadManifest --> readState["Read trackunit-migrations.json\nfor migratedVersions state"]
    readState --> filterVersion{"migration.version >\nlastMigratedVersion?"}
    filterVersion -->|No| skipMigration[Skip migration]
    filterVersion -->|Yes| collect["Add to pending list"]
  end

  subgraph updatePkg [Version Updates]
    scan --> compareDeps{"Installed version >\npackage.json version?"}
    compareDeps -->|Yes| bumpDep["Update version in\nconsumer package.json"]
    compareDeps -->|No| noop[No change]
  end

  collect --> writeFile["Write trackunit-migrations.json\nwith pending migrations +\nupdated migratedVersions"]

  subgraph step2 [Step 2: nx g @trackunit/migrations:run-migrations]
    readFile["Read trackunit-migrations.json"] --> loop["For each pending migration"]
    loop --> importImpl["Import migration implementation"]
    importImpl --> execute["Execute migration against NX Tree\n(AST transforms, file rewrites)"]
    execute --> clearPending["Clear pending list\nPreserve migratedVersions"]
  end

  writeFile --> review["Developer reviews\ntrackunit-migrations.json"]
  review --> readFile

flowchart LR
  subgraph nodeModules ["node_modules (recursive scan)"]
    rc["@trackunit/react-components\nv2.0.0\nmigrations: ./migrations.json"]
    rcc["@trackunit/react-chart-components\nv1.20.0\nmigrations: ./migrations.json"]
    su["@trackunit/shared-utils\nv1.13.0\n(no migrations field)"]
    nested["some-lib/node_modules/\n@trackunit/react-components\nv1.21.8 (older, deduped out)"]
  end

  subgraph migrationsFiles [migrations.json per package]
    rcMig["react-components/migrations.json\n- rename-button-kind (v1.22.0)\n- button-required-variant (v2.0.0)"]
    rccMig["react-chart-components/migrations.json\n- chart-api-v2 (v1.20.0)"]
  end

  subgraph output [trackunit-migrations.json]
    pending["migrations:\n- rename-button-kind\n- button-required-variant\n- chart-api-v2\n\nmigratedVersions:\n  react-components: 2.0.0\n  react-chart-components: 1.20.0"]
  end

  rc --> rcMig
  rcc --> rccMig
  su -.->|skipped| nodeModules
  nested -.->|deduped| rc
  rcMig --> pending
  rccMig --> pending

Usage

Step 1: Discover and collect migrations

nx g @trackunit/migrations:migrate

This updates @trackunit/* dependency versions in your package.json and writes a trackunit-migrations.json file listing any pending migrations. Review the file before proceeding.

Step 2: Run pending migrations

nx g @trackunit/migrations:run-migrations

This executes each migration listed in trackunit-migrations.json and clears the pending list. You can delete the file afterward or keep it for version tracking.

Internal monorepo

yarn nx g @trackunit/migrations:migrate
yarn nx g @trackunit/migrations:run-migrations

For more info and a full guide on Iris App SDK Development, please visit our Developer Hub.

Trackunit

This package was developed by Trackunit ApS.

Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.