How to apply Helix to a Sitecore JSS client application

When we started working on a new Sitecore JSS project there was no mention of Helix principles in the JSS documentation for the client application.

This is most likely because the JSS starter application is based on popular frontend frameworks (either Angular, React or Vue) and communities of these frameworks have established some architectural principles. Nonetheless, the Codehouse front-end team felt it was important to be consistent with the back-end solutions based on Helix practices without compromising established front-end architectural principles.

Folder structure

The front-end framework of choice for the JSS project was React. The JSS starter application for React is based on the “Create React App” and is very much open to interpretation, leaving it to the developer to define the application architecture.

React doesn’t have opinions on how you put files into folders. That said there are a few common approaches popular in the ecosystem you may want to consider REACT

In light of this statement we were free to modify the folder structure to follow Helix principles and incorporate other popular approaches from the React community. Our solution was to achieve the same folder structure as the Habitat solution created by Sitecore.

With the folder structure represented above, component files (CSS, JS, tests) are grouped together inside their React component folder. This is a common pattern of structuring files in the React community. This way, there's a folder structure following Helix principles and the principles established by the React community.

Nonetheless, altering the client application folder structure will break two out-of-the box JSS features: the component factory and the scaffolding of new components.

Component factory

The component factory is the “mapping between JSS component names and their React component implementations”. The mapping happens during the build of the client application, and it expects React components to be inside the src folder. With the new folder structure the React components live a few levels deeper in the application and the build can no longer dynamically construct the component factory.

The good news is that the JSS team made several scripts used by the build customisation, including the one that generates the component factory. In this scenario, the script generate-component-factory.js needs to be updated to look for React components further down the file tree. Download this example to see only the parts of the generate-component-factory.js script that have been changed.

The script looks inside the Helix layers folders, goes through all of the modules inside each layer as well as the React components in each module. It also looks for changes on those components. After these changes, the build dynamically constructs a map of your React components organised in a Helix folder structure.

Scaffolding new components

The scaffolding script, jss scaffold <componentName>, allows developers to dynamically create a new React component placing it directly in /src/components/.

To adhere to the new folder structure developers need to manually move the new React components to its corresponding Layer and Module folders. Similarly, in the component factory, the scaffold-component.js script needs to be customised to place the React component in the correct location. In order to do that, when executing the script, pass extra arguments to specify the location of the component: jss scaffold <ComponentName> <LayerName> <ModuleName>. The following changes in scaffold-component.js will cater for that: Download the script.

With these changes you're able to scaffold a new React component in its correct location without any manual work.

Conclusion

Sitecore doesn't require the JSS client application to follow the Helix principles. However, for consistency with the back-end solution, the client application can follow the same architecture pattern by altering its folder structure. This change doesn't require a compromise on front-end architectural patterns, since it groups all the files corresponding to a React component inside the component folder - a popular approach by the React Community.

Changing the JSS client application folder structure affects the JSS component factory and component scaffolding. These JSS features expect files to be in specific locations, however the scripts behind these can be customised and cater for the new changes.

Working with Codehouse

At Codehouse we're constantly exploring ways of improving the Sitecore development process. We continually work on exciting design and build projects often on CMS like Sitecore. Get in touch to find out more.