Use a Namespace and Alias in Managed Packages
Before you package your components and distribute them on AppExchange, register a namespace in your org. A namespace prefix prevents naming conflicts in the installer's organization. See Developing Second-Generation Managed Packages.
Just like component names include a namespace prefix in managed packages, GraphQL API queries in your components must include a namespace prefix on custom objects and fields. For example, a custom object, MyCustomObject__c, in an org with the namespace, example_ns, would become example_ns__MyCustomObject__c.
If your org uses a namespace, namespacing is resolved automatically for custom objects and fields in your query when deploying your Lightning Web component. Namespace resolution isn't affected if you add it yourself.
Let's look at an example with a GraphQL query that works correctly as-is in a non-namespaced developer org. The example is followed by a package-ready query that includes an org's namespace and preserves referential integrity.
The GraphQL query uses a custom object, Custom_Object__c, and a custom field, Custom_Object_Field__c, in the example developer org with the my_namespace namespace.
If you’re referencing objects and fields from another namespace, you must include the namespace as part of the object or field name.
During development, you push the component to a scratch org for testing. The original component source is unchanged. The updated query is sent to the client, which is also what a subscriber's org executes when it runs.
References to objects and fields outside of the gql template literal aren’t updated.
Since the query is updated, the component is likely to fail at runtime. To resolve this issue, apply GraphQL alias syntax on your custom objects and fields. See Use Aliases with Custom Objects and Fields.
Let's add aliasing to the base query, and update how you retrieve data from the response.
When you push the component to a scratch org with aliasing, the resulting query looks like this.
Using GraphQL alias maintains referential integrity and preserves the names that are used for custom objects and fields in the GraphQL result.
Referential integrity is built in to the Salesforce platform development experience. Referential integrity includes:
- Spidering: automatically including dependencies in packages and changesets
- Delete blocked: preventing or issuing a warning on the deletion of dependencies
- Rename cascades: updating source code on the renaming of dependencies
These capabilities simplify working across technologies and concepts on the Salesforce platform. For example, when you apply custom objects and fields to your query and package the Lightning Web component, it automatically includes the custom objects and fields. When the developer tries to delete the custom object, the operation is blocked because it can break the Lightning web component.
When the custom object gets renamed, the reference to that object in the query is updated. To preserve referential integrity, we strongly recommend using GraphQL aliases for your custom objects and fields. Using GraphQL aliases also prevent your component from breaking if a subscriber org renames your custom objects or fields.
Use Aliases with Custom Objects and Fields