Custom Admin in production

Hi Ecnerwal1234, here's some guidance.

Replace "mysite" with whatever you want, but make sure you update it in ALL locations found in my below sample code, it does matter.

1. For Production, you will need to Build the react project. I assume you used the Admin Boilerplate, right? Then you should have a "build" command which executes "webpack --mode=production", you'll need to run that as part of your build pipeline

// package.json
{
  "name": "mysite-web-admin",
  "version": "1.0.0",
  "description": "Your title administration project.",
  "private": true,
  "scripts": {
    "start": "webpack serve --mode development",
    "build": "webpack --mode=production"
  },
  "dependencies": {
    "@kentico/xperience-admin-base": "31.0.0", // YOur Xperience Version
    "@kentico/xperience-admin-components": "31.0.0",
    "react": "18.3.1",
    "react-dom": "18.3.1"
  },
  "devDependencies": {
    "@babel/core": "7.25.2",
    "@babel/plugin-transform-runtime": "7.24.7",
    "@babel/preset-env": "7.25.3",
    "@babel/preset-react": "7.24.7",
    "@babel/preset-typescript": "7.24.7",
    "@kentico/xperience-webpack-config": "29.4.1",
    "@types/react": "18.0.33",
    "@types/react-dom": "18.3.0",
    "babel-loader": "9.1.3",
    "webpack": "^5.101.3",
    "webpack-cli": "5.1.4",
    "webpack-dev-server": "^5.2.2"
  },
  "overrides": {
    "react": "$react",
    "react-dom": "$react",
    "json-joy": ">= 11.19.0"
  },
  "browserslist": [
    "> .2% and last 3 versions",
    "not op_mini all",
    "not IE 11"
  ]
}

// webpack.config.js
const webpackMerge = require("webpack-merge");

const baseWebpackConfig = require("@kentico/xperience-webpack-config");

module.exports = (opts, argv) => {
  const baseConfig = (webpackConfigEnv, argv) => {
    return baseWebpackConfig({
      // Sets the organizationName and projectName
      // The JS module is registered on the backend using these values
      orgName: "mysite",
      projectName: "web-admin",
      webpackConfigEnv: webpackConfigEnv,
      argv: argv,
    });
  };

  const projectConfig = {
    module: {
      rules: [
        {
          test: /\.(js|ts)x?$/,
          exclude: [/node_modules/],
          loader: "babel-loader",
        },
      ],
    },
    output: {
      clean: true
    },
    // Webpack server configuration. Required when running the boilerplate in 'Proxy' mode.
    devServer: {
      port: 3070,
    },
  };

  return webpackMerge.merge(projectConfig, baseConfig(opts, argv));
};
``` ```

3. You need to make sure to register your Client Module in a AdminModule class:

   
   [assembly: RegisterModule(typeof(XperienceAdminModule))]
   
   namespace Admin
   {
       public class XperienceAdminModule : AdminModule
       {
           public XperienceAdminModule() : base("XperienceAdminModule")
           {
   
           }
   
           protected override void OnInit(ModuleInitParameters parameters)
           {
               base.OnInit();
   
               // Makes the module accessible to the admin UI
               RegisterClientModule("mysite", "web-admin");
           }
   
   
       }
   }
   
   

4. In your .csproj file for your admin application, you also need to include this to tell it to include the compiled files. Special attention to line 9, 22-34 in the below

   <Project Sdk="Microsoft.NET.Sdk">
   
     <PropertyGroup>
       <TargetFramework>net8.0</TargetFramework>
       <ImplicitUsings>enable</ImplicitUsings>
       <Nullable>enable</Nullable>
       <WarningsAsErrors>Nullable</WarningsAsErrors>
   
       <AdminOrgName>mysite</AdminOrgName> <!-- Should match prefix -->
   
     </PropertyGroup>
   
     <!-- Disable stupid Result conflict with HotChocolate -->
     <PropertyGroup>
       <HotChocolateImplicitUsings>disable</HotChocolateImplicitUsings>
     </PropertyGroup>
   
     <ItemGroup>
       <AssemblyAttribute Include="CMS.AssemblyDiscoverableAttribute" />
     </ItemGroup>
   
   <ItemGroup>
       <AdminClientPath Include="Client\dist\**">
         <ProjectName>web-admin</ProjectName>
       </AdminClientPath>
     </ItemGroup>
     <ItemGroup>
       <Compile Remove="Client\node_modules\**" />
       <EmbeddedResource Remove="Client\node_modules\**" />
       <None Remove="Client\node_modules\**" />
     </ItemGroup>
     <ItemGroup>
       <Folder Include="Client\" /> <!-- Where the admin react client is, for mine it was a folder at the root "Client" -->
     </ItemGroup>
   
   </Project>
   

5. Your admin page should of course also register the custom react:

   
   [assembly: UIPage(typeof(ClassroomOrdersApplicationPage),
       "order-handler", 
       typeof(CustomOrderHandlerTemplate), 
       "Order Handler",
       "@mysite/web-admin/CustomOrderHandler", 
       0)]
   
   

If you want a full, in-production, customized, working example of configuring and deploying admin customizations, just take a look at the Kentico Community Portal source code (the website you are viewing). It is completely open source.

• Admin Client folder

• Admin module and registration

• Admin .NET build configuration

• GitHub workflow deployment pipeline

All of these implementations and customizations follow the Admin UI development preparation docs.

I also created a library - Xperience Community: Component Registry. It uses a lot of Admin UI customization and delivers it as a single NuGet package.

I have it working and am able to get it to publish, but it is very inconsistent. If I make an update to the admin, it doesn't seem to publish when i republish the site. My changed will all work locally, but get JavaScript errors when running it from staging. after series of rebuild and cleans and publishes, sometimes i am able to get it to work again. but sometimes it doesn't make a different.

I think you have an issue with your build and deployment process. If these things are automated you won't ever have these kinds of problems.

You can "deploy" a Release build of your application, including the custom admin client assets, to your local filesystem using dotnet publish. You can then run it from that deployment directory with dotnet MyXperienceApp.dll and see if your build process is generating the correct assets.

If this works consistently, then the problem is your deployment to external environments.