Confusion About Oqtane Project Structure – Application Template vs GitHub Repository

[Bhushan02-dot]

Hello @sbwalker ,

I’m currently learning and working with the Oqtane Open Source framework, and I have some confusion regarding the project structure and recommended development approach.

My Observations

Using Oqtane Application Template (Visual Studio)

When I create a new Oqtane project using the Application Template, the solution structure is different.

When I create a new module, it is added inside the same solution.

Using Oqtane GitHub Repository

When I clone the Oqtane GitHub repository, the structure is different.

When I create a new module here, it is usually created as a separate module project and then referenced/linked with Oqtane.

Update / Upgrade Concern

Oqtane gets frequent updates and new features.

If I customize Oqtane or add modules:

How should I pull future updates safely?

What is the recommended way to keep my project up-to-date without breaking my custom modules?

My Questions

Which approach is recommended for real-world development?

Application Template based solution
OR

Cloned GitHub repository based setup?

What is the best practice for module development?

Should modules always be created as separate projects?

Or is it okay to keep them inside the main Oqtane solution?

When Oqtane releases new updates:

How should we merge or apply those changes to an existing project?

Should we rebase from GitHub, update NuGet packages, or recreate the project?

[sbwalker]

@Bhushan02-dot as of Oqtane 6.2 there are now 2 "official" approaches for developing Oqtane solutions. Both approaches are recommended for "real world development". Both approaches support upgrading the framework. I recommend you watch the video recording at this link: https://www.oqtane.org/blog/!/124/oqtane-community-standup-september-2025

1. External Modules (traditional approach)

Setup - install Oqtane Framework source code, create module using External Module Template (which creates a separate solution/projects)
Development - develop/debug module - assemblies and static assets are copied to the Oqtane Framework folder
Deployment - build module in Release mode and a Nuget package is created which can be deployed
Upgrade - upgrade the framework independently from your module projects

Scenario - create individual modules which will be managed independently
Pros - granular deployment of module Nuget packages, allows debugging into Oqtane Framework
Cons - non-standard environment setup, "magic" deployment of assemblies/assets to Oqtane Framework folders (ie. debug.cmd, release.cmd), difficulty consuming third party Nuget packages in modules (ie. need to manually extract assemblies and static assets and include in debug.cmd and nuspec files)

2. Oqtane.Application.Template (new approach)

Setup - create Oqtane application from template (Oqtane Framework is a standard Nuget dependency)
Development - develop/debug modules/themes within the same solution
Deployment - standard deployment process ie. right-click Publish in Visual Studio
Upgrade - update package reference versions in *.csproj - standard .NET upgrade approach

Scenario - create applications which contain multiple modules and themes
Pros - standard Blazor application structure, supports standard .NET tooling and deployment, consume third party Nuget packages simply, prevents modifying Oqtane Framework, allows customization of Program.cs which makes some integrations easier (ie. .NET Aspire)
Cons - does not allow debugging into Oqtane Framework code