When contemplating using code-first workflow, it's important to be aware of the limitations of this technique to ensure you make the correct choice of workflow.
Initial app deployment
Before deploying, ensure that you have a Sitecore install with Headless server components installed.
The app drives all the initial content hierarchy (routes -> page-level items), renderings (for each component there will be one rendering item in Sitecore) and presentation details on page-level items.
To deploy your app, run:
jss deploy app --includeContent --includeDictionary
This command will perform the following steps for you, which can also be performed independently if needed:
- App manifest generation starts with
jss manifest. This will generate the
sitecore-import.jsonfile that will be used by
- A JSS manifest package is generated using the manifest created previously, using
- The app will be built, using
- The manifest package is deployed to Sitecore via the import service endpoint -
jss deploy items --includeContent --includeDictionary
- The build artifacts are copied to the Sitecore instance at the configured location -
jss deploy files
At the end of the process, you will have everything necessary automatically created in Sitecore and your app is expected to render the same way as in the disconnected mode.
See the documentation about the import process for important information on how import works and how to customize it
Incremental app deployment
For a Sitecore-first development process incremental deployments will use
jss deploy filesonly. Package-based deployment is only for code-first scenarios after the initial deployment.
The same scripted process applies for incremental deployment. If you added a new component that needs to be deployed to Sitecore, you can simply execute
jss deploy app, with
--includeContent --includeDictionary if appropriate, and the import process will take care of the change.
jss deploy appfor incremental deployment, read the import process documentation for important considerations.
Here you have more options, however. You may want to deploy changes during development with
jss deploy files, for example.
When the content user activity starts, it makes sense to think about the parts of the content tree owned by developers (
/sitecore/templates) and which ones are owned by content authors (
/sitecore/content). See the Content Workflow and Developer Overwrite section for more information about content ownership.
Content Workflow and Developer Overwrite
The JSS import process is designed to gracefully skip items to which the configured import user does not have write permission. This allows you to utilize Sitecore Security to prevent the import from overwriting content which should no longer be "developer-owned."
To further facilitate this, JSS includes a content workflow which is automatically applied to all generated templates. This workflow defines Development Mode and Content Mode states to designate the current "ownership" of a content item.
|Development Mode||Import can overwrite field values and route item layout.|
|Content Mode||Import user is denied item write access. Import will skip writes on the item. For route items, this means that any rendering changes or updates to datasource items are also skipped.|
Note that Development Mode includes an __OnSave command which moves the item into Content Mode. This means that by default, any content changes to an item will force it into Content Mode, to avoid overwrite by subsequent imports.
By default the Development Mode workflow state is not publishable. This means that a JSS site that has its content database set to anything other than master (thus enabling workflow and publishing) will not publish content items that are imported from the JSS app manifest without workflow approval. For use-cases where app-based content should be considered "publishable", check the Final checkbox on the Development Mode workflow item in the above screenshot.
To move an item back to Development Mode, you can use the Allow Developer Overwrite action. As stated in the confirmation dialog presented by that action, doing so can be dangerous. If the developer does not pull the latest content, whatever is imported next will overwrite the existing item content. Even if the developer uses
pull-all-route-data to update local data, data and configuration can still be lost, since the route data is not a complete serialization of the item. Examples of data that could still be lost includes:
- Personalization rules / conditional rendering
- Content tests
- Final Layout (though it will be pulled in the route data, it would be reimported as Shared Layout)
- Specific datasource locations (import will utilize whatever datasource strategy is configured for the app)
Therefore it is recommended that you limit use of Allow Developer Overwrite to only scenarios when simple content changes have been made to route and/or its datasources, or potentially when renderings have been added to the Shared Layout.
As when deploying items using any tool which can serialize Sitecore items, you need to carefully consider ownership of items when using the import process. Rather than updating the routes through the import, your import may simply provide new components which content authors can utilize on the routes.
Front-end Developer vs Sitecore Developer Item Ownership
Similar to designating content author "ownership" of content items is JSS's use of Sitecore security to designate developer items which should not be overwritten on import. This would typically include items such as:
- The app's generated Route template
- Datasource templates and their fields
- The app's generated main layout
- Placeholder settings
item:create access to the
sitecore\JSS Import Service Users role or the specific import user allows a Sitecore developer or admin to limit items that the front-end developer can create and update. The import process will gracefully skip those items and output a warning indicating that it has done so. This allows the Sitecore developer to tweak the imported items without fear that the changes will be overwritten.
To facilitate these restrictions, JSS provides two security presets that can be used to quickly protect items from the import process.
Note that you may need to scroll past the default Sitecore
Require Loginpresets to see these options, or use the dropdown button of the
Presetsbox to see them all.
|No new children||Denies
Care should be taken when using this mechanism as it will require additional coordination between the front-end developer and the Sitecore developer if a change is needed to the items in question.
You don't necessarily need to restrict writes if you are updating fields which JSS does not touch. JSS import will never delete an item unless "full wipe" mode is enabled. However note that doing this confuses the ownership of the item and could create issues in the future if the JSS import adds support for the field.
Import Full Wipe Mode
During initial development, when application structure is most volatile, it can be helpful to have a "fresh start" on each import. Enabling Full Wipe mode will delete any imported items at their currently configured path at the start of the import process. It is intended primarily for local development or Continuous Integration configurations, where check-ins from front-end developers are being automatically deployed/imported in a CI environment.
Full Wipe has a "double lock" on it and must be enabled in two places:
- The SitecoreJSS.WipeAllowed setting in Sitecore configuration must be enabled (
true) in a configuration patch.
- The --wipe parameter (alias
-w) must be passed via the JSS CLI
jss deploy app -c -d -w
In addition, the SitecoreJSS.WipeMode setting can be used to control whether the import recycles (default) or does a hard delete of the items. Change this setting at your own risk.
Care should be taken to ensure that Full Wipe is not enabled in a content entry or production environment. Sitecore configuration rules are in place by default so that the
WipeAllowedglobal setting defaults to
truefor Sitecore installs that are in the
Standalonerole. This is designed to make it easy to wipe while developing, but hard to mistakenly wipe a production site (which would have a
ContentManagementrole) The paranoid and/or thorough may also wish to disable
item:deleteaccess to relevant portions of the content tree for the JSS import role or user.