Streamline the setup of single page applications (SPAs)

[rodja]

Problem

With the ui.sub_pages element from #4821 it will very simple to create single page applications. But because NiceGUI is based on FastAPI, the main page requires rather technical route definitions to catch all paths:

@ui.page('/')
@ui.page('/{_:path}')
def main():
    ui.sub_pages({...})

Proposed Solution

Add a root parameter to ui.run() that accepts a function which is automatically registered for / and /{_:path} routes in FastAPI. Thereby it is called for every user visit and builds the full UI (including possibly defined sub pages):

Full Example

from nicegui import ui

def main():
    ui.label('My SPA')
    ui.sub_pages({
        '/': home,
        '/about': about,
        '/contact': contact,
    })

def home():
    ui.label('Home Page')

def about():
    ui.label('About Page')

def contact():
    ui.label('Contact Page')

if __name__ == '__main__':
    ui.run(root=main)

Additional to the much simpler (and more intuitive) single page app setup, we could possibly use this technique as a replacement for the auto-index client (see #4472) which is quite a complex maintenance burden. The main benefit of the auto-index client was that it allows super simple scripts like this:

from nicegui import ui

ui.label('Hello World!")

ui.run()

Internally a / route is registered on from nicegui import ui and the label is placed on this "hidden page". The UI is not re-evaluated per visit but rather a copy is send to each client. This leads to possible unexpected behaviour.

With the root parameter in ui.run a minimal application would look like this:

from nicegui import ui

def main():
    ui.label('Hello World!")

ui.run(root=main)

Of course root should be an optional parameter. If it is not provided, developers could still use the @ui.page(...) decorator to register pages as they please.

[falkoschindler]

Two thoughts:

1. Maybe root can be a positional argument so that we can write ui.run(main).
2. A common pattern in Python is to create a main function which is called inside a main guard. This would conflict with the new root=main convention. Maybe root() is a better function name:

   from nicegui import ui
   
   def root():
       ui.label('Hello, World!')
   
   def main():
       ui.run(root)
   
   if __name__ == '__main__':
       main()

[falkoschindler]

Or is index() an even better name?

[rodja]

A few days ago @falkoschindler and me talked a intensivly about this feature and the general implications of moving more towards SPA applications. One main topic was the interplay between an SPA and other FastAPI routs. As can be seen with issues like #5001, it can become quite complicated to archive the desired routing result. The core issue is the "catch-all" FastAPI route which is needed to enter the SPA:

@ui.page('/')
@ui.page('/{_:path}')  # NOTE: our SPA should catch all paths

In #5005 I now sketched an idea we had for a late-catch-all: instead of registering FastAPI routes for the SPA, the root builder function can simply be evaluated in the FastAPI 404 handler. The PR is currently just a feasibility test. But I find this approach very promising.

[falkoschindler]

PR #5005 has been merged and will be released as part of version 3.0.