FAQ

The redirect parameter is double-encoded on Web (%252F)?

Known behavior. The round-trip is correct (guard registration and return-jump restoration match); verify on a real device before shipping to Android for deep-link scenarios.

The console shows NavigationFailure logs?

Known ux-router behavior on Web (a confirmation log after relaunch); the navigation result is correct and should not be treated as an error.

Why not standard Pinia for state management?

uni-app x's App side (Kotlin) does not support standard Pinia's plugin protocol (app.use verified not to work), and UTS has no Proxy and no reflection, making standard Pinia's reactivity model impossible to implement. ux-pinia implements a Pinia-style API within UTS using a class + reactive architecture (see the "Differences from Standard Pinia" chapter in the unix-pinia docs).

Why doesn't the token use ux-pinia's built-in persistence plugin?

Separation of concerns: token read/write is consolidated in utils/auth.uts (mirroring js-cookie's responsibility), and the ensureAuthReady() cold-start race elimination design is verified end to end; the built-in persistence defaults to uni storage, and coexisting with ux-storage would split persistence semantics. The built-in persistence is reserved for business-state scenarios (such as drafts).

ux-storage is asynchronous — why is reading the token synchronous?

Smoothed by an in-memory cache: writes take effect in memory immediately and persist asynchronously; at cold start the first line of the guard chain, await ensureAuthReady(), restores the memory cache once (Promise reuse, no races). See Auth & Guards.

Release packaging (cloud packaging / release to Web) fails, but dev works?

Pitfalls caused by differences between the release pipeline and dev have been fixed in the template (verified on 5.34):

• UTS plugin entry points must not export string constants (uts-proxy generates invalid JS);
• Domain types must be defined within the single <domain>/types.uts file (release builds do not follow export type ... from forwarding chains);
• Inside plugin components, avoid Animation type annotations, script-level slots.default checks, and watch with flush (Unresolved in the 5.34 Kotlin generator).

See the Fixed section of CHANGELOG 1.1.0 in the repository.

Android cannot connect to the local mock?

127.0.0.1 on a real device points to the phone itself. Change baseURL in config/index.uts to the computer's LAN IP (e.g. http://192.168.x.x:3210), keep the phone and computer on the same network, and make the mock service listen on 0.0.0.0.

Guards don't take effect after navigating to a new page?

Check two things: the page declares the defineUniPage({ name, title }) macro (the route table is generated by the plugin); navigation goes through useRouter() rather than the uni.navigateTo family (the latter is intercepted by the InterceptorPlugin fallback, but the fallback must not be relied upon).

Are there HBuilderX version requirements?

The template completed compilation and packaging verification on 5.34 (Web + Android cloud packaging). Earlier versions are unverified; newer versions require attention to UTS compiler behavior changes.