Table of Contents

Oqtane Extension - Build and Distribution (WIP)

These guides will help you understand how Oqtane Extensions (Themes and Modules) are packaged and distributed.

This is not about building/distributing Oqtane itself, but about building and distributing your own Themes and Modules.

Background

Oqtane is a .net 8.0 Blazor application that is designed to be modular and extensible. This means that you can create your own modules, themes, and other extensions to customize your Oqtane solution.

To get comfortable with Oqtane, you will need to understand how to package and distribute your themes and modules.

We want to cover the following topics:

  1. What is a Build and What's Inside it?
  2. How does the Build Process Work?
  3. What is a package?
  4. What is a deployment?
  5. Build and deploy during development
  6. Build and deploy for distribution
  7. Distribute through Nuget, Github and the Oqtane Marketplace

Basics: What is a Build and What's Inside it?

A build is the process of taking your work preparing it to run. When we say your work this usually means:

  1. Your C# code
  2. Your Blazor code
  3. Your HTML, CSS, JavaScript
  4. Any additional images, fonts, etc.

The build is usually done by Visual Studio and typically involves 3 steps:

  1. Compiling any JavaScript, SASS etc. using Webpack
  2. Compiling your C# and Razor code into one .net assembly
  3. Deploying the results, together with any other files (eg. supporting DLLs)
    deployment can be into other folders, or into a Nuget package

How does the Build Process Work?

The build process is usually done by Visual Studio. If you follow the current conventions, you will have a dedicated project called Oqtane...Package which is only responsible for the building process.

Tip

If you only build the main project, the result will just sit around and do nothing. You must build the package project to see anything useful.

What is Triggered by the Build Process?

The build process is configured in the Oqtane...Package.csproj file, explained here:

<Project Sdk="Microsoft.NET.Sdk">
  <!-- some parts skipped for brevity -->

  <!-- This is where the distribution / package steps are configured, "PostBuild" -->
  <Target Name="PostBuild" AfterTargets="PostBuildEvent">
    <!-- If Windows and creating a Dev-Build, Run "debug.cmd" -->
    <Exec Condition="'$(OS)' == 'Windows_NT' And '$(Configuration)' == 'Debug'" Command="debug.cmd" />
    <!-- If Mac/Linux and creating a Dev-Build, Run "debug.sh" using bash -->
    <Exec Condition="'$(OS)' != 'Windows_NT' And '$(Configuration)' == 'Debug'" Command="bash $(ProjectDir)debug.sh" />
    <!-- If Windows and creating a Release-Build, Run "release.cmd" -->
    <Exec Condition="'$(OS)' == 'Windows_NT' And '$(Configuration)' == 'Release'" Command="release.cmd" />
    <!-- If Mac/Linux and creating a Release-Build, Run "release.sh" using bash -->
    <Exec Condition="'$(OS)' != 'Windows_NT' And '$(Configuration)' == 'Release'" Command="bash $(ProjectDir)release.sh" />
  </Target>
</Project>

What Happens in a Dev-Build?

➡️ Read more about the Dev-Build

What Happens in a Release-Build?

➡️ Read more about the Release-Build

What's missing here?

The previous example shows a default setup for a Theme. As you may have noticed, it doesn't have a WebPack or other JavaScript build steps.

Tip

As of now, the default templates/modules don't include examples for TypeScript or SASS.


Main Author

Daniel Mettler, @iJungleboy [MS MVP, Oqtane Core Team]

Content Management Expert, Chief Architect of 2sxc and cre8magic.
Forged in the jungles of Indonesia, lives in Switzerland , loves Oqtane 🩸 & 2sxc 💜.

LinkedIn | Discord: @iJungleboy | Twitter: @iJungleboy | Github: @iJungleboy

Edit this page