Salesforce Second-Generation Packaging (2GP), Explained

TL;DR: Second-generation packaging (2GP) is Salesforce's modern, source-driven way to build and distribute managed and unlocked packages from version control instead of a packaging org. It replaces first-generation packaging (1GP) with modular packages, flexible namespaces, explicit dependencies, and a Salesforce CLI workflow. Salesforce now recommends 2GP for all new managed package development.

What is Salesforce second-generation packaging (2GP)?

A 2GP package is a container for the metadata, code, and schema you distribute as an app - to AppExchange customers (managed) or across your own org estate (unlocked). The defining idea is that the package is built from source in Git, not from a stateful packaging org. Salesforce is explicit that managed 2GP "isn't merely version 2.0" of 1GP; it is a different, automation-friendly development model, and it is the recommended path for all new packages.

How is 2GP different from first-generation packaging (1GP)?

The short version: 1GP lives in a packaging org, 2GP lives in your repository. That single change unlocks the rest:

• Source-driven. The package version is created from your project source, so Git is the source of truth.
• Modular. You can split functionality across multiple packages instead of one monolith.
• Namespace flexibility. The same namespace can be shared across several 2GP packages, though each package binds to one namespace that cannot change after creation.
• Explicit dependencies. Package dependencies are declared in sfdx-project.json, not discovered at install time.
• Version control and CI friendly. The whole flow runs through the Salesforce CLI, so it drops into a pipeline.

Managed or unlocked: which 2GP do you need?

Both are second-generation packages built the same way. The choice is about audience:

• Managed 2GP - for ISVs distributing on AppExchange. Code is IP-protected and the package carries a registered namespace.
• Unlocked packages - for internal teams organizing an org's own metadata into deployable, versioned units. Code stays readable.

How do you create a 2GP package? (step by step)

You need a Dev Hub org with Unlocked Packages and Second-Generation Managed Packages enabled, and the Create and Update Second-Generation Packages permission. Then:

1. Create the package definition. sf package create --name MyApp --package-type Managed --path force-app --target-dev-hub DevHub
2. Create a version from your source, with an installation key and code coverage. sf package version create --package MyApp --installation-key test1234 --code-coverage --wait 10 --target-dev-hub DevHub
3. Test the install in a scratch or sandbox org. sf package install --package 04t... --wait 10
4. Promote to released once it passes. Promotion requires meeting code coverage. sf package version promote --package [email protected] --target-dev-hub DevHub

A promoted managed version is the one you submit to AppExchange security review before customers can install it.

What are the common 2GP gotchas?

• Namespace is permanent. Pick it deliberately; a 2GP package cannot switch namespaces later.
• Code coverage gates promotion. You cannot promote a version to released without meeting Apex coverage requirements.
• Dependencies must be explicit. Undeclared dependencies fail at install, not at build.
• Not every 1GP metadata type is supported. Check coverage before migrating an old package.

Because the whole flow is CLI-first, it slots into a DevOps pipeline - the same place tools like Copado, Gearset, Salto, AutoRABIT, Flosum or Blue Canvas orchestrate version control and testing. For more build-and-release playbooks, see our SF Guides.

FAQ

Is 2GP replacing 1GP?

Salesforce recommends 2GP for all new managed packages, though existing 1GP packages still work and can be migrated.

Do I need a Dev Hub for 2GP?

Yes. Enable Dev Hub and second-generation packaging, and grant the create/update packages permission before you start.

Can two 2GP packages share a namespace?

Yes. Several managed 2GP packages can use one namespace, but each package binds to a single namespace that cannot change after creation.

What is the difference between managed and unlocked packages?

Managed 2GP is for AppExchange distribution with IP protection; unlocked packages organize your own org's metadata into versioned, deployable units.