qiankun vs single-spa: Architecture, Isolation, and Setup Compared

Both qiankun and single-spa solve the same fundamental problem: how to run multiple frontend applications within a single browser tab without them breaking each other. However, they approach this challenge with different levels of abstraction and built-in safeguards. Let's compare how they handle registration, isolation, and communication.

🏗️ Registration and Routing Setup

single-spa requires you to manually define activity functions that determine when an app should be active. You register each application individually with a name, a loading function, and a condition.

// single-spa: Manual registration with activity function
import { registerApplication, start } from 'single-spa';

registerApplication({
  name: '@myorg/app-one',
  app: () => System.import('@myorg/app-one'),
  activeWhen: (location) => location.pathname.startsWith('/app-one'),
  customProps: { store: myStore }
});

start();

qiankun simplifies this by grouping registrations into a single configuration array passed to registerMicroApps. It handles the routing logic internally based on the activeRule.

// qiankun: Batch registration with activeRule
import { registerMicroApps, start } from 'qiankun';

registerMicroApps([
  {
    name: 'app-one',
    entry: '//localhost:7100',
    container: '#container',
    activeRule: '/app-one',
    props: { store: myStore }
  }
]);

start();

🛡️ JavaScript Isolation: Sandboxing

single-spa does not provide JavaScript sandboxing out of the box. If two apps modify the same global variable (like window.user), they will conflict. You must rely on build tools (like Webpack Module Federation) or strict coding conventions to avoid this.

// single-spa: No built-in sandbox
// Risk: App A and App B both access window.globalConfig
window.globalConfig = { theme: 'dark' }; // App A
window.globalConfig = { theme: 'light' }; // App B overwrites it

qiankun includes a JavaScript sandbox that runs micro-apps in a Proxy-based environment. This prevents child apps from polluting the global window object, ensuring that global variables stay local to the app.

// qiankun: Proxy Sandbox enabled by default
// App A modifies window within its sandbox
window.localConfig = { theme: 'dark' }; 
// App B cannot see window.localConfig from App A
// When App A unmounts, the sandbox cleans up global side effects

🎨 CSS Isolation: Styling Boundaries

single-spa relies on CSS naming conventions (like BEM) or CSS Modules to prevent style conflicts. It does not automatically scope styles, so a global CSS reset in one app can break another.

/* single-spa: Manual scoping required */
.app-one-button { background: blue; } /* Must use unique prefixes */
.app-two-button { background: red; }

qiankun offers built-in CSS scoping. It can rewrite styles to ensure they only apply within the micro-app's container. It also supports Shadow DOM for stricter isolation, though this comes with its own trade-offs regarding event bubbling.

/* qiankun: Automatic scoping via data attributes */
/* qiankun adds data-qiankun-app-one to the container */
[data-qiankun-app-one] .button { background: blue; }
/* Styles are scoped automatically during runtime */

🔄 Lifecycle Management

single-spa expects each micro-app to export specific lifecycle functions (bootstrap, mount, unmount). The framework calls these at the right times, but you must implement them in every sub-application.

// single-spa: Explicit lifecycle exports in sub-app
export async function bootstrap(props) { /* init */ }
export async function mount(props) { /* render */ }
export async function unmount(props) { /* cleanup */ }

qiankun also uses these lifecycle hooks but wraps them to handle the sandboxing and container mounting automatically. If you are using a supported framework (like Vue or React), qiankun provides helpers to reduce boilerplate.

// qiankun: Lifecycle with sandbox context
export async function render(props) {
  const { container } = props;
  // Render logic here, qiankun handles the container injection
  ReactDOM.render(<App />, container.querySelector('#root'));
}

export async function mount(props) { render(props); }
export async function unmount(props) { /* cleanup */ }

📡 Global State Communication

single-spa does not enforce a specific way to share state between apps. Developers typically use custom events, a shared store module, or browser storage (localStorage).

// single-spa: Custom event bus pattern
window.dispatchEvent(new CustomEvent('USER_LOGIN', { detail: user }));
// Another app listens for this event

qiankun provides a built-in global state API called initGlobalState. This allows the main app and micro-apps to share reactive data without setting up external libraries.

// qiankun: Built-in global state
import { initGlobalState } from 'qiankun';

const actions = initGlobalState({ user: null });
actions.onGlobalStateChange((state) => {
  console.log('User updated:', state.user);
}, true);

🌱 When Not to Use These

These libraries are powerful but add complexity. Consider alternatives when:

• You are building a small application – A monorepo with simple routing is easier to manage.
• You need SEO for all sub-routes – Server-side rendering across micro-frontends is difficult to configure correctly.
• Your team lacks DevOps maturity – Micro-frontends require independent deployment pipelines; without them, you gain no benefit.

📌 Summary Table

💡 Final Recommendation

Think in terms of isolation needs and team structure:

• Need strict separation? → Go with qiankun. The built-in sandboxing saves time and prevents hard-to-debug global conflicts.
• Need maximum flexibility? → Go with single-spa. It gives you the raw tools to build your own architecture without hidden magic.
• Migrating a monolith? → qiankun is often easier for incremental adoption because it handles more edge cases automatically.

Final Thought: Both tools enable the same architectural pattern, but qiankun acts as a batteries-included layer over single-spa. If you don't need the extra isolation features, single-spa keeps your dependency tree smaller. If you need enterprise-grade safeguards, qiankun is worth the trade-off.