How to Use React in the Umbraco Backoffice

Umbraco V14 introduced a step change for devs creating customisations in the Umbraco Back-office. Version 13 and below use Angular for custom back-office components, but from v14 onwards this changed to Web Components. The recommendation from Umbraco is to use these in combination with wrapper library Lit, and front end build tool Vite.  If, like me, you already use tools like Webpack and React, then learning yet more front-end tech might not be desirable or practical when you have tight deadlines. 

If you are looking for an alternative approach for building Umbraco Backoffice Components and Sections using Webpack and React, this article is for you.

The following steps explain how to use React to build custom Umbraco Backoffice customisations for v14 onwards:

1. Add a custom Section to Umbraco back office (v14, 15 and 16).
2. Configure Webpack build to build Javascript & css files.
3. Create a wrapper Web Component to house React.
4. Set up a basic React Component for the back-office section.
5. Get Productive!

Configure Webpack for React

Step 2 to use React and Webpack for building custom sections in the Umbraco Backoffice involves configuring Webpack to build the typescript and scss files created in the previous step. For my Umbraco components I use a separate webpack.plugin.js config file to keep the front-end build separate to that of the Umbraco back-office.

Add the following webpack.plugin.js file in the root of your Umbraco website:

const { CleanWebpackPlugin } = require("clean-webpack-plugin"); // Cleans up after webpack https://www.npmjs.com/package/clean-webpack-plugin
const MiniCssExtractPlugin = require("mini-css-extract-plugin"); // https://webpack.js.org/plugins/mini-css-extract-plugin/ Extracts CSS from JS and bundles separately
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin'); // Speeds up Typescript checking https://github.com/TypeStrong/fork-ts-checker-webpack-plugin
const autoprefixer = require("autoprefixer"); // Adds Vendor prefixes https://github.com/postcss/autoprefixer from CanIUse

const path = require("path");

module.exports = {
    mode: 'development',
    devtool: 'source-map',
    entry: {
        'product-section-app': './App_Plugins/products/scripts/product-section-app.tsx',  // Output File : Input File
    },
    output: {
        filename: '[name].js',
        chunkFilename: "[name].js",
        path: path.resolve(__dirname, './App_Plugins/dist'), // Main drop folder
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js']
    },
    module: {
        rules: [
            {
                test: /\.tsx?$/,
                exclude: /node_modules/,
                use: {
                    loader: 'ts-loader',
                    options: {
                        configFile: 'tsconfig.plugin.json'
                    }
                }
            },
            {
                // Build Website CSS (Loaders below processed last to first)
                test: /\.s?css$/i,
                use: [
                    {
                        loader: MiniCssExtractPlugin.loader
                    },
                    {
                        loader: 'css-loader',
                        options: {
                            importLoaders: 1,
                            sourceMap: true,
                            url: false // Switches off checks for urls of images referenced in scss
                        }
                    },
                    {
                        loader: "postcss-loader",
                        'options': {
                            'postcssOptions': {
                                plugins: () => [autoprefixer()],
                            },
                        },
                    },
                    {
                        loader: 'sass-loader',
                        options: { sourceMap: true }
                    },
                ]
            },
        ],
    },
    plugins: [
        new CleanWebpackPlugin(),
        new MiniCssExtractPlugin({
            filename: "[name].css",
            chunkFilename: "[name].css",
            ignoreOrder: false,
        }),
        new ForkTsCheckerWebpackPlugin(),
    ]
};

The key takeway from this file is the Entry Path points at the /App_Plugins/products/scripts/product-section-app.tsx file (the Web Component Wrapper), with the exit path being /dist/product-section-app.js, so the final .js file the umbraco-package.json file points at.

Create Wrapper Web Component for React

The third step is to add a Web Component for the custom Umbraco Section to act as a wrapper for the React component.  The component instructs Webpack to process the .scss style file (via an import) and also pull in the React and DataGrid modules.

When Umbraco initialises the Web Component it triggers the connectedCallback method, which:

- Creates a div within the shadow dom that we attach our React component to.
- Adds a link to the component's .css file created during the Webpack build.
- Attaches the React component to the div created earlier.

Add the following code into your product-section-app.tsx file:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './product-section';
import '../css/index.scss';

// For MUI DataGrid
import createCache from "@emotion/cache";
import { CacheProvider } from "@emotion/react";

class ProductSectionElement extends HTMLElement {
    constructor() {
        super();
    }

    connectedCallback() {
        const shadowContainer = this.attachShadow({ mode: 'open' });

        const wrapper = document.createElement('div');
        this.shadowRoot.appendChild(wrapper);

        const style = document.createElement('link');
        style.setAttribute('rel', 'stylesheet');
        style.setAttribute('href', '/App_Plugins/dist/product-section-app.css');
        this.shadowRoot.appendChild(style);

        // This is to pass MUI Datagrid styles thru to shadow dom
        const cache = createCache({
            key: "css",
            prepend: true,
            container: shadowContainer
        });

        const root = ReactDOM.createRoot(wrapper);
        root.render(
            <CacheProvider value={cache}>
                <App />
            </CacheProvider>);                
            );
    }
}

customElements.define('product-section', ProductSectionElement);

Get in touch...

Custom Umbraco back office Sections are a great way to integrate internal business systems with your Umbraco website.

If you have this type of requirement then Codebricks can help, so please get in touch for a free, no obligation chat.