Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Override and code injection in Spire

Describes override and code injection in Spire.

As a developer, you can create new handlers to inject into handler chains to extend Spire. You also have other ways you can override or extend code in Spire.

Override widgets and pages

Collectively, Optimizely considers widgets and pages in Spire as ContentItems. ContentItems are defined in a TypeScript file, which includes all the information for editing a ContentItem, as well as rendering it on the storefront. Review the following basic example of a widget.

// a widget is a react component. It can be a class or functional component. It can be wrapped in HOCs
const ExampleWidget: React.FC<WidgetProps> = (props: WidgetProps) => {
    return <div>
// the definition tells spire information it needs to allow this widget to be added to a page and edited.
// the basics of a definition include a group name and any fields that will exist on the widget
// the values for these fields are supplied by a CMS user and versioned and published.
const definition: WidgetDefinition = {
    group: "Testing",
    fieldDefinitions: [
            name: "textFieldValue",
            editorTemplate: "TextField",
            fieldType: "General",
            defaultValue: "",
// A widget's default export must be a WidgetModule
const widgetModule: WidgetModule = {
    component: ExampleWidget,
export default widgetModule;

Render a component server-side

If you want to render a component server-side, you should be aware of the following items:

  • Using a react class component and the UNSAFE_componentWillMount lifecycle method is the recommended way to load data that the component needs to render server-side.

    • This UNSAFE_ function is part of React and we use it extensively. It should not be confused with Spire code that has been prefixed with UNSAFE_.

    • It is important that the component check if the data is loaded before loading it. Without this check, the component will get mounted, rendered then create a new request to load data 10 times before Spire gives up on it finishing. For example:

    UNSAFE_componentWillMount() {
             if (!props.isDataLoaded) {
  • The React hook useEffect, and the lifecycle method
    componentDidMount do not currently work with server-side
    rendering, so you cannot use these to load any data the component

See Server-side rendering SSR guidelines for Spire for more details.

Replace items in content-library

Spire contains a core version of all out-of-the-box widgets, pages and components in a module called Content-Library. You may replace every file that is in Content-Library by a Blueprint, but you may not replace React components that live outside of Content-Library.

Replacing a Content-Library file involves creating the replacement at: [blueprint]\src\Overrides\[pathOfReplacedFile]

For example, replace content-library\src\Widgets\Basic\PageTitle.tsx by creating [blueprint]\src\Overrides\Widgets\Basic\PageTitle.tsx.

Check with support when overrides don't deploy

Not everything is available for you to override. If you override a file and it seems to work locally, but doesn't have any effect in your sandbox or production environments, the build and deploy process may be ignoring your overrides.

For example, if you want to add some extra fields to the FrontEnd\modules\shell\src\DefinitionLoader.ts file and make these changes directly in the base file, these will not carry through to your sandbox or production environments.

If you want to change a certain file that is not currently open for overrides, please enter a feature request or submit a support ticket so the product team can determine whether to update the code you want changed as part of a future release.