Code-first development workflow

Version: 21.x

In a code-first workflow, the JSS app creates a manifest of its content data and data schema from a set of files. This enables the JSS app to run with local mock content, without a Sitecore instance.

In this mode, the JSS app is the master copy of all artifacts. The manifest gets imported into Sitecore, which creates the necessary structures to support the app.

We recommend that you choose the code-first workflow if:

  • You are in the early prototyping phase of a design, where a Sitecore instance might not be available yet.

  • The primary developers on the team are JavaScript developers.

  • Front-end developers do not have their own Sitecore instances.

  • The needs of the app are relatively simple from a content perspective.

  • The company is hiring an external front-end agency to build a JSS app that will later be integrated into Sitecore.

Important

When considering using the code-first workflow, it is important to be aware of the limitations of this technique to ensure you make the correct choice of workflow.

Initial app deployment

When your code-first JSS application is ready to be deployed to Sitecore, connect and deploy your JSS app to Sitecore.

The app drives all the initial content hierarchy. Every route in your JSS app becomes a page-level item, and each component becomes a rendering item. The JSS app also determines the presentation details on page-level items.

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.

After initial app deployment, you can continue to develop code-first or switch to Sitecore-first.

Incremental app deployment

If you added a new component that must be deployed to Sitecore, you can use the command jss deploy app, with the options --includeContent --includeDictionary if appropriate, and the import process perform the necessary changes.

When the content user activity starts, developers usually own some parts of the Sitecore content tree, such as /sitecore/Layouts and /sitecore/Templates and Content Authors own items under /sitecore/Content. Therefore, if Content Authors have already started their activities, we recommend you only deploy code artifacts, with the command jss deploy files, which does not deploy any items (routes, content, images).

Content workflow and developer overwrite

The JSS import process is designed to skip items for which the configured import user does not have write permission. This allows you to utilize Sitecore Security to prevent the import process from overwriting content that is not owned by developers.

To further support this, JSS includes a content workflow that is automatically applied to all generated templates. The workflow defines Development Mode and Content Mode states to designate the ownership of a content item.

Sitecore content tree for JSS Development Workflow

The following table summarizes the states of the JSS Development Workflow:

Mode

Description

Development Mode

The import process can overwrite field values and route item layout.

Content Mode

The import user is denied item write access. The import process skips writing on the item. For route items, any rendering changes or updates to datasource items are also skipped.

Note

By default, the Development Mode workflow state is not publishable. A JSS site that has its content database set to anything other than master, so enabling workflow and publishing, does 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.

Development Mode includes an __OnSave command that moves the item into Content Mode. By default, any content changes to an item force the item into Content Mode when saved, to avoid overwrites by subsequent imports.

To move an item back to Development Mode, you can use the Allow Developer Overwrite action.

Important

We recommend that you limit the use of the action Allow Developer Overwrite to scenarios of simple content changes to routes and/or their datasources, or when renderings have been added to the Shared Layout.

Using the action Allow Developer Overwrite is dangerous. If the developer does not pull the latest content, whatever is imported next overwrites the existing item content. Even if the developer uses pull-all-route-data to update local data, data and configuration can still be lost. This is because the route data is not a complete serialization of the item. Some data that can be lost is:

  • Personalization rules / conditional rendering.

  • Content tests.

  • Final Layout (although it is pulled in the route data, it is reimported as Shared Layout).

  • Specific datasource locations (import utilizes whatever datasource strategy is configured for the app).

We strongly recommend that you consider ownership of items when using the import process. Rather than updating the routes through the import process, provide only new components which Content Authors can utilize on the routes.

Front-end developer and Sitecore developer item ownership

JSS uses Sitecore Security to designate developer items that must not be overwritten on import. These typically include items such as:

  • The app's generated Route template.

  • Datasource templates and their fields.

  • The app's generated main layout.

  • Renderings.

  • Placeholder settings.

Denying item:write and item:create access to the sitecore\JSS Import Service Users role or to 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 skips those items and outputs a warning indicating that it has done so. This allows the Sitecore developer to change the imported items without fear that changes are overwritten.

Import process notification about skipping non-writable item

To facilitate these restrictions, JSS provides two security presets that can be used to quickly protect items from the import process:

Code-first import security presets

Preset

Description

No overwrite

Denies item:write access to the item and its descendants for the sitecore/JSS Import Service User role. Indicates the import must not overwrite any field values on the item.

No new children

Denies item:create access to the item and its descendants for the sitecore\JSS Import Service User role. Indicates the import must not create any new children under the item.

Using this mechanism requires additional coordination between the front-end developer and the Sitecore developer items protected with these security presets require changing.

You do not have to restrict writes if you are updating fields that JSS does not touch. The JSS import does not delete an item unless it runs in full wipe mode. Avoiding these restrictions, however, confuses the item ownership and might create issues if the JSS import adds support for those fields in the future.

Importing in full-wipe mode

During initial development, when the application structure is volatile, it can be helpful to have a fresh start on each import. Importing in full-wipe mode deletes 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 (CI) configurations, where check-ins from front-end developers are automatically deployed/imported in a CI environment.

Full-wipe import has a double lock on it and must be enabled in two places:

  • The SitecoreJSS.WipeAllowed setting in the Sitecore configuration must be enabled (true) in a configuration patch. 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.

  • The JSS CLI command must include the --wipe parameter (alias -w). For example, jss deploy app -c -d -w.

Important

Full-wipe mode must not be enabled in a content entry or production environment. Sitecore configuration rules are in place by default so that the WipeAllowed global setting defaults to true for Sitecore installs in a Standalone role to make it easy to wipe during development while preventing mistakenly wiping a production site with a Content Management role. For added security, you can also disable item:delete access to relevant portions of the content tree for the JSS import role or user.

Reducing risk in long-term code-first development

Sometimes teams are required to develop code-first for the majority of development time.

To reduce risks in such scenarios:

  • As part of front-end developer onboarding, we recommend that front-end developers get a chance to try Sitecore editors. It is important to understand what components, fields, rendering parameters, and placeholders are from the authors' point of view, and that sometimes components need to be rendered in special ways in Sitecore editing interfaces. For example, a modal is normally hidden on page load, but visible on page load in the Experience Editor so that Content Authors can edit the modal contents.

  • If all front-end developers are required to work in disconnected/code-first mode, we recommend having a Sitecore developer on the team to collaborate on the design of templates.

Do you have some feedback for us?

If you have suggestions for improving this article,