Modernize @sitecore-content-sdk/react to React 19+ Best Practices (HOCs → Hooks, Class → Functional Components)

[robertsoniv]

Is your suggestion related to a problem? Please describe.

The @sitecore-content-sdk/react package uses outdated React patterns that don't align with React 19+ best practices:

Current Issues:

1. HOC Pattern Overuse: 8 Higher-Order Components (withEditorChromes, withPlaceholder, withDatasourceCheck, etc.) that could be modern hooks for better composability and React 19 optimization
2. Class Components: 6 class components (SitecoreProvider, PlaceholderComponent, BYOCComponent, etc.) using lifecycle methods instead of hooks
3. Legacy Context API: Using Context.Consumer render props instead of useContext hook
4. React.createElement Usage: 7 files using React.createElement instead of JSX syntax
5. useEffect Dependency Issues: Missing or incomplete dependency arrays in several components
6. Deprecation Strategy: No clear migration path from HOCs to hooks, making it harder for consumers to modernize

These patterns work but don't leverage React 19 optimizations, make code less composable, and create a steeper learning curve for developers familiar with modern React patterns.

Describe the solution you'd like

Modernize the package through a phased, backwards-compatible approach:

Phase 1: Create Hook Infrastructure

• Create 7 new hooks: useEditorChromes, useComponentMap, useDatasourceCheck, usePlaceholder, useAppPlaceholder, useEmptyFieldEditingComponent, useFieldMetadata
• Export hooks alongside existing HOCs (no breaking changes)

Phase 2: Refactor HOCs to Use Hooks

• Convert all HOCs to be thin wrappers around the new hooks
• Add @deprecated JSDoc tags and development-mode warnings
• Maintain 100% backwards compatibility

Phase 3: Convert Class Components to Functional

• Convert SitecoreProvider, PlaceholderComponent, and BYOCComponent to functional components
• Replace lifecycle methods with hooks (useEffect, useState, useMemo)
• Keep error boundaries as classes (React 19 requirement)

Phase 4: Fix React Patterns

• Replace React.createElement with JSX in 7 files
• Fix useEffect dependency arrays in Form.tsx, DesignLibrary.tsx, etc.
• Replace Context.Consumer with useContext in withSitecore

Phase 5: Testing & Documentation

• Add comprehensive tests for all hooks
• Create migration guide: docs/migration/hooks-migration.md
• Update API docs with deprecation notices
• Ensure TypeScript types are complete

Key Benefits:

• ✅ Zero breaking changes (all in minor versions)
• ✅ HOCs remain functional during transition
• ✅ Clear migration path for consumers
• ✅ Better React 19 optimization and tree-shaking
• ✅ Improved developer experience and composability

Is there a way to achieve this functionality with exisiting tools?

Yes, the existing HOCs continue to work. The modernization adds hooks as the preferred pattern while keeping HOCs functional. Consumers can:

• Continue using HOCs - They'll work indefinitely but show deprecation warnings
• Gradually migrate to hooks - Use new hooks in new code, migrate existing code over time
• Use both patterns - Mix HOCs and hooks during transition period

The hooks provide the same functionality with better composability. For example:

• withEditorChromes(Component) → useEditorChromes() inside component
• withPlaceholder(...)(Component) → const placeholderData = usePlaceholder(...)
• withSitecore()(Component) → const { page, api } = useSitecore() (already exists)

Additional information

Implementation Details:
Files to Create:

• src/hooks/useEditorChromes.ts
• src/hooks/useComponentMap.ts
• src/hooks/useDatasourceCheck.ts
• src/hooks/usePlaceholder.ts
• src/hooks/useAppPlaceholder.ts
• src/hooks/useEmptyFieldEditingComponent.ts
• src/hooks/useFieldMetadata.ts
• src/hooks/index.ts

Files to Refactor:

• src/enhancers/withEditorChromes.tsx (class → functional, use hook)
• src/enhancers/withComponentMap.tsx (use hook internally)
• src/enhancers/withDatasourceCheck.tsx (use hook internally)
• src/enhancers/withPlaceholder.tsx (class → functional, use hook)
• src/enhancers/withAppPlaceholder.tsx (use hook internally)
• src/enhancers/withEmptyFieldEditingComponent.tsx (use hook internally)
• src/enhancers/withSitecore.tsx (replace Context.Consumer with useContext)
• src/components/SitecoreProvider.tsx (class → functional)
• src/components/Placeholder/Placeholder.tsx (class → functional)
• src/components/FEaaS/BYOCWrapper.tsx (class → functional)
• src/components/Form.tsx (fix useEffect dependencies)
• src/components/DesignLibrary.tsx (fix useEffect dependencies)
• 7 files using React.createElement → convert to JSX

Versioning Strategy:

• Phases 1-5: Minor version bumps (1.3.0 → 1.4.0 → 1.5.0)
• All changes maintain backwards compatibility
• Future major version (2.0.0) could optionally remove HOCs if desired

Success Criteria:

• All hooks implemented and tested
• All HOCs refactored to use hooks internally
• All class components converted to functional (except error boundaries)
• All React patterns updated to modern best practices
• Full backwards compatibility maintained
• Comprehensive documentation and migration guide
• Zero breaking changes in minor versions

[robertsoniv]

Impact Summary for @sitecore-content-sdk/nextjs Package

Positive impacts:

• New hooks available: The Next.js package re-exports React package APIs, so new hooks (useEditorChromes, useComponentMap, useDatasourceCheck, usePlaceholder, etc.) will be available to Next.js consumers after the React package updates.
• Better composability: Next.js components can use hooks directly instead of HOCs, improving composability in App Router and Server Components.

No breaking changes:

• All existing HOCs remain functional: withSitecore, withPlaceholder, withEditorChromes, withDatasourceCheck continue to work as before.
• Current Next.js components unaffected: Placeholder.tsx, Link.tsx, NextImage.tsx use React package components/types that remain compatible.
• Type exports unchanged: PlaceholderComponentProps, WithSitecoreProps, SitecoreProviderState, etc. remain the same.

Recommended follow-up actions:

• Re-export new hooks: Update src/index.ts to export the new hooks alongside existing HOCs for consistency.
• Update documentation: Add Next.js-specific examples showing both HOC and hook patterns.
• Test compatibility: Verify Next.js package tests pass with the modernized React package, especially components using SitecoreProviderReactContext directly (e.g., NextImage.tsx).

Timeline:

• No immediate action required — Next.js package will work with modernized React package out of the box.
• Optional enhancement: Re-export hooks in a future minor version to provide a consistent API surface.
• Bottom line: The Next.js package benefits from the modernization with zero breaking changes. Existing code continues to work, and new hooks become available for future development.

[stasmaxymov]

@robertsoniv Thank you for the detailed input!
I have few comments on it.

• Suggested changes focus on code clarity and alignment with idiomatic React approaches, but also mention some optimization improvement. However I miss what exact optimization improvement they provide.
• Big part of suggested changes is to replace HOCs to hooks. However majority of the HOCs used in content-sdk are not directly replaceable with hooks as they don't with state or have extractable behavior, but mostly help to wrap targeted components with utility components or work with only JSX. The ones that do have distinct behavior either have a hook (useSitecore) or not exported to from package (withComponentMap).

Other suggestions are valid and would make code a practices cleaner in Content SDK

[robertsoniv]

Working on a more in depth reply, but for now, just for my own understanding... part of your comment "are not directly replaceable with hooks as they don't [missing word?] with state", wasn't totally clear to me what you meant.

[robertsoniv]

Regarding your comment on the "optimization" I referred to, the optimization is merely incremental as React 19 optimizes functional components / hooks better than class components - nothing major. Also, I didn't realize that withComponentMap is only used internally - wouldn't mark that as particularly high priority now, other than having consistent internal patterns (assuming we move forward with the other changes).

Trying to clear it up a bit: the goal I had in mind was to modernize by converting class components to functional components where possible and also update and/or clone (for backwards compatibility) some of the enhancers to use the hook pattern where possible - not replace all HOCs with hooks. I know that ErrorBoundary still has to be a class component so there will be at least 1 class component in the mix.

My attention is usually drawn to the Placeholder.tsx component - of which, admittedly, I'm still trying to wrap my head around. But, for the sake of argument if we had a hook for useComponentMap available, could we theoretically create a function component that can achieve feature parity with the current class component? I see that it uses the componentDidCatch, so Placeholder would have to be wrapped in the ErrorBoundary component or the children should be wrapped... Just typing this out it is becoming more apparent why class components were utilized in greater numbers than I'm accustomed to. Perhaps a longer convo over a call may help me get over some of the hangups I have.

Essentially, where I'm coming from is having attempted to adopt the content-sdk for a different React meta-framework (other than NextJS), and some patterns I noticed in the react package seemed "off" or "old" (not saying they're wrong, just that from my experience in React in recent years it raised some concerns). There could be more functional components + hooks vs. the class components and with* wrapping pattern (feels like I'm back in Angular). So I suppose what I would really like to see is the "react" package feel like modern React. Again, this is all just "code style" stuff.

I totally respect that this layer is critical for rendering hosts and that everything works as-is. There's a ton to take in! Perhaps with a few tweaks we can make the "react" package more easily accessible to developers in the community and hopefully that enables them to contribute their own wants/needs in the future.

[stasmaxymov]

Working on a more in depth reply, but for now, just for my own understanding... part of your comment "are not directly replaceable with hooks as they don't [missing word?] with state", wasn't totally clear to me what you meant.

Those HOC act mostly as outside wrappers not altering/extending components behavior.
Better to explain on example. Take withFieldMetadata. This HOC does one thing - wraps a field with "metadata" nodes when page is rendered for editing, needed by authoring apps like Pages or Design Library.
Users can use this hook to make their custom field discoverable in Pages via concise API: export const ImageField = withFieldMetadata(()=>{/* component code here */}
Alternative to this hook would be to implement this wrapping in every "Field" in users codebase, or have a generic wrapper in user's code base, which is no different to current HOC.
If you see how hooks can improve situation here - please share you ideas. I'm totally with you on preferring modern practices, like we use them in all new code or features.

I also want to make it clear, like I mentioned above, all the other suggestions are totally valid and I'd say very important. I really appreciate your input. In day to day work with all priorities and deadlines it is easy to overlook such inefficiencies and outdated practices. I can assure you we definitely are going to implement suggestions, but not immediately. I'd target a next major release as some of the changes are formally breaking changes (class -> functional), but it will be relatively soon