Introduction

Yzen - MudBlazor Web App Server Premium Admin Template, With these template formats, it's very easy to create a presence and grab someone's attention around the web page Because the template is built using razor, C#, CSS3, MudBlazor framework and with Sass. So please before you start working with the template take a quick look on the documentation so that you can easily built your website. If You Love Our Template Design Please don't forgot to rate it. Thank you so much! 😊

Support and Updates:

When you purchase Yzen, you gain access to free future updates to ensure your template remains up-to-date. Plus, our support team is always ready to assist with any questions.

What Do You Get with the Yzen:

Yzen provides all necessary Razor, CSS, SCSS, JS files, along with detailed Documentation to help you easily customize and implement the template.

Yzen Compatibility with Popular Browsers:

Yzen is fully compatible with major browsers, ensuring a seamless user experience across Chrome, Firefox, Safari, Edge, and Opera.

• Start by unzipping the project folder that you received from us.
• Go to the "Yzen\Components Layout directory within the project folder, where you'll find MainLayout.razor, LandingLayout.razor, MainHeader.razor and NavMenu.razor files etc..
• Go to the "Yzen\Components Pages directory within the project folder, where you'll find over 13 + folders and 170 + .razor files.
• The MainLayout.razor file serves as the base for all razor pages.
• The CustomLayout.razor file is the base for authentication pages such as Create-password-cover.razor, Reset-password-cover.razor, Two-step-verification-basic.razor, Error401.razor, Error500.razor, and Under-maintenance.razor, etc.
• The LandingLayout.razor file is the base for the Landing.razor page.

Step 1: Visit the official .NET SDK download page.

Step 2: Click on the Download .NET SDK button.

Step 3: Run the installer to install the SDK on your system.

Yzen uses AspNetCore.SassCompiler to compile SCSS files into CSS as part of the ASP.NET Core application lifecycle. This ensures styles are always generated automatically and stay in sync with your SCSS source files.

Installation

Install the AspNetCore.SassCompiler NuGet package to enable SCSS compilation. You can install it using any of the following methods:

• Package Manager Console: Install-Package AspNetCore.SassCompiler
• dotnet CLI: dotnet add package AspNetCore.SassCompiler
• PackageReference:

    <PackageReference Include="AspNetCore.SassCompiler" Version="1.97.1" />

How it Works

SCSS files located in wwwroot/assets/scss are compiled into CSS and written to wwwroot/assets/css.

Configuration

The Sass compiler is configured using sasscompiler.json:

    {
    "Source": "wwwroot/assets/scss",
    "Target": "wwwroot/assets/css",
    "Arguments": "--no-source-map --error-css --style=expanded"
    }

Live CSS Changes (Development Mode)

To enable live SCSS-to-CSS recompilation during development, the Sass compiler is registered in the application startup Program.cs:

        if (builder.Environment.IsDevelopment())
        {
            builder.Services.AddSassCompiler();
        }
    

When enabled, any changes made to SCSS files are automatically recompiled at runtime, allowing CSS updates to reflect immediately without restarting the application.

Key Benefits

• Instant SCSS-to-CSS recompilation during development
• No manual build or watch commands required
• Fully integrated with ASP.NET Core
• Works seamlessly with MSBuild and PostCSS pipeline

Note: Initial CSS files are generated by running dotnet build, Run dotnet build once to generate CSS files if they do not exist in wwwroot/assets.

Yzen uses MSBuild targets to manage frontend assets in a structured and automated way. All tasks are executed as part of the standard ASP.NET Core build lifecycle.

This approach avoids introducing a separate JavaScript build system (such as esbuild or Gulp) and keeps asset processing fully aligned with the .NET build process.

Pipeline Responsibilities

1. Ensures Node.js dependencies (node_modules) are installed
2. Resolves and copies libs from node_modules
3. Processes CSS using PostCSS

Why MSBuild?

MSBuild is used as the single orchestration layer for frontend assets to ensure consistency across development, CI/CD, and production builds.

• Runs automatically during dotnet build
• No separate frontend build commands required
• Works consistently across local and server environments
• Avoids duplicate or out-of-sync build pipelines

Automatic npm Dependency Handling

The build pipeline requires Node.js dependencies to be available in node_modules because frontend assets (such as copying npm libraries, SCSS processing, and PostCSS transforms) are executed during dotnet build.

To support both local development and CI environments, an MSBuild target named HandleNpm ensures that dependencies are available before the build continues.

<PropertyGroup>
  <!-- Detect CI environment (Azure DevOps, or generic CI=true) -->
  <IsCI Condition="'$(CI)' == 'true' Or '$(TF_BUILD)' == 'true'">true</IsCI>
</PropertyGroup>

<Target Name="HandleNpm" BeforeTargets="Build">

  <!-- CI behavior: CI pipelines MUST explicitly run 'npm ci' before 'dotnet build'. 
  This ensures deterministic, reproducible builds. -->
  <Error Condition="'$(IsCI)' == 'true' And !Exists('node_modules')" 
         Text="node_modules not found. Run 'npm ci' in the CI pipeline before building." />

  <!-- Local development behavior: If node_modules is missing, dependencies are installed automatically.
    This runs only once and will not repeat if node_modules already exists. -->
  <Exec Command="npm install --no-audit --no-fund" 
        Condition="'$(IsCI)' != 'true' And !Exists('node_modules')" />

</Target>

This approach ensures:

• Fast local development (automatically installs node_modules if not exists.)
• Strict CI reproducibility
• Reliable frontend asset processing during dotnet build

Npm Package libraries Management

• npm packages are managed through package.json. You can install a package using npm install <package-name>, ensuring consistent dependency versions across all environments.
• When dotnet build is executed, MSBuild copies the required package libs from node_modules to wwwroot/assets/libs, making them available for runtime use.

If you want new npm plugin, Install it using command npm install <package-name>, stop the server, then run dotnet build. The configured MSBuild targets will automatically copy the package libs from node_modules to wwwroot/assets/libs.

    <Target Name="CopyVendorAssets" AfterTargets="Build">
    <Message Importance="high"
            Text="Auto-resolving and copying vendor assets..." />

    <Copy SourceFiles="@(AllFiles)"
            DestinationFolder="wwwroot\assets\libs\%(Folder)\%(RecursiveDir)"
            SkipUnchangedFiles="true" />
    </Target>

The pipeline intelligently detects whether a package exposes a dist, min, umd directory and copies optimized files when available. If no dist folder exists, the package contents are copied instead.

PostCSS Processing

After SCSS to CSS compilation by SassCompiler, CSS files are post-processed using PostCSS. PostCSS is used as a lightweight transformation step rather than a full bundling solution.

The PostCSS configuration is defined in postcss.config.js:

    module.exports = {
        plugins: [
            require('postcss-import'), 
            require('autoprefixer'),
        ]
    };

• postcss-import – enables modular CSS with @import and bundles it into one file.
• Autoprefixer – automatically adds required CSS prefixes to ensure cross-browser compatibility.

    <Target Name="MinifyAndPrefix" AfterTargets="Build">
    <Message Importance="high"
            Text="Post-processing CSS: Autoprefixing and Minifying..." />

    <Exec Command="npx postcss wwwroot/assets/css/icons.css
            -o wwwroot/assets/css/icons.css" />

    <Exec Command="npx postcss wwwroot/assets/css/styles.css
            -o wwwroot/assets/css/styles.css" />

    <Exec Command="npx postcss wwwroot/assets/css/icons.css
            -o wwwroot/assets/css/icons.min.css --use cssnano" />

    <Exec Command="npx postcss wwwroot/assets/css/styles.css
            -o wwwroot/assets/css/styles.min.css --use cssnano" />
    </Target>

• cssnano – used only for generating minified production CSS files

When you run dotnet build command, the following actions take place:

1. npm dependencies are installed automatically (if missing)
2. npm package libs are copied to wwwroot/assets/libs from node_modules folder
3. CSS is autoprefixed and minified

All frontend asset tasks are handled automatically by MSBuild, keeping the asset pipeline simple, predictable, and production-ready.

The project uses SassCompiler to compile SCSS files into CSS, and MSBuild targets to copy npm package libraries from node_modules into wwwroot/assets/libs. PostCSS is used for autoprefixing and minification of the generated CSS.

Recommended Development Flow

• Always run dotnet build first, then start the application using dotnet watch run.
• Although dotnet watch run performs a build before starting, it may run an incremental build and some MSBuild targets (such as copying libs) may not execute fully.
• Therefore, if wwwroot/assets/libs is missing, the project may start successfully, but some components can fail with missing library errors because the required libs are not copied from node_modules.

During development, SassCompiler watches SCSS changes automatically, so you do not need to manually recompile or restart the server because we have registered the Sass Compiler in the application startup Program.cs:

    if (builder.Environment.IsDevelopment())
    {
        builder.Services.AddSassCompiler();
    }

When enabled, any changes made to SCSS files are automatically recompiled at runtime, allowing CSS updates to reflect immediately without restarting the application.

Adding a New npm Package

When adding a new npm package, install it using npm install <package-name>, stop the server, then run dotnet build. The configured MSBuild targets will automatically copy the package libs from node_modules to wwwroot/assets/libs.