Sitecore First Workflow
NOTE: before working Sitecore-first, we recommend doing an initial deploy of a new app with Import. This will create all of the root items, base templates, and such to get you started on a well-organized JSS app.
Working Sitecore-first in a JSS app is a lot like building any non-JSS Sitecore site. There are a few key differences:
Creating Renderings
When creating rendering items, use the Json Rendering
template instead of View renderings, XSLT, etc. This rendering template is automatically rendered to JSON when emitted via Layout Service. Json Rendering also includes some additional fields that allow you to set Rendering Contents Resolvers, set up Integrated GraphQL queries, and configure any placeholders that are exposed by the rendering.
Also unique to Json Rendering, the Component Name
field is a string that needs to match up to the name of a component registered in the JSS app. For example, if you created a rendering with Foo
as the component name, the JSS app would need a Foo.js
component that was registered with its component mapping as "Foo" -> Foo.js
. If a component name cannot be mapped, JSS apps will show a placeholder with the name of the missing component received from Sitecore. This can be used to scaffold out a component hierarchy prior to frontend developers actually implementing the view of the components.
If you add a placeholder to a rendering, don't forget to add it to the
Layout Service Placeholders
field on the rendering item - if this is not done, Layout Service will not attempt to render the child placeholder, and you will not receive any renderings added to it in the Layout Service data.
Editing & Creating Routes
Creating routes Sitecore-first is just like adding pages in a traditional Sitecore site.
Scripted component scaffolding in Sitecore-first
When working in a Sitecore-first application, the task of adding a new component involves a repetitive set of steps (creating a rendering item, datasource template item, datasource location folders, linking them together, etc). To keep this simple, there are JSS CLI commands to help scaffold JSS components' Sitecore infrastructure:
jss deploy component
deploys a new component (similar tomanifest.addComponent()
for code-first, but directly to the Sitecore database)jss deploy template
deploys a new Sitecore template (for use as a content template, settings item, etc)
Run jss deploy component --help
for documentation; a usage can be as simple as jss deploy component HelloWorld --allowedPlaceholders content
.
Transitioning from Code-first to Sitecore-first
The JSS sample apps are all set up to use code-first workflow by default. At some point, apps may wish to transition from working with disconnected data and importing that into Sitecore to treating Sitecore data as the master.
Such a transition would usually be because:
- An app started its life as a code-first disconnected prototype and is transitioning to be Sitecore integrated
- App developers are more comfortable working in Sitecore than in JS and prefer a familiar backend
- The limitations of import are too limiting, and the app is transitioning to use Sitecore item serialization
It is not necessary to perform any steps to transition to Sitecore-first development, other than to not push import data. The following steps are for developers wishing to remove artifacts of code-first development from their app for cleanup and safety in case of an accidental deployment.
Removing Code-First Artifacts
These instructions apply to all supported JS libraries.
Extensively customized apps using different techniques than the standard sample apps may require additional steps depending on their customizations.
- Delete
/data
to remove disconnected route data, if it exists - Delete
/sitecore/definitions
to remove the manifest definitions - Delete
/sitecore/pipelines
(if it exists) to remove manifest pipeline patches - Delete
/scripts/disconnected-mode-proxy.js
to remove an unused script - In the
package.json
:- Remove the
start
script, and (optional) renamestart:connected
tostart
to remove the option to start disconnected - Remove the
bootstrap:disconnected
script
- Remove the
Working After Removal
Once code-first has been removed from the app, you may continue development as before but without expecting any new items to come from the JSS app.
At this point you will most likely be working in connected mode, where your app is running locally but fetching data from a Sitecore instance which is available via HTTP(S). Therefore, if you haven't already, it is recommended to follow the steps outlined in connected mode setup.