Framework
jd-opensource/micro-app avatar
jd-opensource/micro-app

micro-app: JD's Web Component Micro Frontend, Reviewed for Adoption

A simple, efficient and powerful micro front-end framework.

6,262 stars644 forksCSSMIT

At a glance

What is it?
micro-app is a micro frontend framework from JD Retail that loads sub applications through a custom element and a JS sandbox. It is easy to start with, but the Proxy requirement and mandatory CORS on every sub app shape where it fits.
Who is it for?
Adopt micro-app when you have an existing page that must host sub applications built by other teams, and when all of those apps can serve CORS headers. Do not adopt it if you still support IE.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 33 days ago.
What is it written in?
Mainly CSS, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • jd-opensource/micro-app6,262 ★ · +8
Star history
Repository2026-09-232026-11-15
jd-opensource/micro-app6.3k6.3k

8 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What micro-app solves, and who it is for

A large front end usually ends up as several applications owned by different teams, all needing to appear inside one page. The usual answers are iframes, which fight you on routing and styling, or a build time monorepo, which forces every team onto one toolchain. micro-app takes a third route: the base application drops a custom element into its template, points it at a URL, and the framework pulls in the sub application at runtime.

The README describes it as a micro frontend framework launched by JD Retail that renders based on webcomponent-like behavior, with the stated goal of reducing the difficulty of getting started. It also states that micro-app has no restrictions on the front end framework: any framework can be the base application and any framework can be the sub application. That is the real audience. Teams that already have a shell written in Vue or React and need to mount a sub app written in something else, without a rewrite.

It is less suited to greenfield projects where one team owns everything. If you control the whole codebase, a monorepo gives you type checking across boundaries and a single build graph, and micro-app gives you neither.

How the custom element and JS sandbox actually work

The base application starts the framework once with microApp.start() at the entry point. After that, a <micro-app> tag with a name and url attribute acts as the mount point. The name is the app identifier and the url is the address the framework fetches from.

Because the fetch is a normal browser request rather than a build time import, the sub application is loaded as a remote resource. That single design decision explains most of micro-app's constraints. It is why cross domain headers are mandatory, why the sub application must be reachable at runtime, and why the base app can host an app it has never built. The README lists the accompanying machinery: JS sandbox, style isolation, element isolation, preloading, resource address completion, plugin system and data communication. Style and element isolation matter most in practice, since they are what an iframe gives you for free and what you lose by not using one.

The sandbox relies on Proxy, and the README is explicit that Proxy is not compatible for the time being and that micro-app cannot run on browsers that do not support it. CustomElements is the other dependency, and for that one the README points to webcomponents polyfills as a workaround. So one of the two core APIs has an escape hatch and the other does not.

Installing micro-app and rendering a first sub application

The README gives a three step path for the base application. Install the package from npm under its scoped name, then import and start it at the entry point.

bash
yarn add @micro-zoe/micro-app
js
// main.js
import microApp from '@micro-zoe/micro-app'

microApp.start()

With the framework started, the base application uses the element like any other tag. The README's example is a Vue template, and it uses two attributes, name and url.

html
<!-- my-page.vue -->
<template>
  <!-- 👇 name is the app name, url is the app address -->
  <micro-app name='my-app' url='http://localhost:3000/'></micro-app>
</template>

The sub application side needs one change before any of this works. Its dev server must send a cross domain header, and the README shows the webpack-dev-server form.

js
devServer: {
  headers: {
    'Access-Control-Allow-Origin': '*',
  },
},

If the header is missing, the browser blocks the fetch and the element stays empty. The README notes that for production you support cross domain through nginx configuration instead. After both sides are running, the sub application should render inside the base page at the url you gave.

Cross domain and Proxy are hard requirements, not options

Most micro frontend frameworks treat isolation as a feature. In micro-app it is closer to a precondition. The README answers the cross domain question with a flat yes, and then explains that development uses webpack-dev-server headers while production uses nginx. There is no documented mode where a sub application is bundled into the base app and therefore exempt.

That has an operational cost people underestimate. Every sub application becomes a separately deployed origin that must be reachable from the browser and must return the right header. If your organization routes internal traffic through a gateway that strips or rewrites headers, you will discover this during integration rather than during design. The README does not document a fallback for a sub application that cannot set CORS headers.

The Proxy requirement is the harder boundary. The README states plainly that micro-app cannot run on browsers that do not support Proxy, and that browser compatibility is broadly desktop except IE, with mobile at ios10+ and android5+. For a consumer facing product with a long tail of older Android webviews, that is a real constraint and not a theoretical one. The CustomElements dependency, by contrast, is softened by polyfills.

Where micro-app is the wrong tool

The README answers yes to SSR support and points to nextjs and nuxtjs pages; check those pages for how server rendering interacts with micro-app's runtime loading before relying on it.

If your sub applications cannot be served as separate origins, the framework's core assumption breaks and you are better served by a build time approach such as npm workspaces or a monorepo with shared packages. Similarly, if the boundary between your applications is a data boundary rather than a UI boundary, module federation style composition or a plain shared library may be less machinery for the same result.

There is also an honest versioning caveat. The newest release listed is 1.0.0-rc.32 from 2026-06-25, preceded by 1.0.0-rc.31 and 1.0.0-rc.30. The project is publishing release candidates, not a stable 1.0.0. That does not make it unusable, and the last push to the repository was on 2026-10-13, but it does mean you should pin an exact rc version and read the release notes before moving.

Alternatives and the difference in approach

The closest comparison is single-spa, which also composes applications at runtime, but it works through a registered application lifecycle rather than a custom element in your template. With single-spa you write registerApplication calls and the framework decides when to mount and unmount; with micro-app you place a tag with a name and url and the element's presence in the DOM drives the lifecycle. The micro-app README's stated advantage is that it is low invasive and needs only a small amount of code, and the tag based model is the concrete reason.

If your teams already share a build, module federation in webpack 5 is a different trade-off: shared dependencies and a build time graph instead of a runtime fetch, which removes the CORS requirement entirely but couples the applications to a compatible bundler and shared dependency versions. micro-app does not require that coupling, which is exactly why it needs the header.

For simple cases, an iframe remains the cheapest isolation mechanism and needs no framework at all. micro-app's value over an iframe is routing, style and element isolation that behave like part of the host page rather than a separate document.

Maintenance, licensing and what upgrading costs

The repository is not archived and the last push was on 2026-10-13, so the codebase is being touched. The three most recent rc versions came out on 2026-04-20, 2026-06-09 and 2026-06-25, which suggests active iteration on the 1.0 line. Treat that as a signal about churn, not about stability: release candidates can change behavior between versions.

Licensing is MIT, per the LICENSE file and the badge in the README. MIT permits commercial use, modification and redistribution with the licence and copyright notice retained. That is a permissive starting point, but it says nothing about the licences of the sub applications you load or the dependencies you add alongside it, and it is not legal advice.

The upgrade cost is mostly on the base application. Because the integration surface is one start call and one custom element, the base app changes little between versions. The risk sits in the sandbox and isolation internals. Pinning an exact version in package.json and reading the release notes for each rc is cheaper than discovering a sandbox behavior change in production.

Editorial conclusion

Adopt micro-app when you have an existing page that must host sub applications built by other teams, and when all of those apps can serve CORS headers. Do not adopt it if you still support IE. Before committing, verify three things: that your sub applications can return Access-Control-Allow-Origin in production, that your target browsers support Proxy, and that the release you pin is a 1.0.0-rc build rather than a stable 1.0.0, since the newest published version is 1.0.0-rc.32 from 2026-06-25.

Frequently asked questions

What is micro-app and what is it used for?

micro-app is a micro frontend framework from JD Retail that renders based on webcomponent-like behavior and lets a base application embed sub applications at runtime. The README states it has no restrictions on the front end framework, so any framework can be the base and any framework can be the sub application.

What are some examples of micro apps built with micro-app?

The README does not list production examples or case studies. The repository does contain a dev directory with base and child applications such as main-react16, main-vue2, main-vite and children for react16, react17, vue2, vue3, vite2, vite4 and angular11, which are the working examples the project ships.

Does micro-app support Vite and SSR?

Yes to both, according to the README FAQ. It links to an adapt vite page for Vite, and to nextjs and nuxtjs pages for server side rendering.

Official sources

  1. jd-opensource/micro-app on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/jd-opensource-micro-app.svg)](https://hysenlabs.com/projects/jd-opensource-micro-app)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/jd-opensource-micro-app.svg)](https://hysenlabs.com/projects/jd-opensource-micro-app)

Was this useful?