Salesforce Managed Packages & AppExchange Guide — SFX Support

1. Introduction to Salesforce Packaging

In Salesforce development, once you've built custom functionalities like Apex code, Lightning Web Components, custom objects, or flows, you often need to move these customizations between different Salesforce environments or distribute them to other organizations. This is where Salesforce Packaging comes in.

Salesforce packaging allows you to bundle your metadata into deployable units. These packages can then be installed into other Salesforce organizations, streamlining distribution, deployment, and version management of your applications or components.

Why is Packaging Important?

• Distribution: Easily share your custom solutions with other Salesforce organizations.
• Version Control: Manage different versions of your application or components.
• Deployment: Simplify the process of moving changes across environments or to customers.
• Intellectual Property Protection: For commercial applications, protect your source code.
• Modularity: Break down large implementations into smaller, manageable, and reusable units.

This module covers the different types of Salesforce packages — Unmanaged, Managed (1GP and 2GP), and Unlocked Packages — highlighting their characteristics, use cases, and how to create them.

2. Unmanaged Packages

Unmanaged packages are the simplest type and are primarily used for distributing open-source projects, templates, or small self-contained applications. Think of them as a "copy-paste" mechanism for Salesforce metadata.

Key Characteristics

• Editable: All components (Apex, LWC, custom objects, etc.) are fully customizable by the installing organization.
• No Upgrade Path: No built-in mechanism for the original developer to push updates. Recipients must manually re-deploy changes.
• No IP Protection: Source code of Apex classes, Visualforce pages, etc. is visible and accessible after installation.
• No Namespace: Components have no unique namespace prefix — higher risk of naming conflicts in the installing org.
• Deletion: Uninstalling removes the package container, but installed components remain. You must manually delete them.

Use Cases

• Sharing sample code or templates with other developers.
• Distributing open-source projects or utilities.
• Providing a starting point for a customer's implementation that they will heavily customize.
• Migrating components between non-related developer orgs.

How to Create — Salesforce UI

1. Log in to your Developer Edition or Sandbox org where your customizations reside.
2. Go to Setup.
3. In the Quick Find box, type Package Manager and select Package Manager.
4. Click New under "Unmanaged Packages".
5. Provide a Package Name (e.g., "MyUtilityComponents") and optionally a description. Click Save.
6. On the Package Detail page, click Add Components.
7. Select the Component Type and the specific components to include. Click Add To Package. Repeat for all components.
8. Once all components are added, click Upload. Salesforce provides an installation URL to share.

SFDX CLI Context

The SFDX CLI does not have a direct command to create an unmanaged package container. The typical workflow involves developing in a scratch org or sandbox, then using the Salesforce UI Package Manager in that org to create the package.

# Develop your customizations in a scratch org or sandbox.
# Pull the source to your local SFDX project:
sf project retrieve start -o myDevOrg

# Then use the Salesforce UI (Package Manager) in that same org
# to create the unmanaged package, selecting the components
# now present in the org from your SFDX project.

3. Managed Packages (1st Generation & 2nd Generation)

Managed packages are the cornerstone for Salesforce ISVs (Independent Software Vendors) to distribute and sell applications on the AppExchange. They offer intellectual property protection, upgrade capabilities, and a unique namespace.

Key Characteristics (Common to 1GP and 2GP)

• Protected Components: Source code of Apex classes, Visualforce pages, and other IP is hidden from the installing organization. Components are not editable after installation.
• Upgrade Path: Package developers can push upgrades to installed managed packages — customers receive new features and bug fixes.
• Unique Namespace: All components have a unique namespace prefix (e.g., mycompany__MyComponent__c), preventing naming conflicts.
• AppExchange Distribution: Required for listing applications on the Salesforce AppExchange.
• Version Control: Strong versioning capabilities for clear release management.

a. 1st Generation Managed Packages (1GP)

The traditional approach to managed packaging, developed in a single Developer Edition org (the "packaging org"). An org-centric development model where all components for the package must reside in this one org.

• Limitations: Difficult to manage for large, modular applications; limited integration with modern source control; no scratch org support; harder dependency management.

Creation (High-Level — via Salesforce UI in a Packaging Org):

1. Request a special Developer Edition org for packaging.
2. Develop all your application's metadata directly in this packaging org.
3. In Setup, go to Package Manager.
4. Click New under "Managed Packages".
5. Provide a Package Name, select a unique Namespace Prefix, and fill in other details. Click Save.
6. Add all your developed components to this package.
7. Click Upload to create a new version.

b. 2nd Generation Managed Packages (2GP)

The modern, source-driven approach built on Salesforce DX. Metadata is stored in a Git repository, packages are built from source, and development happens in scratch orgs. This is the recommended approach for new managed packages.

• Modularity: Supports multiple smaller packages with clear dependencies.
• Source-Driven: All package definition and development managed in version control (Git).
• CI/CD Friendly: Integrates seamlessly with automated build, test, and deployment pipelines.
• Better DX: Uses scratch orgs for isolated, disposable development environments.

Creation (SFDX CLI — High-Level Steps):

1. Enable Dev Hub: In your production or developer org, go to Setup → search Dev Hub → enable it.
2. Configure sfdx-project.json:

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true,
      "package": "MyAwesomeApp",
      "versionName": "ver 1.0",
      "versionNumber": "1.0.0.NEXT",
      "ancestorId": null,
      "definitionFile": "config/project-scratch-def.json"
    }
  ],
  "namespace": "mycompany",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "58.0"
}

sf package create \
  --name "MyAwesomeApp" \
  --path "force-app" \
  --packagetype Managed \
  --json \
  --target-dev-hub YourDevHubAlias
# Returns a Package ID (0Ho...). Update your sfdx-project.json with this ID.

sf package version create \
  --package "MyAwesomeApp" \
  --installation-key-bypass \
  --wait 10 \
  --json \
  --target-dev-hub YourDevHubAlias
# Returns a Package Version ID (04t...). Use this to install the package.

sf package version promote \
  --package "04txxxxxxxxxxxxxxxx" \
  --json \
  --target-dev-hub YourDevHubAlias

4. Unlocked Packages

Unlocked packages are a type of 2nd Generation package providing a flexible way to manage and deploy metadata for internal projects. They are source-driven and version-controlled, but their components are editable after installation — a modern alternative to Change Sets and the Ant Migration Tool.

Key Characteristics

• Source-Driven & Version-Controlled: Built from source in a Git repository, promoting modern development practices.
• Editable Components: The key differentiator — components are editable after installation. Great for internal teams needing to make adjustments directly in a sandbox.
• Upgrade Path: Supports upgrades, but changes made in the target org can be overwritten by new package versions.
• No Namespace (Typically): Unlocked packages typically don't have a unique namespace, which can lead to naming conflicts if not managed carefully.
• Internal Use: Designed for internal development teams to modularize their own Salesforce customizations — not intended for AppExchange distribution.
• Deletion: Uninstalling an unlocked package removes both the container and all its components from the target org.

Use Cases

• Modularizing large enterprise Salesforce implementations into smaller, manageable units.
• Managing metadata for internal projects with version control and CI/CD.
• Facilitating agile development and continuous delivery for internal teams.
• Replacing Change Sets and Ant Migration Tool for complex internal deployments.
• Distributing common components or base configurations across multiple internal orgs.

How to Create (SFDX CLI)

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true,
      "package": "MyInternalApp",
      "versionName": "ver 1.0",
      "versionNumber": "1.0.0.NEXT",
      "ancestorId": null,
      "definitionFile": "config/project-scratch-def.json"
    }
  ],
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "58.0"
}

sf package create \
  --name "MyInternalApp" \
  --path "force-app" \
  --packagetype Unlocked \
  --json \
  --target-dev-hub YourDevHubAlias
# Returns a Package ID (0Ho...). Update sfdx-project.json.

sf package version create \
  --package "MyInternalApp" \
  --wait 10 \
  --json \
  --target-dev-hub YourDevHubAlias
# Returns a Package Version ID (04t...).

sf package install \
  --package "04txxxxxxxxxxxxxxxx" \
  --target-org mySandboxAlias \
  --wait 10

5. Choosing the Right Package Type

The choice of package type depends heavily on your use case, audience, and development methodology.

Unmanaged Packages

• Use when: Simple code sharing, open-source projects, templates, small one-off deployments where the recipient needs full editability and no future upgrades are expected.
• Avoid when: Building commercial applications, requiring IP protection, or needing a clear upgrade path.

Managed Packages (2GP preferred for new)

• Use when: Building applications for the Salesforce AppExchange, commercial products, solutions requiring IP protection, and a robust upgrade mechanism.
• Avoid when: Internal organizational customizations where full editability is desired, or for simple deployments not intended for broad distribution.

Unlocked Packages

• Use when: Internal enterprise development, modularizing large Salesforce orgs, adopting source-driven development and CI/CD, replacing Change Sets, or distributing common internal components.
• Avoid when: Building AppExchange products (use Managed Packages) or when strict IP protection is required.

For most internal development, Unlocked Packages combined with Salesforce DX and a robust CI/CD pipeline are the recommended modern approach — offering the benefits of version control and automation while retaining flexibility.

6. Conclusion & Key Takeaways

Salesforce packaging is a powerful mechanism for managing and distributing your customizations. Understanding the different package types and their appropriate use cases is crucial for efficient and scalable Salesforce development.

Key Takeaways

• Unmanaged Packages: Simple sharing, fully editable, no upgrade path. Best for open-source and templates.
• Managed Packages: For AppExchange products, IP protection, and controlled upgrades. 2GP is the modern, source-driven approach.
• Unlocked Packages: For internal enterprise development, modularity, version control, and flexible upgrades. A modern alternative to Change Sets.
• Salesforce DX & SFDX CLI: Essential tools for modern packaging (2GP and Unlocked), enabling source-driven development and CI/CD.

By leveraging the right packaging strategy, you can streamline your development lifecycle, improve collaboration, and ensure the consistent and reliable deployment of your Salesforce solutions.