Installing Apex Stem

•Apex Stem Docs
Apex StemInstallationUnlocked PackageSalesforce
Two install paths for every framework: Unlocked Packages (framework tests excluded from RunLocalTests) and git submodules. Current versions and install IDs.

Every Apex Stem framework ships two ways: as an Unlocked Package (2GP, no namespace) and as a git submodule. Both install the exact same source — pick per project, and you can even mix them across orgs.

Which path should I take?

Unlocked Package (recommended)Git Submodule
Best forNew projects, production orgsExisting projects already on submodules, contributors
Framework tests in your deploysExcluded from RunLocalTests — your validates never run (or fail on) framework testsRun as local tests in every RunLocalTests deploy
Org coverage calculationFramework code excludedFramework code and tests included
Version visibilitysf package installed list shows the exact versionRead the submodule's git tag
UpgradeInstall the next version (in place)git submodule update --remote
Directory layoutFlat right after a retrieve — restore it with npx apex-librarian arrange (see below)Preserved by the submodule itself

The package path exists because framework tests that create real records (ApexBlueprint's integration suite, for example) can collide with org-specific validation rules and required fields. Installed as a package, those tests never run in your deploys or validates — the failure class that blocks a release disappears.

One nuance: when you run sf apex run test -l RunLocalTests by hand, tests from unlocked packages without a namespace are included (the Salesforce CLI help defines RunLocalTests differently for deploys and for manual test runs). Apex Stem's packages are published without a namespace, so a manual run does execute the framework tests. If one fails and its class shows ManageableState = installedEditable, it belongs to the package and you can ignore it.

Current versions

FrameworkVersionInstall command
ApexEloquentv4.0.0sf package install -p 04tgK000000ZPwPQAW -o <your-org> -w 10
ApexBlueprintv2.2.0sf package install -p 04tgK000000V4KHQA0 -o <your-org> -w 10
ApexTracev1.6.0sf package install -p 04tgK000000V3zJQAS -o <your-org> -w 10
ApexToolsv1.2.0sf package install -p 04tgK000000V3xhQAC -o <your-org> -w 10

The frameworks are fully independent — no install order, no cross-dependencies. Install only what you need.

To install from the browser instead, open https://login.salesforce.com/packaging/installPackage.apexp?p0=<install ID> (use test.salesforce.com for sandboxes). Install IDs for older versions are listed on each repository's GitHub Releases page:

ApexEloquent / ApexBlueprint / ApexTrace / ApexTools

Git submodule

BASH
cd /path/to/your/project
git submodule add https://github.com/krile136/ApexEloquent.git  force-app/main/default/classes/ApexEloquent
git submodule add https://github.com/krile136/ApexBlueprint.git force-app/main/default/classes/ApexBlueprint
git submodule add https://github.com/krile136/ApexTrace.git     force-app/main/default/classes/ApexTrace
git submodule add https://github.com/krile136/ApexTools.git     force-app/main/default/classes/ApexTools
git submodule update --init --recursive

sf project deploy start -d force-app/main/default/classes/<Name> deploys each one like any source folder. When cloning a project that uses submodules, remember git clone --recurse-submodules.

Switching from submodules

If your org already has the frameworks deployed from submodule source, you don't need to delete the existing classes before installing the packages. When an unmanaged class with the same name exists, the package takes over its ownership at install time (ManageableState changes from unmanaged to installedEditable).

  • Install one at a time, smallest first (ApexTools → ApexTrace → ApexBlueprint → ApexEloquent). Install them all at once and you can't isolate the cause when something fails
  • Installing does not run all the tests in your org. Measured runs finished in tens of seconds to a few minutes per package, even in a production org
  • Verify with ManageableState. sf package installed list can lag behind
BASH
sf data query -o <your-org> --use-tooling-api -r csv \
  -q "SELECT ManageableState, COUNT(Id) c FROM ApexClass WHERE NamespacePrefix = null GROUP BY ManageableState"

⚠️ Once the package has taken over, stop including the submodules in your deploys. If you do, you overwrite the installedEditable classes as unmanaged and the state rolls back. Keeping the submodules in the repository as a source reference and a record of the version is enough.

Restoring the directory layout

Salesforce orgs have no concept of folders for Apex classes, so classes installed as a package arrive flat in classes/ when you pull them down with sf project retrieve.

As of the versions in the table above (ApexEloquent v4.0.0 / ApexBlueprint v2.2.0 / ApexTrace v1.6.0 / ApexTools v1.2.0), every class declares its own location in an @directory doc-comment tag. After a retrieve, one run of the npm module ApexLibrarian restores the exact directory hierarchy a submodule install would give you:

BASH
npx apex-librarian arrange

Each .cls-meta.xml always moves together with its class. For how it works and the other commands (check / stamp), see the ApexLibrarian page.

Next steps