Table of Contents

Local Development

The FrontEnd Server can be hosted locally as an ASP.NET Core 8 process that you debug through Visual Studio or VS Code, with your custom components compiled into the same process. This is the standard workflow for iterating on C# custom components, plugins, and business rules without redeploying a container every cycle.

Related docs.
Component Authoring — how to author a custom component (C# + React).
Installation — full reference for production deploys.
Overview — mental model of the BFF + React-shell pair.
System Overview — full mental model of how the BFF, the React shell, and the microservices fit together.

What this tool does — and does not — give you

This tool hosts only the BFF half of the FrontEnd Server locally: the .NET process that exposes /api/v2/display/<pageKey>/<id>, /oauth/callback, /configurablepermissions, and the rest of the HTTP surface. It is sufficient for:

  • Iterating on a custom C# component (MapSchema, MapData, business rules, plugins).
  • Debugging server-side behaviour with breakpoints / Edit-and-Continue.
  • Exercising the BFF API directly (e.g. via Postman or DevTools).

It does not serve the React shell. To see your component rendered in the operator-facing UI, you also need one of:

  • A locally-running React shell — cd MibFrontEnd/apps/cms && pnpm dev (or npm run dev), configured to point at the locally-hosted BFF.
  • A deployed React shell pointed at your local BFF (set the shell's VITE_API_URL env var to your local BFF root, e.g. http://localhost:5000/).
  • The Storybook in your federated remote, for component-isolation work that doesn't need the BFF wired up at all.

For component-isolation work, prefer Storybook with the MibFrontEnd mock-server package — see Component Creation — Storybook for isolation.


Prerequisites (Visual Studio)

Add the nuget feeds to install the development package. For more information click here.

Create an ASP.NET Core application.


Select .NET 8 (the FrontEnd Server runs on .NET 8 from MIB 7.0; older releases targeted .NET 6.0).



Installation (Visual Studio)

Open nuget manager.



Select the MediaiBox.Cms.FrontEnd.Server nuget package and install.



Settings (Visual Studio)

After installation, you will need to run the build to finalize the package settings in the project.

Add and edit the following configuration files:


Open and edit the Program.cs file and add the following snippet:


using MediaiBox.Cms.FrontEnd.Server.Development;

MibHost
    .Create()
    .Start();



Then run the application and log into the CMS.


If all the steps were followed correctly the CMS landing page will open:





Prerequisites (VS Code)

Install the C# plugin.




Installation (VS Code)

Add the nuget feeds to install the development package. For more information click here.

dotnet nuget add source {nuget_endpoint} -n MibNuget

Create a solution. 
dotnet new sln --output Agile.Mediaibox.Cms.Dev

Change to the project directory. 
cd Agile.Mediaibox.Cms.Dev

Create an ASP.NET Core application. 
dotnet new web --output Agile.Mediaibox.Cms.Dev

Add the project to the solution 
dotnet sln add Agile.Mediaibox.Cms.Dev

Install the MediaiBox.Cms.FrontEnd.Server nuget package. Use the version matching your target MIB release — the feed at [nuget.agilesvcs.com](https://nuget.agilesvcs.com) hosts the available versions. 
dotnet add Agile.Mediaibox.Cms.Dev package MediaiBox.Cms.FrontEnd.Server --version <target-version>


Settings (VS code)


After installation, you will need to run the build to finalize the package settings in the project. 
dotnet build

Open VS Code. 

code .

Add and edit the following configuration files:

Open and edit the Program.cs file and add the following snippet: 

using MediaiBox.Cms.FrontEnd.Server.Development;

MibHost
    .Create()
    .Start();


Start Debug and click on create a launch.json file and select .NET5+ and .NET Core and press F5.



If all the steps were followed correctly the CMS landing page will open.



How to Debug

Here is an example of a project with a custom component:


The following steps will be based on the Agile.Mediaibox.Cms.Dev project for didactic reasons.

  • Add the references of the required projects in Agile.Mediaibox.Cms.Dev;
  • Copy the contents of the Views and wwwroot into the Agile.Mediaibox.Cms.Dev output directory:

    • Agile.Mediaibox.Cms.Dev/bin/debug/net6/Views/**.*

    • Agile.Mediaibox.Cms.Dev/bin/debug/net6/wwwroot /**.*



Customizing The Development Environment

To facilitate the development of custom components, mib allows you to change some settings at startup.


Change the views folder path.

In the "How to Debug" example, the Views folder of the custom component should be in /bin/debug/net6.0/Views for the mib to be able to render. You can change the view path:

using MediaiBox.Cms.FrontEnd.Server.Development;

var customPath = Directory.GetCurrentDirectory();

MibHost
    .Create()
    .SetCustomViewPath(customPath)
    .Start();

In the example above the mib will render the views of the following structure:



Change the wwwroot folder path.

In the "How to Debug" example, the wwwroot folder should be at /bin/debug/net6.0/wwwroot. You can change the view path:

using MediaiBox.Cms.FrontEnd.Server.Development;

var customPath = Directory.GetCurrentDirectory();

MibHost
    .Create()
    .SetCustomWebOptimizerPath(customPath)
    .Start();

In the example above the mib will load the assets of the following structure:



Add an asset folder

If there is a need to include a new assets folder to facilitate development, here is an example below:

using MediaiBox.Cms.FrontEnd.Server.Development;
using Microsoft.Extensions.FileProviders;

var customPath = Directory.GetCurrentDirectory();

MibHost
    .Create()
    .SetCustomStaticFiles(ctx => new StaticFileOptions
    {
        FileProvider = new PhysicalFileProvider(Path.Combine(customPath, "MyAssets")),
        RequestPath = "/MyStaticAssets"
    })
    .Start();

In the example above the mib will load the static assets of the following structure:



Add a MibConfig path

If there is a need to specify a mib configuration path, here is an example below:

using MediaiBox.Cms.FrontEnd.Server.Development;

MibHost
    .Create()
    .AddMibConfigurationPath(@"C:\agile\cms\config")
    .Start();


Tips & Tricks

Automate the copy of Views and assets via csproj's Target tag.

Here's an example:

<Target Name="CopyViewsComponent" AfterTargets="AfterBuild">
	<ItemGroup>
		<SampleViewsFiles Include="..\MediaiBox.Cms.FrontEnd.Sample.Component\Views\**" />
	</ItemGroup>
	<Copy SourceFiles="@(SampleViewsFiles)" DestinationFiles="$(OutDir)Views/%(RecursiveDir)%(Filename)%(Extension)" />
</Target>
<Target Name="CopyAssetComponent" AfterTargets="AfterBuild">
	<ItemGroup>
		<SampleAssetFiles Include="..\MediaiBox.Cms.FrontEnd.Sample.Component\wwwroot\**" />
	</ItemGroup>
	<Copy SourceFiles="@(SampleAssetFiles)" DestinationFiles="$(OutDir)wwwroot/%(RecursiveDir)%(Filename)%(Extension)" />
</Target>


Pairing with the React shell for end-to-end dev

The local BFF on its own gives you the API surface. To see your component render in the operator UI, point a running React shell at it.

Option A — local React shell (recommended)

cd MibFrontEnd/apps/cms

# Configure the shell to point at the locally-hosted BFF
cat > .env.development.local <<EOF
VITE_API_URL=http://localhost:5000/
VITE_CUSTOM_COMPONENTS_URL=http://localhost:4000/assets/remoteEntry.js
EOF

pnpm install
pnpm dev   # or: npm run dev

The shell opens at http://localhost:5173/ (Vite default) and hits the locally-hosted BFF for every render. Make sure your federated remote is also running (pnpm dev in the remote's repo, served on port 4000).

When the BFF and the shell live on different origins (the default in local dev), you must enable CORS on the BFF:

MIBCMSFRONTENDSERVERBASECONFIG_DEFAULT_CORSORIGINS=http://localhost:5173
MIBCMSFRONTENDSERVERBASECONFIG_DEFAULT_CORSMETHODS=GET,POST,PUT,DELETE,OPTIONS
MIBCMSFRONTENDSERVERBASECONFIG_DEFAULT_CORSHEADERS=Content-Type,Authorization,If-None-Match,If-Match

You also need CorsAllowCredentials=true on the Authorization Server so the OAuth cookie can be set cross-origin.

Option B — Storybook for component-isolation work

For component-isolation work that doesn't need a real BFF, use Storybook in your federated remote. The MibFrontEnd mock-server package provides MSW handlers that mimic the BFF's response shape — your widget runs against canned {schema, data} fixtures and you iterate fast. See Component Creation — Storybook for isolation.

Option C — deployed shell pointing at your local BFF

For one-off integration tests, deploy a shell to a dev environment and point it at a tunnelled local BFF (e.g. via ngrok). Useful when testing OAuth cookie behaviour, but slower to iterate than Option A.

Edit this page