Sitecore JavaScript Services Immersion - Lessons Learned

A presentation at Sitecore User Group Conference (SUGCON) in May 2019 in Bengaluru, Karnataka, India by Anastasiya Flynn

Slide 1

Slide 1

JSS Immersion

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

Slide 2

Slide 2

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!

Slide 3

Slide 3

Slide 4

Slide 4

”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

Slide 5

Slide 5

🧠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

Slide 6

Slide 6

Quick Start

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

Slide 7

Slide 7

✨ Beautiful! ✨

JSS starting point - empty page

Slide 8

Slide 8

🛠 My sandbox

Sandbox requirements

Slide 9

Event Listing - 💻 Demo

Slide 10

Slide 10

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

Slide 11

Slide 11

Getting Started

Customizing CLI Project structure Data modeling Debugging techniques

Slide 12

Slide 12

Getting Started - Customizing CLI

Slide 13

Slide 13

⚠️ Customizing CLI

Slide 14

⚠️ Customizing ‘jss scaffold’ - Demo

Slide 15

Slide 15

Getting Started - Project Structure

Slide 16

Slide 16

‘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

Slide 17

Slide 17

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

Slide 18

Slide 18

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.

Slide 19

Slide 19

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

Slide 20

Slide 20

Getting Started

Customizing CLI Project structure Data modeling (selected) Debugging techniques

Slide 21

Slide 21

Manifest API – adding content

manifest.addRoute()

  • Routes (aka pages)
  • Components

manifest.addContent()

  • List items

Slide 22

Slide 22

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

Slide 23

Slide 23

Getting Started - Debugging techniques

Slide 24

Slide 24

🦠 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

Slide 25

🦠 Debugging - Breakpoints Demo

Slide 26

Slide 26

🦠 Debugging - React Dev Tools

Slide 27

Slide 27

🦠 Debugging – console.log()

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

Slide 28

Slide 28

🦠 Debugging – console.log()

Build error Search for error Add logging

Slide 29

Slide 29

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

Slide 30

Slide 30

Accelerated Development With React Modules

Static content Theming Modular components Animations

Slide 31

Slide 31

Accelerated Development With React Modules

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

Slide 32

Slide 32

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

Slide 33

Slide 33

react-rebass

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

Slide 34

Slide 34

Building modular components

Slide 35

Slide 35

Building modular components

sitecore\definitions\components
Header.sitecore.js

data\routes\events\en.yml

src\components\Header\index.js

Slide 36

Slide 36

Editing fields in Experience Editor

Slide 37

Slide 37

withSitecoreContext() helper

Slide 38

Slide 38

Accelerated Development With React Modules

Static content Modular components Theming (selected) Animations

Slide 39

Slide 39

🌈 Themes

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

Slide 40

Slide 40

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

Slide 41

Slide 41

Provide theme

src\Layout.js

Slide 42

Slide 42

Consume theme

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

Slide 43

Theme - Demo

Slide 44

Slide 44

Accelerated Development With React Modules

Static content Theming Modular components Animations (selected)

Slide 45

Slide 45

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

Slide 46

Slide 46

react-spring

src\components\SearchResults\index.js

Slide 47

Slide 47

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

Slide 48

Slide 48

Dynamic Content

Keyword searches via GraphQL Injecting GraphQL data into Layout Service

Slide 49

Slide 49

Dynamic Content

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

Slide 50

Slide 50

GraphQL - Configuration

sitecore\config\jss-sandbox.config

Slide 51

GraphQL - Demo

Slide 52

Slide 52

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

Slide 53

Slide 53

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

Slide 54

React context - Demo

Slide 55

Slide 55

Dynamic Content

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

Slide 56

Slide 56

Inject GraphQL data into Layout Service

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

Slide 57

Slide 57

Inject GraphQL data into Layout Service

Slide 58

Slide 58

GraphQL-powered navigation

Slide 59

Slide 59

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

Slide 60

Slide 60

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/

Slide 61

Slide 61

Sponsors

Slide 62

Slide 62