Understanding Weex Runtime Architecture

Cross-Platform Rendering Pipeline

Weex separates UI description (written in Vue, Rax, or vanilla JS) from native rendering via a bridge architecture. At runtime, JavaScript bundles are downloaded and interpreted by Weex SDKs, which delegate view rendering to native components. Rendering issues occur when there’s a mismatch between the interpreted JS instructions and the underlying native module capabilities.

Component Loading Modes

• Statically bundled components inside the app package
• Dynamically fetched .js bundles from CDN or local server
• Hybrid apps using WebView+Weex combinations

Root Cause: Rendering Failures Due to Native-JS Mismatch

Symptoms

• White screen or partially rendered UI after navigation
• Logs show "component not found" or "unknown module" errors
• Some components render correctly on Android but not iOS (or vice versa)
• Hot reloaded content works locally but fails after OTA update

Technical Root Causes

• Version mismatch between JS bundle and native SDK version
• Component registration failure due to incorrect lifecycle hook
• Asynchronous data not hydrated before component instantiation
• Race conditions in dynamic routing or conditional rendering paths

// Example log error
[Weex][error] [native] [component:chart-view] not found.
// Caused by missing native module registration during cold start.

Diagnostics: How to Reproduce and Trace the Issue

Step-by-Step Debugging

1. Reproduce in production mode with OTA bundle enabled and DevTools disabled
2. Enable verbose logging in Weex SDK (WXEnvironment.isApkDebug for Android, WXLogLevelAll for iOS)
3. Use onCreate lifecycle callbacks to log native module registration order
4. Compare JS bundle version checksum with native app’s declared version code
5. Use Chrome remote debugging to inspect JS errors and module registration at runtime

Key CLI Command

# Validate bundle checksum during OTA deployment
shasum -a 256 dist/index.weex.js

Common Pitfalls in Enterprise Weex Apps

1. CDN Cache Drift

CDNs may serve stale JS bundles even after native apps are updated, leading to bundle-native incompatibility.

2. Asynchronous Component Mounting

Components using v-if or asyncData() may render before data is hydrated, causing blank views.

3. Missing Platform-Specific Registration

Native components not registered correctly for both Android and iOS can cause selective rendering failures.

Fixing the Issue

Short-Term Workarounds

• Pin both JS and native SDK to synchronized versions
• Wrap conditional components with v-show instead of v-if to avoid reinitialization
• Force native re-registration of all components on app cold start
• Use fallback UI for critical components via try-catch blocks in JS

Long-Term Solutions

• Implement semantic versioning between JS bundle and native runtime
• Automate bundle-native version alignment in CI/CD pipelines
• Introduce component-level health checks before render
• Cache invalidate old bundles using query string hashing in CDN URLs

// Example: dynamic component loader with error guard
const SafeComponent = () => import('@/components/CustomChart.vue')
  .catch(err => {
    console.error('Failed to load component:', err);
    return import('@/components/FallbackChart.vue');
  });

Best Practices

• Lock native SDK and JS bundle versions with mutual compatibility contracts
• Always run end-to-end tests with OTA bundles in staging
• Use platform-specific logs to validate native registration order
• Document all third-party component dependencies and platform constraints

Conclusion

While Apache Weex enables high-performance cross-platform development, real-world deployments must carefully manage JS-native compatibility and async lifecycle behavior. Issues like white screens or missing modules often originate from bundle drift, registration timing, or CDN inconsistency. Through deterministic CI/CD practices, dynamic guard clauses, and platform-aware monitoring, teams can eliminate hard-to-reproduce rendering bugs and deliver reliable user experiences across Android and iOS.

FAQs

1. Why does a component render on Android but not on iOS in Weex?

Most likely the native module was registered only on one platform. Ensure platform-specific registration is handled consistently during startup.

2. How can I debug Weex rendering issues in production?

Enable verbose logging in Weex SDK and use Chrome DevTools to inspect JS execution and view structure remotely.

3. What causes white screens after OTA update?

A white screen often indicates a JS-native version mismatch or a failure to load dynamic components due to stale or corrupted bundles.

4. Should I use v-if or v-show for conditional rendering in Weex?

Prefer v-show for critical components, as it avoids teardown and reinitialization that may trigger async loading failures.

5. How do I synchronize native and JS bundle versions in Weex?

Include a semantic version string in both the JS bundle metadata and the native app, and enforce validation before rendering begins.