Sitecore JavaScript Services Immersion - Lessons Learned

JSS Immersion

Diving into JavaScript Services – Lessons Learned Anastasiya Flynn Front-End Technical Evangelist @ Sitecore May 17, 2019

Hello SUGCON! 👋

JavaScript/JSS Evangelist (wat?) Goals:

• Champion adoption of JSS
• Ensure developers and partners have the necessary resources to be successful.
• JavaScript all the things!

”One of the primary goals of Sitecore JSS was to add a proper first-class interface for JavaScript developers and enable websites and web apps powered by Sitecore Experience Platform” - Alex Shyba

🧠Learning Resources

Official Docs https://jss.sitecore.com/docs Video - Getting Started With JSS https://www.youtube.com/watch?v=IeLqT75N8V0 Video – Build Your First JSS App https://www.youtube.com/watch?v=XNQGsr9_34A&t=3s

Quick Start

Cleaning Up • Removed StyleGuide boilerplate • Removed bootstrap • Removed hardcoded navigation

✨ Beautiful! ✨

JSS starting point - empty page

🛠 My sandbox

Sandbox requirements

Event Listing - 💻 Demo

Event Listing - Highlights

• Dynamic navigation generated from content tree
• Background generated from configurable page-level color fields
• GraphQL powered Search box
• Two instances of a Header component, configured to render differently
• GraphQL powered Search Results finds instances of Event pages

Getting Started

Customizing CLI Project structure Data modeling Debugging techniques

Getting Started - Customizing CLI

⚠️ Customizing CLI

⚠️ Customizing ‘jss scaffold’ - Demo

Getting Started - Project Structure

‘jss scaffold’ + project structure

What if I don’t like the project structure generated by ‘jss scaffold’? • ‘jss scaffold’ drives files structure of components • Default convention is \src\components\ComponentName\index.js • This file structure is important – used to generate the Component Factory • If you update how files are generated by ‘jss scaffold’, you may need to update how scripts\generate-component-factory.js generates the Component Factory

Component Factory

How it works • The component factory is a mapping between a string name of a Sitecore rendering and a React component instance • By default, component factory registers components that follow the \src\components\ComponentName\index.js convention • Injected as prop into SitecoreContext in AppRoot • To change how component factory is generated, update scripts\generatecomponent-factory.js • Use case for customization: importing components from node_modules

Component Factory

Why I like the default src structure

• A single Sitecore rendering can be a composite of multiple React components (aka module). They can all be grouped together in the module directory and only the main component gets exported.
• Shared utility/UX components which don’t correlate to Sitecore renderings are easy to exclude from Component Factory.

Lessons Learned

Customizing CLI & Project Structure

• Start with package.json to find entry point
• Customize default component code via scripts\scaffold-component.js
• Customize Component Factory via scripts\generate-component-factory.js

Getting Started

Customizing CLI Project structure Data modeling (selected) Debugging techniques

Manifest API – adding content

manifest.addRoute()

• Routes (aka pages)
• Components

manifest.addContent()

• List items

Lessons Learned

Data Modeling • Need to be explicit about item role when declaring item • Some manifest functions called by OOTB JSS scripts • More info: http://tinyurl.com/y28jpmlg

Getting Started - Debugging techniques

🦠 Debugging - VSCode Breakpoints

Debug JSS apps with breakpoints in VSCode

1. Install Chrome Debugger extension
2. Add .vscode/launch.json config
3. Add breakpoints to code
4. Run jss start
5. Press F5 in VSCode
6. Reload page

🦠 Debugging - Breakpoints Demo

🦠 Debugging - React Dev Tools

🦠 Debugging – console.log()

When you may want to use console.log() • Debugging components in connected mode • Debugging errors during build

🦠 Debugging – console.log()

Build error Search for error Add logging

Lessons Learned

Debugging Techniques • Use “Chrome debugger” VSCode extension to enable breakpoints • Use “React developer tools” Chrome extension to inspect values passed to component props • When all else fails, use console.log() for instant results

Accelerated Development With React Modules

Static content Theming Modular components Animations

Accelerated Development With React Modules

Static content (selected) Modular components (selected) Theming Animations

react-rebass

https://rebassjs.org/ Why it rocks • Single command installation • 8 foundational UI components • Super small (~1KB) • Responsive, themeable style props • Support for styled-components 💅 • Extensible

react-rebass

Why it rocks (continued) • Takes static data as props and converts to styled UI elements – perfect for usage in a CMS

Building modular components

Building modular components

sitecore\definitions\components
Header.sitecore.js

data\routes\events\en.yml

src\components\Header\index.js

Editing fields in Experience Editor

withSitecoreContext() helper

Accelerated Development With React Modules

Static content Modular components Theming (selected) Animations

🌈 Themes

What constitutes a theme? • Brand colors • Fonts and text size • Device breakpoints • Whitespace

styled-components

https://www.styled-components.com/ Why it rocks • Single command installation • Automatic critical CSS • Only injects styles of components that are used on the page • Works with code splitting • Unique class names avoid collisions • Dynamic styling • Worry-free deletion of obsolete CSS • Improves modularity of components • Takes static data as props and converts to CSS – perfect for usage in a CMS

Provide theme

src\Layout.js

Consume theme

src\components\HeaderContainer\Background.js src\components\SearchResults\SearchResultTiles.js

Theme - Demo

Accelerated Development With React Modules

Static content Theming Modular components Animations (selected)

react-spring

https://www.react-spring.io/ Why it rocks • Single command installation • Covers most UI-related animation needs • Natural-looking animations • Cross-platform • Supports render props and hooks • Takes static data as props and converts to animations – perfect for usage in a CMS

react-spring

src\components\SearchResults\index.js

Lessons Learned

Accelerated development with React modules • Use withSitecoreContext() helper to change rendering behavior by page state • Invisible fields editable via ‘edit fields’ ribbon button • React libraries integrate smoothly into JSS • Useful libraries for improving modularity and accelerating UX development • react-rebass • styled-components • react-spring

Dynamic Content

Keyword searches via GraphQL Injecting GraphQL data into Layout Service

Dynamic Content

Keyword searches via GraphQL (selected) Injecting GraphQL data into Layout Service

GraphQL - Configuration

sitecore\config\jss-sandbox.config

GraphQL - Demo

GraphQL – Lessons Learned

1. Use “search” query to filter items by criteria
2. Check Sitecore.ContentSearch.ISearchResult Implementations for available fields
3. Use spread operator for query nesting
4. Alias fields for more intuitive result structure
5. Cast ItemField base type to other field types via sub-queries

React context API

“Context provides a way to pass data through the component tree without having to pass props down manually at every level” – React docs

React context - Demo

Dynamic Content

Keyword searches via GraphQL Injecting GraphQL data into Layout Service (selected)

Inject GraphQL data into Layout Service

sitecore\definitions\components\Navigation.sitecore.js src\components\Navigation\index.js

Inject GraphQL data into Layout Service

GraphQL-powered navigation

Lessons Learned

Dynamic Content • Try out the OOTB GraphQLqueries in GraphiQL GUI • Use React Context API to orchestrate a search page • Use ‘graphQLQuery’ field on rendering definition to inject data into Layout Service

Thank you!

Final lesson learned ‘jss deploy’ + ‘jss start:connected’ = 🔥💻🔥

Want more JSS immersion? • Follow #SitecoreJSS and @AnastasiyaFlynn on Twitter • Check out https://www.codealamodeblog.com/jss-sandbox/

Sponsors