[BUG] Oqtane 5.1.2 has 48 ways to render Modules - many with problems - making module development hard

[iJungleboy]

Oqtane Info

Version - 5.1.2
Render Mode - Many | Interactivity - Many | Database - SQL Server

Describe the bug

I (@iJungleboy) am one of the core developers of 2sxc.

Together with @tvatavuk I've been working on getting 2sxc to run with Oqtane SSR for the last few months.
This is just a short summary of the challenges we're having, since I feel that we're probably one of the few developers that somehow need (and test) just about every thinkable combination of usages.

Just an example
A static rendering Module loading on an SSR site when the user lands on the site the very first time...
behaves differently than the very same module with SSR on SSR Site
...but when a user navigates to it because he was on another page before.

So just one up ca. 6 rendering parameters changes, and things can break.

Since 2sxc is used in as many thinkable scenarios as Oqtane itself - from content management to module development - we are forced to test just about every thinkable combination of scenarios and need to rely on various features of the platform such as loading JavaScripts etc.

We are very keen to support the latest Oqtane, but as of today it's still a game of whack-a-mole. There are so many render scenarios ATM and so many edge cases which behave either differently or don't fully work (throwing errors).

I wanted to post this to raise awareness, but also to possibly collect insights.
Some examples of things that are currently not working vs. things that are.

Site Variations

1. ✅ Oqtane (without 2sxc) on main site with domain - eg. localhost:243/ or site1.oqtane.me/ - works
2. ✅ Oqtane (without 2sxc) on sub site with own domain - eg. site2.oqtane.me/ - works
3. 🛑 Oqtane (without 2sxc) on sub site with subfolder - eg. site1.oqtane.me/site2/ - errors when loading and fails on most operations

Navigation Variations

1. ✅ SSR, 2sxc on a page which was loaded as the entry page - module.js (in Resources) is loaded by Oqtane
2. 🛑 SSR, entry page is a page without 2sxc, navigate "softly" to a page with 2sxc - module.js is not loaded by Oqtane

Render Mode Variations Site/Module combined with navigation variations

As of now I feel like we have sooo many variations to test & cater to - it's crazy. If a developer is just creating his own solution, this may not bother him because he'll pick his preferred mode, but a module that should work in all cases - ideally optimized to each case.

Up to 48 ways to render a Module

So ATM we seem to have at least these combinations:

1. 2 Site Render Modes: Interactive / Static / Headless (not counted)
2. (ignoring for now: Hybrid yes/no)
3. 3 Site Interactivity: Server / Client / Auto (which I believe would try to transition from server to client)
4. 2 Prerender modes: yes / no (yes means that in some cases the page will behave differently, as the HTML will be created/flushed, but it's relevant for google) - kind of only applies to Server Render Interactive
5. 2 Module Render Mode Interactive / Static
6. 2 Navigation variations First Entry (real link / F5) / Soft navigation (magic partial page reload - with different behavior on JS/CSS loading)

Notes

• I'm still not sure if the theme or container could also be static vs. interactive - which may again change the combinations.
• ATM we're also challenged by sub-site vs. main site issues, but this is not a module-rendering issue for now, so I won't count it

I was going to create a table to show the different scenarios which are possible but it would just be way too long. Basically a module developer is faced with up to 48 ⚠️ different ways the module could be rendering. And as of now, every combination seems to have slightly different challenges an different levels, incl.

1. How to ensure JS/CSS is loaded on the page
2. HTML headers (e.g. meta keywords, Open-Graph headers, custom headers)
3. Events triggered on the module (pre-on-load and on-load style events)
4. Initialization / reading of page parameters (ATM some modes work better than others, especially on soft-navigations)

The complexity for module developers is very, very challenging.

It is also impossible to document any recommendations as of now, as the target is still moving quickly. E.g. we had a 2sxc for 5.1.1 (but we didn't want to release it yet because of Oqtane problems) but we had to redo most of it in 5.1.2 because so many small details didn't quite work any more.

Recommendations

1. We need a fairly comprehensive list of things a module might want to do - e.g. preload js/css, optional-load js/css, set headers, just create html-output, include inline-script, etc.
2. For each of these things we need two or three recommendations
   1. The simplest possible way this works in all 48 scenarios (ATM we're just guessing and often forced to use multiple methods for the same problem)
   2. Possibilities to optimize it if the developer wants to provide an enhanced experience for each possible scenario
3. ...and Oqtane should focus on testing each of these variations - eg. with specially made test-modules and sites with ever possible setup for the next releases, until we are certain it's stable

[sbwalker]

There was a slide in the webinar I presented a few months ago (https://m.youtube.com/watch?v=1rwNc8ldIxI) titled "with great power comes great responsibility" which specifically called out the fact that Blazor now has so many capabilities that it creates challenges for software developers on how to utilize it effectively.

That being said, the overarching goal for Oqtane has always been to allow software developers to leverage all of Blazor's capabilities... in a more cohesive, powerful, and maintainable manner than what is offered by the default Blazor project template.

This has been an extremely complex challenge. Building a framework on top of a framework is a bit like building a house on quicksand... especially a framework like Blazor which has been constantly evolving with every release of .NET. The changes in .NET 8 for SSR were especially complicated to integrate... in many ways it felt similar to the transition from Web Forms to MVC.

So yes I would agree that developing for Blazor can be complex - especially when building a solution which needs to support all render modes and configurations. It has required a huge amount of effort to deliver this capability in Oqtane. So I can definitely relate to the challenges you are describing for 2SXC.

And yes there are a lot of potential run-time variations. The flexibility and versatility of Oqtane is one of its greatest attributes. And since it's an open source solution it relies on the community to contribute by providing specific feedback on their experiences so that the solution can be improved for the benefit of everyone.

On that note, a "BUG" should provide details so that an issue can be reproduced, investigated, and resolved. Comments such as "subfolders throw errors in many cases" are not helpful as they offer no actual details which would allow the issue to be resolved.

[tvatavuk]

Thank you so much for the constructive help and great explanation! 😊

I wanted to bring to your attention an issue we're facing in a sub-site, which is preventing us from updating our production sites to the latest and greatest Oqtane v5.1.2. You can find the details here: Issue #4339. 🚧🔧

Additionally, a special shout-out for the amazing video on Building Beautiful Blazor Websites in .NET 8! 🎥🌐

Thank you! 🙏

[tvatavuk]

Here is another issue that happens in Interactive Server Sub-Site #4349

[sbwalker]

@tvatavuk I will investigate #4339 and #4349 - thank you for providing the details.

[sbwalker]

@iJungleboy I am not sure how to take action on this item. Certainly for your specific scenario involving the development of 2SXC which needs to support ALL render modes and configurations, development and testing is challenging. However your scenario is NOT the typical scenario. The MAJORITY of developers are NOT creating solutions which need to support ALL render modes and configurations - they are building solutions designed to solve a specific business problem which means that they will choose a specific render mode and configuration which matches their requirements. So although I can sympathize with your perspective (because Oqtane itself needs to handle all render modes and configurations) this issue is not constructive to the broader Oqtane community.

[iJungleboy]

@sbwalker I believe there are a few important action items here, that affect everybody.

1. We (probably myself) should document the many variations of how things happen, and how they behave differently and how they should be addressed. I can start the documentation, but I'm not sure myself how each scenario is thought to be addressed, so I would need your help there.

2. These docs will certainly be helpful, but could also be daunting. So we need to provide a simplified decision tree which path we would recommend for certain scenarios - so that developers are not trying to cover every case, but have some simple "do this and it will always work". As of now, I simply wouldn't know what to recommend, so here too I will need your guidance.

3. In terms of a getting-started guidance, I believe we should be even simpler and recommend a single "if you're getting started - here's what we recommend"

4. To reduce friction even more, I would also like to suggest that we allow the "Enhanced Navigation" to be turned off. I believe that for 95% of web scenarios this would be preferred and reduce a lot of debugging, especially until it's really matured.

[sbwalker]

@iJungleboy one of the Oqtane philosophies is "Microsoft Alignment". In .NET 8 the default Blazor application template is configured to use Static rendering with Enhanced Navigation enabled... and this is the reason why Oqtane followed this same approach in the 5.1 release. Note that if Enhanced Navigation is disabled, the application will use a full page refresh model - which from a user experience perspective is a significant step backwards (and is not consistent with the other UX approaches in Oqtane/Blazor). It is technically possible to disable Enhanced Navigation using an inline script (see https://www.telerik.com/blogs/blazor-enhanced-navigation-fully-explained) however this would then make 96 different combinations which need to be supported in the framework - which seems be the opposite of what you were advocating for in your original post?

On your other points, I agree that docs would be useful. We have discussed this topic previously... so I know you are already very familiar with the challenges related to docs.

[iJungleboy]

@sbwalker thanks for that post, I'm learning new stuff all the time 😉

Actually it wouldn't add any new combination - it would simply enforce the same behavior on navigation as when a user enters the page directly - which is a case the developer must always cater to anyhow.

I could imagine that this would be something to revisit some day - eg. if for certain reasons specific pages should never be soft-navigated to. But we'll move that to the probably-won't-happen-backlog.

I'll still try to get the docs to describe all these aspects and would then get back to you for what we should make the best recommendations for people getting their feet wet.