Installing Apex Stem
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 for | New projects, production orgs | Existing projects already on submodules, contributors |
| Framework tests in your deploys | Excluded from RunLocalTests — your validates never run (or fail on) framework tests | Run as local tests in every RunLocalTests deploy |
| Org coverage calculation | Framework code excluded | Framework code and tests included |
| Version visibility | sf package installed list shows the exact version | Read the submodule's git tag |
| Upgrade | Install the next version (in place) | git submodule update --remote |
| Directory layout | Flat 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
| Framework | Version | Install command |
|---|---|---|
| ApexEloquent | v4.0.0 | sf package install -p 04tgK000000ZPwPQAW -o <your-org> -w 10 |
| ApexBlueprint | v2.2.0 | sf package install -p 04tgK000000V4KHQA0 -o <your-org> -w 10 |
| ApexTrace | v1.6.0 | sf package install -p 04tgK000000V3zJQAS -o <your-org> -w 10 |
| ApexTools | v1.2.0 | sf 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
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 listcan lag behind
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
installedEditableclasses asunmanagedand 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:
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
- New to the stack? Start with Get Started with Apex Stem
- Per-framework guides: ApexEloquent / ApexBlueprint / ApexTrace / ApexTools