Characteristics of the JSS code-first import process
The JSS import process, used for code-first development, allows you to rapidly design and define the structure of an application while disconnected from Sitecore and then publish it to Sitecore. The import process creates Sitecore artifacts, such as templates, placeholder settings, datasource items, route items, and rendering items.
If you plan to use the App Import capabilities with your JSS apps, you must keep in mind the following:
The import process is idempotent
You can run the import process multiple times on the same application to the same Sitecore instance without repercussions, with some limitations.
Any fields on an item not explicitly defined in the manifest are left untouched. For example, if a Sitecore developer inputs a source for an imported field, the next import does not reset the source unless the manifest also defines a value for the source.
Special considerations define how import works with content items and content editors.
The import process is not a substitute for Sitecore Serialization
The import format does not represent the full fidelity of Sitecore items or handle every situation when updating items. It does not replace tools such as Unicorn or TDS that serialize Sitecore items.
The import process primarily allows the design of rendering apps by front-end developers who might not have an available Sitecore instance or want to begin working on their application before back-end developers set up Sitecore. Eventually, in the development process, we recommend the import process is supplemented by or replaced by purpose-built Sitecore item serialization tools to maintain the state of a JSS app, with the possible exception of rapidly developed simple campaign-style apps.
Sitecore item serialization tools can serialize items created or updated by JSS import; they are like any other Sitecore item.
The import process uses strings as IDs by default
The import process maps string names onto Sitecore items with GUIDs, making the import files easier to write. The mapping means that moving or renaming imported items must be done carefully.
Imported Sitecore item IDs are deterministic: importing the same app on different Sitecore instances creates items with identical IDs in Sitecore.
Renaming imported Items
Because they are matched by string name, renaming an item in your manifest (or in Sitecore) after it has already been imported results in creating a duplicate item if the import is re-run. To prevent item duplication:
-
Explicitly set the manifest ID to the existing imported item ID in Sitecore, then rename it in the manifest. It is renamed on import.
-
Set the display name and leave the name alone, which visually alters the name in Sitecore.
Moving imported items
Because they are matched by name, moving imported items causes duplicates on the next import.
If you must move an imported item, set an explicit ID for the item equal to the already imported Sitecore item ID in the manifest. The import process queries the item by the ID instead of the name. Therefore, the item remains known to the manifest after moving.
The import process does not purge unknown items
If you remove a template or route from the manifest, the import process does not delete it from Sitecore on the next import.
The import process sets values only for explicitly defined manifest data
Only explicitly defined manifest data overwrites values set in Sitecore.
For example, suppose you import a template that does not define an icon, and a Sitecore developer sets an icon on the item. In this case, future imports do not overwrite the icon value. If the manifest defines an icon for the template, the value in the manifest overwrites any value set in Sitecore.
Handling item IDs in the import process
Sitecore items have unique GUID IDs. By default, App Import uses the name defined in the manifest to derive a deterministic GUID so that the imported item always has a predictable ID. The GUID is namespaced, so names must only be unique within a section of the app instead of across the entire JSS app.
For example, it is legal to have both a route and a template named Home (or two routes at different levels), but it is not legal to have two templates called Home. The namespace also contains the JSS application name so that multiple JSS apps can have items with the same name.
Renaming a JSS application causes all of the expected GUIDs of its items to change.
It is also possible to specify an explicit ID for all of the items in the import manifest by adding the id property to the manifest definition of the items.
When specifying explicit IDs on route data in a multilingual import environment, ensure the same ID value on all language values.
The id can be one of the following types:
-
A GUID value, used literally. It is the same item ID used in Sitecore.
-
A string value, used as the source for a deterministic GUID. Unlike name-based deterministic GUIDs, explicit string IDs are namespaced only by the JSS app name. Therefore, they must be globally unique within a JSS app.
App Import never changes an existing imported item GUID to avoid losing data. When you set an ID value on an already imported item, the new ID only takes effect in Sitecore if you delete that item and re-run the import or run the import in full wipe mode.
The sample applications have examples of setting explicit IDs in their Styleguide examples on content reuse.
When adding components to the manifest, you must provide two id properties: the renderingId and the templateId. Both must be present because a JSS component definition adds two Sitecore items.