Managed Package Extension
A Managed Package Extension is a separate managed package that extends or builds on top of another managed package, treating the underlying package as a dependency.
Definition
A Managed Package Extension is a separate managed package that extends or builds on top of another managed package, treating the underlying package as a dependency. The extension package can reference objects, fields, Apex classes, and components from the base package and add its own components alongside them. AppExchange ISVs use the extension pattern to ship add-on products that augment a base product without forking it: an extension to a CPQ package adds industry-specific pricing logic; an extension to a contract-management package adds e-signature integration.
Extensions are a first-class concept in the Salesforce packaging model. The extension declares its dependency on the base package; customers must install the base package before installing the extension. Salesforce enforces install order and version compatibility automatically. The extension can reference (but not modify) the base package''s metadata: Apex classes via global methods, custom objects via fields and lookups, Lightning components via inheritance. The base package author cannot prevent extensions from existing; the extension model is open by design, which is what enables the multi-vendor AppExchange ecosystem.
How Managed Package Extensions let ISVs build on top of other ISVs cleanly
How the extension declares its base dependency
When building the extension package, the publisher declares the base package as a Required Package in the package metadata. 2nd-Generation packages use sfdx-project.json''s dependencies block; 1st-Generation packages use the legacy packaging UI. The dependency includes the base package''s ID and minimum version. Salesforce installs check the dependency at install time; if the base is missing or older than the required version, the install fails with a clear dependency error.
What an extension can and cannot do
Can: reference base package objects via lookups, call base package global Apex methods, extend base Lightning Web Components, deploy new fields onto base custom objects (subject to FLS), add new objects and components alongside the base. Cannot: modify base package internals (the namespace and managed protection block edits), call private Apex methods of the base, override base validation rules without explicit base-package hooks, or remove base functionality. The constraints protect base-package integrity while letting extensions add value.
Global Apex and the public API surface
Base packages expose Apex APIs to extensions via the global access modifier. Methods, classes, and interfaces marked global are callable from extension code; package-private and public methods are not. This is the contract the base package commits to maintaining; once global, a method cannot be removed without breaking extensions. Smart base-package authors curate their global surface carefully and document expected usage patterns. Sloppy ones expose too much and lock themselves into backwards compatibility on incidental implementation details.
Version compatibility and the upgrade dance
When the base package releases a new version, extensions may need updating to match. The base package can break extension compatibility via deprecation or API contract changes. The extension''s dependency declaration specifies a minimum base version; running on a newer base version is usually compatible unless the base introduced breaking changes. Extensions should test against major base-version releases and ship updated extension versions that declare the new minimum.
Installing extensions and the order dependency
Customer installs the base package first, then the extension. Trying to install the extension first fails with a Required Package Missing error. AppExchange listings for extensions usually call out the base package requirement prominently to avoid customer confusion. For internal teams shipping multiple Unlocked packages with extension relationships, the Salesforce CLI install commands respect dependency order automatically; manual install via Setup requires the customer to install in order.
Uninstalling: base versus extension
Uninstalling the extension is straightforward; the extension can be removed without affecting the base. Uninstalling the base while the extension is still installed fails; the platform blocks the uninstall to prevent broken references. Customers must uninstall extensions first, then the base. This is the most common base-package-uninstall confusion: an admin tries to clean up a base package and the uninstall fails because forgotten extensions are still referencing it.
AppExchange listings and extension discoverability
Extension packages can list on AppExchange independently. The listing displays the base package as a requirement; customers see "Requires Acme CPQ 5.0 or later" prominently on the listing page. Some ISVs build entire businesses on extending one or two popular base packages (extensions to nCino, extensions to Conga). The extension model is what makes the AppExchange ecosystem layered rather than flat; smaller ISVs can ride on top of bigger ones rather than building from scratch.
Building a Managed Package Extension
Building an extension follows the same packaging workflow as a standalone managed package, with the added step of declaring the base package as a dependency. The base package must be installed in the development org for the extension to compile against it.
- Install the base package in your development org
Get the base package install URL from the publisher or AppExchange. Install in your Partner Org or scratch org. The extension code needs to compile against the base; without it, references to base classes fail.
- Declare the dependency
For 2nd-Gen Managed and Unlocked: add the base package ID and minimum version to sfdx-project.json''s dependencies array. For 1st-Gen: configure in the packaging UI under Setup, Package, Dependencies.
- Build the extension components
Reference base package objects via lookups using the base namespace prefix (acme__Custom_Object__c). Call base global Apex methods using the namespace (acme.UtilityClass.doSomething()). Build new objects and components in your own extension namespace.
- Test against multiple base versions
Test the extension against the minimum supported base version and the latest base version. Major base version upgrades may require extension updates; test in advance.
- Package and distribute
Build the extension version via Salesforce CLI (sf package version create). Submit for AppExchange Security Review if distributing publicly. List on AppExchange with the base package called out as a requirement.
Minimum base version the extension requires. Match to the oldest base version your extension supports; allow newer.
AppExchange listing (most common for paid extensions) or direct install URL for internal or partner-specific distribution.
Extension uses its own namespace, separate from the base. Helps customer-side users distinguish base and extension metadata.
Per-seat licensing layered on top of the base package license. Customers typically pay both base and extension licenses.
- Install order matters. Base package first, then extension. Reversing the order fails with a Required Package Missing error.
- Uninstall order matters in reverse. Extension first, then base. Trying to uninstall the base while extensions reference it fails.
- Extension code can only call global Apex from the base package. Public and protected methods are not accessible across packages.
- Major base version upgrades may break extension compatibility. Test against new base versions before customers upgrade.
- Extension AppExchange listings must call out the base requirement prominently. Customers who miss the requirement install in the wrong order and blame the extension publisher.
Trust & references
Cross-checked against the following references.
- Extension Packages and DependenciesSalesforce Developer Docs
- Define 2nd-Gen Package DependenciesSalesforce Developer Docs
Straight from the source - Salesforce's reference material on Managed Package Extension.
- Apex Access ModifiersSalesforce Developer Docs
- AppExchange Security Review for ExtensionsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Managed Package Extension?
Q2. What can extensions add?
Q3. What's the value of extensions?
Discussion
Loading discussion…