State Controller

[pi0]

Over the time, nuxt building process became more and more complex and while there is no clear visualization of what is happening, improving user experience would be hard.

Goals of this issue:

• Describe current flow as parallel state machines
• Help writing internal documentation to describe how nuxt works
• Implement unified state controller based on nuxt hooks for nu cli and dev tools for smooth and managed user experience
• Using visualization to ensure all cases are handled in dev flow
• Discover improvement areas

Next Steps

• Evaluate current machines
• Extract fsm tables (state, error and event codes)
• Implement global controller based on FSM machine and nuxt hooks
• Write internals documentation
• [reevaluate issue]

Config State

• Source: cli

Upon initialization or when nuxt.config is changed, this process starts. Updating config causes full nuxt restart.

Improvement areas:

• Watch nuxt.config dependencies
• Accept nuxt hook to manually trigger init
• Diff from old config and use a hook to see there is a client accepting change, avoid restarting (config HMR)

Core State

• Source: nuxt3

When config is (re)loaded, the core has to be initialized. It involves assigning defaults, validating config, and initializing all nuxt modules.

Improvement areas:

• Trigger restart if a module is changed

App State

• Source: nuxt3

Nuxt uses a templating engine to generate code based on project structure and config. If a file/dir is created or removed from this structure, we need to repeat generate process. This starts when the core is ready.

Improvement areas:

• Partial generate (updating only one template)
• Use virtual filesystem to write files

Bundler state

• Source: webpack, vite

When app code is ready, we use either webpack or vite to generate client, server bundles.

Improvement areas:

• Unify progress and error state for vite and webpack

Nitro State

Nitro, is the server engine for nuxt. Wrapping server code with bundle dist to make final server using rollup. For performance reasons, nitro does not wait until the bundle is ready (which involves app generation) and lazy loads bundle.

• Source: nitro

Improvement areas:

• Sync with bundle state to keep the user waiting instead of error (while bundle is not ready)
• Sync with nitro state to keep user waiting instead of refresh method (while nitro is not ready)
• Reuse the previous bundle (offline cache) if possible
• Better sync with CLI

CLI state

Due to parallel complexities, cli is not visualized but it is how nu dev works:

• Start a server immediately
• Initialize core
• Start app build
• Replace server with nitro when ready

Improvement areas:

• Sync with the global state (all machines above) for error control
• Use a simple indicator to show status like ora
• Support WebSocket upgrade
• Keep user waiting instead of refresh workaround
• Expose its API to build state-aware dev tools / extension