Registering a namespace prefix is a one-time setup for a package, but using it correctly is an ongoing development concern. The workflow below covers the standard sequence for a new ISV or enterprise team setting up a namespaced package.
- Choose and register the namespace prefix
Decide on a namespace prefix that is meaningful for the brand or product (1 to 15 alphanumeric characters, starting with a letter). Check availability through the Salesforce DX CLI (sf org namespace list or the Developer Console namespace registration UI). Register the prefix in the Dev Hub org. The registration is immediate and permanent: the prefix is yours globally across Salesforce. Document the prefix choice in the project README so all developers on the team use it consistently.
- Configure the Salesforce DX project
Update the project's sfdx-project.json to declare the namespace prefix at the project level. Configure the source files to use the local-name convention (no prefix in the source) while specifying the namespace in the package metadata. Set up the project's CI pipeline to build packages with the namespace prefix applied. Test by deploying a sample package to a scratch org and confirming the components appear with the correct prefix.
- Audit Apex and dynamic references
Review the Apex codebase for any hardcoded namespace references, dynamic SOQL with component names, and Schema or Type API calls. Update any such references to use the appropriate namespace-aware patterns: UserInfo.getOrganizationNamespace, explicit namespace prefix in cross-package references, prefix-aware string concatenation in dynamic SOQL. Add code review checklist items for namespace awareness so future code stays consistent.
- Test installation in a clean subscriber org
Create a fresh scratch org or sandbox that does not have the namespace prefix. Install the package version through its install URL. Verify that the components appear in the subscriber org with the namespace prefix, that the Apex code runs correctly, and that any cross-package or cross-org references work as expected. Test with a sample customer-added field on a namespaced object to confirm the customer-org-local field works alongside the vendor-shipped fields. Iterate until the install experience is clean.
- The namespace prefix is permanent for the package. Changing it requires creating a new package and migrating subscribers, which is rarely worth the cost.
- Hardcoded namespace strings in Apex break when the code runs outside the namespace. Use namespace-aware utilities for dynamic references.
- Generic component names within a namespace can conflict with standard object names. Choose descriptive prefixes for components even inside the package.
- Cross-package references require the explicit namespace prefix on the referenced component. Local-name references work only within the same package.
- Customer-org-local fields on namespaced objects do not have the prefix. Reports and Apex code that read both vendor-shipped and customer-added fields must handle this correctly.