[ { "path": ".changeset/README.md", "content": "# Changesets\n\nHello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works\nwith multi-package repos, or single-package repos to help you version and publish your code. You can\nfind the full documentation for it [in our repository](https://github.com/changesets/changesets)\n\nWe have a quick list of common questions to get you started engaging with this project in\n[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)\n" }, { "path": ".changeset/big-cougars-draw.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfeat(sandbox): use cloneNode api instead of importNode for compatible\n" }, { "path": ".changeset/clean-walls-hang.md", "content": "---\n\"@qiankunjs/bundler-plugin\": patch\n---\n\nfix: move cheerio to dependencies\n" }, { "path": ".changeset/clever-carpets-vanish.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nRevert \"fix(sandbox): non-hijacking elements should be appended to global document (#2861)\"\n" }, { "path": ".changeset/clever-dragons-ring.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/loader\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\n✨support to transform head/body tags to qiankun head/body in stream\n" }, { "path": ".changeset/config.json", "content": "{\n \"$schema\": \"https://unpkg.com/@changesets/config@2.29.5/schema.json\",\n \"changelog\": \"@changesets/cli/changelog\",\n \"commit\": true,\n \"fixed\": [],\n \"linked\": [],\n \"access\": \"public\",\n \"baseBranch\": \"next\",\n \"updateInternalDependencies\": \"patch\",\n \"ignore\": [],\n \"___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH\": {\n \"onlyUpdatePeerDependentsWhenOutOfRange\": true\n }\n}\n" }, { "path": ".changeset/empty-jars-vanish.md", "content": "---\n'create-qiankun': minor\n---\n\nfeat: introduce qiankun scaffold\n" }, { "path": ".changeset/empty-lions-rescue.md", "content": "---\n'@qiankunjs/shared': patch\n---\n\nfix: remove inline script source-url\n" }, { "path": ".changeset/five-papayas-buy.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfix: optimize types and add a warning for preload\n" }, { "path": ".changeset/forty-teachers-taste.md", "content": "---\n'@qiankunjs/ui-shared': patch\n'@qiankunjs/react': patch\n'@qiankunjs/vue': patch\n---\n\nfeat: refactor the code of microapp\n" }, { "path": ".changeset/four-worms-think.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat(sandbox): support dynamic sync scripts executed by order in sandbox\n" }, { "path": ".changeset/friendly-apples-design.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/react\": patch\n\"@qiankunjs/ui-shared\": patch\n\"@qiankunjs/vue\": patch\n---\n\nfix: remove unused umd bundle configuration\n" }, { "path": ".changeset/giant-geckos-love.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfix: double quote link element href as selector\n" }, { "path": ".changeset/green-pants-remember.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: add isRuntimeCompatible api to check qiankun3 compatibility\n" }, { "path": ".changeset/green-tools-wonder.md", "content": "---\n\"@qiankunjs/shared\": patch\n---\n\n🐛fix findDependency logic while peerDeps is undefined\n" }, { "path": ".changeset/hungry-needles-doubt.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: support defer scripts and keep the executing order to consist with browser\n" }, { "path": ".changeset/itchy-pears-retire.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n---\n\nfeat: pass container with parameters rather than getter function\n" }, { "path": ".changeset/itchy-snakes-tell.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n---\n\nfeat(loader): add lru cache for assets fetch by default\n" }, { "path": ".changeset/large-jokes-smile.md", "content": "---\n\"@qiankunjs/shared\": patch\n---\n\n🐛fix preload is invalid while reused dependency is working\n" }, { "path": ".changeset/lemon-seals-juggle.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat(shared): introduce retryable and throwable to fetch-utils\n" }, { "path": ".changeset/long-flies-repair.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\n🔀 merge master\n" }, { "path": ".changeset/loud-berries-watch.md", "content": "---\n\"@qiankunjs/shared\": patch\n---\n\nrefactor(shared): replace semver with compare-versions\n" }, { "path": ".changeset/loud-penguins-crash.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfeat: set proxy appendChild/insertBefore method for every sandbox rather than modify prototype on HTMLElement\n" }, { "path": ".changeset/loud-teachers-develop.md", "content": "---\n\"qiankun\": patch\n---\n\nfeat: enable sandbox by default\n" }, { "path": ".changeset/lovely-colts-decide.md", "content": "---\n\"create-qiankun\": patch\n---\n\nfeat: introduce qiankun scaffold\n" }, { "path": ".changeset/lucky-bikes-scream.md", "content": "---\n\"@qiankunjs/bundler-plugin\": patch\n---\n\nfix: mv webpack-sources to deps\n" }, { "path": ".changeset/metal-cougars-help.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\n🐛parallel sandbox should use different compartment id\n" }, { "path": ".changeset/mighty-nails-pull.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat(loader): compatible with defer entry script\n" }, { "path": ".changeset/modern-kiwis-tap.md", "content": "---\n\"@qiankunjs/bundler-plugin\": patch\n---\n\nfeat: introduce qiankun webpack plugin\n" }, { "path": ".changeset/ninety-rivers-check.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n---\n\nfeat: add transformer options for app loader\n" }, { "path": ".changeset/orange-boats-allow.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: remove webpack chunk cache attributes just while there are multi instances loaded on document\n" }, { "path": ".changeset/poor-squids-hide.md", "content": "---\n\"qiankun\": patch\n---\n\nfix(qiankun): should remove internal cache of loadMicroApp while loading failed\n" }, { "path": ".changeset/pre.json", "content": "{\n \"mode\": \"pre\",\n \"tag\": \"rc\",\n \"initialVersions\": {\n \"@qiankunjs/loader\": \"0.0.1\",\n \"qiankun\": \"3.0.0\",\n \"@qiankunjs/sandbox\": \"0.0.1\",\n \"@qiankunjs/shared\": \"0.0.1\",\n \"@qiankunjs/react\": \"0.0.1\",\n \"@qiankunjs/bundler-plugin\": \"0.0.1\",\n \"@qiankunjs/ui-shared\": \"0.0.0\",\n \"@qiankunjs/vue\": \"0.0.0\",\n \"create-qiankun\": \"0.0.0\"\n },\n \"changesets\": [\n \"big-cougars-draw\",\n \"clean-walls-hang\",\n \"clever-carpets-vanish\",\n \"clever-dragons-ring\",\n \"empty-jars-vanish\",\n \"empty-lions-rescue\",\n \"five-papayas-buy\",\n \"forty-teachers-taste\",\n \"four-worms-think\",\n \"friendly-apples-design\",\n \"giant-geckos-love\",\n \"green-pants-remember\",\n \"green-tools-wonder\",\n \"hungry-needles-doubt\",\n \"itchy-pears-retire\",\n \"itchy-snakes-tell\",\n \"large-jokes-smile\",\n \"lemon-seals-juggle\",\n \"long-flies-repair\",\n \"loud-berries-watch\",\n \"loud-penguins-crash\",\n \"loud-teachers-develop\",\n \"lovely-colts-decide\",\n \"lucky-bikes-scream\",\n \"metal-cougars-help\",\n \"mighty-nails-pull\",\n \"modern-kiwis-tap\",\n \"ninety-rivers-check\",\n \"orange-boats-allow\",\n \"poor-squids-hide\",\n \"rare-lobsters-marry\",\n \"real-trees-unite\",\n \"red-islands-mate\",\n \"red-students-run\",\n \"rich-parents-relate\",\n \"selfish-lamps-thank\",\n \"serious-nails-jog\",\n \"shaggy-shrimps-drum\",\n \"sharp-files-raise\",\n \"shiny-jeans-sip\",\n \"short-kings-explain\",\n \"shy-mayflies-shave\",\n \"silly-books-complain\",\n \"slow-timers-heal\",\n \"small-experts-hug\",\n \"smart-guests-jam\",\n \"smart-scissors-press\",\n \"smart-scissors-sell\",\n \"smooth-pillows-jam\",\n \"sour-roses-smile\",\n \"spotty-plums-hear\",\n \"stale-dolls-push\",\n \"strong-rocks-sneeze\",\n \"sweet-cars-protect\",\n \"sweet-shoes-brake\",\n \"swift-squids-vanish\",\n \"tall-buttons-pretend\",\n \"tasty-donkeys-relax\",\n \"tender-dingos-allow\",\n \"tender-pots-perform\",\n \"thin-ways-allow\",\n \"three-hornets-hammer\",\n \"tough-beers-grow\",\n \"tough-phones-chew\",\n \"twelve-donkeys-help\",\n \"warm-chefs-chew\",\n \"wicked-icons-type\",\n \"wise-eagles-tease\",\n \"wise-ravens-prove\"\n ]\n}\n" }, { "path": ".changeset/rare-lobsters-marry.md", "content": "---\n\"qiankun\": patch\n---\n\n🐛 fix tsc error\n" }, { "path": ".changeset/real-trees-unite.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfix(sandbox): compatible with dynamically appending stylesheets to detached containers\n" }, { "path": ".changeset/red-islands-mate.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n---\n\nfeat(loader): supports passing Response as entry parameter for loadEntry function\n" }, { "path": ".changeset/red-students-run.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/react\": patch\n---\n\nfix(sandbox): should get container from getter function in every accessing\n" }, { "path": ".changeset/rich-parents-relate.md", "content": "---\n\"@qiankunjs/vue\": patch\n---\n\nfix(vue): add unmount hook to unmount application\n" }, { "path": ".changeset/selfish-lamps-thank.md", "content": "---\n\"qiankun\": patch\n---\n\nfix: should re-init container while app remounted from cache\n" }, { "path": ".changeset/serious-nails-jog.md", "content": "---\n\"@qiankunjs/bundler-plugin\": patch\n---\n\nfix: correct entry script identification and webpack version detection in Vue CLI 5\n" }, { "path": ".changeset/shaggy-shrimps-drum.md", "content": "---\n\"@qiankunjs/bundler-plugin\": patch\n\"create-qiankun\": patch\n---\n\nfix: improve QiankunPlugin webpack compatibility and error handling\n" }, { "path": ".changeset/sharp-files-raise.md", "content": "---\n\"qiankun\": patch\n---\n\nfix(qiankun): remove premature lifecycle check to allow fallback detection\n" }, { "path": ".changeset/shiny-jeans-sip.md", "content": "---\n\"qiankun\": patch\n---\n\nfeat: make loadEntry and beforeLoad runs parallelly\n" }, { "path": ".changeset/short-kings-explain.md", "content": "---\n\"qiankun\": patch\n---\n\n✨add registerMicroApps api\n" }, { "path": ".changeset/shy-mayflies-shave.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: change script src before it execute thus we can be more consistent with the native browser logic\n" }, { "path": ".changeset/silly-books-complain.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfeat(sandbox): micro app mounting should wait unit rebuilding link element loaded to avoid unstyleed content flash\n" }, { "path": ".changeset/slow-timers-heal.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfix(sandbox): createElement hijack must be paired to avoid rewriting leak\n" }, { "path": ".changeset/small-experts-hug.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfeat: support addEventListener with once options to avoid memory leak\n" }, { "path": ".changeset/smart-guests-jam.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nchore: optimize code\n" }, { "path": ".changeset/smart-scissors-press.md", "content": "---\n'qiankun': patch\n'@qiankunjs/sandbox': patch\n---\n\nfeat: optimize lifecycle validate log\n" }, { "path": ".changeset/smart-scissors-sell.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfix: dynamic append element should support for the same container between micro apps\n" }, { "path": ".changeset/smooth-pillows-jam.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: remove lru-cache and move wrapFetch to shared package\n" }, { "path": ".changeset/sour-roses-smile.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/react\": patch\n---\n\nfeat: not rebind non-native global properties\n" }, { "path": ".changeset/spotty-plums-hear.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: improve fetch error message by prepending url\n" }, { "path": ".changeset/stale-dolls-push.md", "content": "---\n\"@qiankunjs/shared\": patch\n---\n\nfeat(transpiler): assets transpiler should work well while sandbox disabled\n" }, { "path": ".changeset/strong-rocks-sneeze.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfix: defer scripts should wait until html loaded\n" }, { "path": ".changeset/sweet-cars-protect.md", "content": "---\n\"create-qiankun\": patch\n---\n\nfix: include template to publish field\n" }, { "path": ".changeset/sweet-shoes-brake.md", "content": "---\n\"@qiankunjs/shared\": patch\n---\n\nfix: should not transform URLs that already include a protocol\n" }, { "path": ".changeset/swift-squids-vanish.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfix(sandbox): fix async script order index calculate\n" }, { "path": ".changeset/tall-buttons-pretend.md", "content": "---\n\"create-qiankun\": patch\n---\n\nfeat: refactor create-qiankun cli\n" }, { "path": ".changeset/tasty-donkeys-relax.md", "content": "---\n\"qiankun\": patch\n---\n\n[#2823] Add legacy APIs for qiankun 3.0\n" }, { "path": ".changeset/tender-dingos-allow.md", "content": "---\n\"@qiankunjs/bundler-plugin\": patch\n---\n\nfix(webpack-plugin):fix webpack module not found during webpack-plugin build\n" }, { "path": ".changeset/tender-pots-perform.md", "content": "---\n\"@qiankunjs/loader\": patch\n---\n\nfix: prefer reading script.dataset.src in script load error message\n" }, { "path": ".changeset/thin-ways-allow.md", "content": "---\n\"@qiankunjs/loader\": patch\n---\n\nfix(loader): we should invoke our script load listener before its own\n" }, { "path": ".changeset/three-hornets-hammer.md", "content": "---\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n---\n\nfix: should invoke getContainer method to get container every time to avoid reference misordering\n" }, { "path": ".changeset/tough-beers-grow.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n---\n\nfix: transformer should be generated in every load\n" }, { "path": ".changeset/tough-phones-chew.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\n🐛 compatible with webpack chunk cache logic\n" }, { "path": ".changeset/twelve-donkeys-help.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfix: should patch the container head/body element immediately rather than patch its functions with proxy\n" }, { "path": ".changeset/warm-chefs-chew.md", "content": "---\n\"qiankun\": patch\n---\n\n✨ set data-name on micro app container\n" }, { "path": ".changeset/wicked-icons-type.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: extract NodeTransformer type to shared package\n" }, { "path": ".changeset/wise-eagles-tease.md", "content": "---\n\"@qiankunjs/sandbox\": patch\n---\n\nfix(sandbox): compatible with dynamically appending scripts to detached containers\n" }, { "path": ".changeset/wise-ravens-prove.md", "content": "---\n\"@qiankunjs/loader\": patch\n\"qiankun\": patch\n\"@qiankunjs/sandbox\": patch\n\"@qiankunjs/shared\": patch\n---\n\nfeat: support huge inline-script who might be split into multiple chunks during transfer\n" }, { "path": ".dumirc.ts", "content": "import { defineConfig } from 'dumi';\n\nexport default defineConfig({\n publicPath: process.env.NOW_DEPLOY ? '/' : '/qiankun/',\n base: process.env.NOW_DEPLOY ? '/' : '/qiankun',\n resolve: {\n docDirs: ['docs'],\n codeBlockMode: 'passive',\n },\n locales: [\n { id: 'en-US', name: 'English' },\n { id: 'zh-CN', name: '中文' },\n ],\n themeConfig: {\n name: 'qiankun',\n logo: 'https://gw.alipayobjects.com/zos/bmw-prod/8a74c1d3-16f3-4719-be63-15e467a68a24/km0cv8vn_w500_h500.png',\n nav: {\n mode: 'append',\n value: {\n 'zh-CN': [\n {\n title: '版本公告',\n children: [\n { title: '发布日志', link: 'https://github.com/umijs/qiankun/releases' },\n { title: '升级指南', link: '/zh/cookbook#从-2x-版本升级到-3x-版本' },\n { title: '2.x 版本', link: 'https://v2.qiankun.umijs.org/zh/' },\n ],\n },\n ],\n 'en-US': [\n {\n title: 'Version Notice',\n children: [\n { title: 'Changelog', link: 'https://github.com/umijs/qiankun/releases' },\n { title: 'Upgrade Guide', link: '/cookbook#upgrade-from-2x-version-to-3x-version' },\n { title: '2.x Version', link: 'https://v2.qiankun.umijs.org/' },\n ],\n },\n ],\n },\n },\n socialLinks: {\n github: 'https://github.com/umijs/qiankun',\n },\n },\n metas: [\n {\n name: 'keywords',\n content:\n 'microfrontend, micro frontend, micro frontends, micro-frontend, micro-frontends, microservice, javascript',\n },\n ],\n analytics: {\n ga: 'UA-157295698-1',\n baidu: '0f738d9b0ac90574c09183ea85bcfa2e',\n },\n favicons: ['https://gw.alipayobjects.com/mdn/rms_655822/afts/img/A*4sIUQpcos_gAAAAAAAAAAAAAARQnAQ'],\n theme: {\n '@c-primary': '#6451AB',\n },\n});\n" }, { "path": ".editorconfig", "content": "# http://editorconfig.org\nroot = true\n\n[*]\nindent_style = space\nindent_size = 2\nend_of_line = lf\ncharset = utf-8\ntrim_trailing_whitespace = true\ninsert_final_newline = true\nmax_line_length = 120\n\n[*.md]\ntrim_trailing_whitespace = false\n" }, { "path": ".eslintignore", "content": "examples\ndist\nwritable-dom\ntemplate\n\n# TODO not linting test files temporary\n__tests__/\n" }, { "path": ".eslintrc.cjs", "content": "// eslint config for js\nconst jsConfig = {\n parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },\n extends: ['eslint:recommended', 'prettier'],\n rules: {\n 'no-else-return': ['error', { allowElseIf: false }],\n 'object-shorthand': ['error', 'properties'],\n 'no-shadow': 'off',\n },\n};\n\n// eslint config for cjs\nconst cjsConfig = {\n parserOptions: { sourceType: 'script' },\n env: { node: true },\n};\n\n// eslint config for ts\nconst tsConfig = {\n extends: ['plugin:@typescript-eslint/recommended', 'plugin:@typescript-eslint/recommended-requiring-type-checking'],\n parserOptions: {\n tsconfigRootDir: __dirname,\n project: ['./tsconfig.eslint.json', './packages/**/tsconfig.json'],\n },\n rules: {\n '@typescript-eslint/no-unnecessary-condition': 'error',\n '@typescript-eslint/no-explicit-any': ['error', { fixToUnknown: true }],\n '@typescript-eslint/consistent-type-imports': [\n 'error',\n { prefer: 'type-imports', fixStyle: 'inline-type-imports' },\n ],\n '@typescript-eslint/consistent-type-exports': ['error', { fixMixedExportsWithInlineTypeSpecifier: true }],\n '@typescript-eslint/require-await': 'off',\n '@typescript-eslint/array-type': ['error', { default: 'array-simple' }],\n '@typescript-eslint/no-shadow': ['error', { ignoreFunctionTypeParameterNameValueShadow: true }],\n '@typescript-eslint/no-misused-promises': [\n 'error',\n {\n checksVoidReturn: {\n returns: false,\n variables: false,\n },\n },\n ],\n '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],\n },\n};\n\nmodule.exports = {\n root: true,\n ...jsConfig,\n overrides: [\n {\n files: ['*.ts', '*.tsx'],\n ...tsConfig,\n },\n {\n files: ['*.cjs', 'packages/webpack-plugin/**/*.js'],\n ...cjsConfig,\n },\n ],\n};\n" }, { "path": ".fatherrc.cjs", "content": "module.exports = {\n platform: 'browser',\n esm: {},\n cjs: {},\n sourcemap: true,\n extraBabelPlugins: [\n [\n 'babel-plugin-import',\n {\n libraryName: 'lodash',\n libraryDirectory: '',\n camel2DashComponentName: false,\n },\n ],\n ],\n};\n" }, { "path": ".github/CODE_OF_CONDUCT.md", "content": "# Contributor Covenant Code of Conduct\n\n## Our Pledge\n\nWe as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.\n\nWe pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.\n\n## Our Standards\n\nExamples of behavior that contributes to a positive environment for our community include:\n\n- Demonstrating empathy and kindness toward other people\n- Being respectful of differing opinions, viewpoints, and experiences\n- Giving and gracefully accepting constructive feedback\n- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience\n- Focusing on what is best not just for us as individuals, but for the overall community\n\nExamples of unacceptable behavior include:\n\n- The use of sexualized language or imagery, and sexual attention or advances of any kind\n- Trolling, insulting or derogatory comments, and personal or political attacks\n- Public or private harassment\n- Publishing others' private information, such as a physical or email address, without their explicit permission\n- Other conduct which could reasonably be considered inappropriate in a professional setting\n\n## Enforcement Responsibilities\n\nCommunity leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.\n\nCommunity leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.\n\n## Scope\n\nThis Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.\n\n## Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [kuitos.lau@gmail.com](mailto:kuitos.lau@gmail.com) or by creating a confidential issue in our [GitHub repository](https://github.com/umijs/qiankun/issues). All complaints will be reviewed and investigated promptly and fairly.\n\nAll community leaders are obligated to respect the privacy and security of the reporter of any incident.\n\n## Enforcement Guidelines\n\nCommunity leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:\n\n### 1. Correction\n\n**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.\n\n**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.\n\n### 2. Warning\n\n**Community Impact**: A violation through a single incident or series of actions.\n\n**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.\n\n### 3. Temporary Ban\n\n**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.\n\n**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.\n\n### 4. Permanent Ban\n\n**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.\n\n**Consequence**: A permanent ban from any sort of public interaction within the community.\n\n## Attribution\n\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.\n\nCommunity Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).\n\n[homepage]: https://www.contributor-covenant.org\n\nFor answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.\n" }, { "path": ".github/CONTRIBUTING.md", "content": "# Contributing to qiankun\n\nThank you for your interest in contributing to qiankun! We welcome all types of contributions, including but not limited to:\n\n- 🐛 Bug reports\n- ✨ Feature suggestions\n- 📝 Documentation improvements\n- 🧪 Test cases\n- 💻 Code contributions\n\n## Getting Started\n\nBefore you begin contributing, please:\n\n1. Read our [Code of Conduct](CODE_OF_CONDUCT.md)\n2. Understand the [Developer Certificate of Origin (DCO)](https://developercertificate.org/) requirement - **all commits must be signed off**\n3. Check existing [Issues](https://github.com/umijs/qiankun/issues) and [Pull Requests](https://github.com/umijs/qiankun/pulls)\n4. Understand the project's technical architecture and code style\n\n## Development Environment Setup\n\n### Requirements\n\n- Node.js >= 16.0.0\n- pnpm@9.15.0 (we use pnpm as the package manager, exact version specified in package.json)\n\n### Local Development\n\n1. Fork this repository\n2. Clone to local:\n\n ```bash\n git clone https://github.com/YOUR_USERNAME/qiankun.git\n cd qiankun\n ```\n\n3. Install dependencies:\n\n ```bash\n pnpm install\n ```\n\n4. Run tests:\n\n ```bash\n pnpm test\n ```\n\n5. Build the project:\n ```bash\n pnpm run build\n ```\n\n### Development Scripts\n\n- `pnpm run build` - Build all packages using father\n- `pnpm test` - Run tests using vitest\n- `pnpm run eslint` - Code style check with TypeScript ESLint rules\n- `pnpm run prettier` - Format code with prettier\n- `pnpm run prettier:check` - Check code formatting\n- `pnpm run ci` - Complete CI pipeline (build + lint + format check)\n- `pnpm run clean` - Clean node_modules and build artifacts\n- `pnpm run start:example` - Start example applications (main + react15)\n- `pnpm run docs:dev` - Start documentation development server\n- `pnpm run docs:build` - Build documentation\n- `pnpm run prepare` - Setup husky git hooks and dumi\n\n## Code Contribution Workflow\n\n### 1. Create an Issue\n\nFor major features or breaking changes, please create an Issue first to discuss:\n\n- Clearly describe the problem or feature request\n- Provide relevant context information\n- For bugs, provide reproduction steps\n\n### 2. Create a Branch\n\nCreate a feature branch based on the `next` branch (default development branch):\n\n```bash\ngit checkout next\ngit pull origin next\ngit checkout -b feature/your-feature-name\n# or\ngit checkout -b fix/bug-description\n```\n\nNote: The project uses `next` as the main development branch (as configured in changeset).\n\n### 3. Code Development\n\n#### TypeScript Code Standards\n\n- **Strict Type Checking**:\n - Enable TypeScript strict mode (already configured in tsconfig.json)\n - Avoid using `any` type (ESLint rule enforces `fixToUnknown: true`)\n - Use `unknown` instead of `any` when type is uncertain\n - Enable all strict options: `strictNullChecks`, `strictFunctionTypes`, `noImplicitReturns`, etc.\n- **Type Import/Export**:\n - Use `import type` for type-only imports (enforced by ESLint)\n - Use consistent type exports with inline type specifiers\n- **Naming Conventions**:\n - Variables and functions use `camelCase`\n - Classes and interfaces use `PascalCase`\n - Constants use `UPPER_SNAKE_CASE`\n - File names use `kebab-case` or `PascalCase`\n- **Comment Standards**:\n - Use clear comments to explain complex logic\n - Use JSDoc format for public APIs\n - Provide usage examples for complex type definitions\n - Add type annotations where TypeScript inference is insufficient\n\n#### Code Style\n\n- Follow the project's ESLint configuration\n- Use 2-space indentation\n- No trailing whitespace\n- Keep one empty line at the end of files\n\n#### Architecture Principles\n\n- Follow SOLID principles\n- Maintain high cohesion and low coupling\n- Prefer composition over inheritance\n- Ensure code testability\n\n### 4. Write Tests\n\n- Write corresponding test cases for new features using **vitest**\n- Ensure existing tests are not broken\n- Maintain reasonable test coverage\n- Place test files in appropriate `__tests__` directories or alongside source files with `.test.ts` suffix\n- Use vitest's global test APIs (no need to import `describe`, `it`, `expect`)\n- Run tests with `pnpm test` or `pnpm -r run test` for all packages\n\n### 5. Commit Code\n\n#### Developer Certificate of Origin (DCO)\n\nAll commits **MUST** be signed off with the Developer Certificate of Origin (DCO). This is a legal requirement to ensure you have the right to contribute your code.\n\n**How to sign off commits:**\n\n1. **Manual sign-off for each commit:**\n\n ```bash\n git commit -s -m \"feat: add new feature\"\n ```\n\n2. **Configure automatic sign-off:**\n\n ```bash\n git config user.name \"Your Name\"\n git config user.email \"your.email@example.com\"\n git config commit.gpgsign true # Optional: GPG signing\n ```\n\n3. **Sign off existing commits retroactively:**\n\n ```bash\n # For the last commit\n git commit --amend --signoff\n\n # For multiple commits (rebase and sign off)\n git rebase --signoff HEAD~n # where n is the number of commits\n ```\n\n**What is DCO?**\n\nThe DCO is a statement that you have the right to contribute the code and that you understand the licensing implications. Please read the full [DCO text](https://developercertificate.org/) for complete details. When you sign off a commit, you're confirming:\n\n- The contribution was created by you, or you have permission to submit it\n- You understand and agree that the contribution will be public\n- You understand the contribution is licensed under the project's license\n\n**Commit sign-off format:**\n\nEach commit message must end with a \"Signed-off-by\" line:\n\n```\nfeat(core): implement new feature\n\nThis commit adds support for custom lifecycles.\n\nSigned-off-by: Your Name \n```\n\n**⚠️ Important:** Pull requests with unsigned commits will be rejected. Make sure all your commits are properly signed off before submitting a PR.\n\n#### Commit Message Format\n\nWe follow [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.\n\n**Format:**\n\n```\n[optional scope]: \n\n[optional body]\n\n[optional footer(s)]\n\nSigned-off-by: Your Name \n```\n\n**Commit Types:**\n\n| Type | Description | Example |\n| ---------- | ----------------------- | --------------------------------------------- |\n| `feat` | New feature | `feat(sandbox): add new isolation mode` |\n| `fix` | Bug fix | `fix(loader): resolve script loading issue` |\n| `perf` | Performance improvement | `perf(core): optimize app loading speed` |\n| `docs` | Documentation only | `docs: update API reference` |\n| `style` | Code formatting | `style: fix ESLint warnings` |\n| `refactor` | Code refactoring | `refactor(utils): simplify helper functions` |\n| `test` | Adding tests | `test(core): add unit tests for loadMicroApp` |\n| `chore` | Build/tooling changes | `chore: update dependencies` |\n| `ci` | CI configuration | `ci: add workflow for releases` |\n| `build` | Build system changes | `build: configure webpack` |\n| `revert` | Revert previous commit | `revert: feat(api): add user auth` |\n\n**Breaking Changes:**\n\nFor breaking changes, use one of these approaches:\n\n1. Add `!` after type: `feat!: redesign loadMicroApp API`\n2. Add `BREAKING CHANGE:` in footer:\n\n ```\n feat(api): add new authentication method\n\n BREAKING CHANGE: The old auth method is no longer supported.\n Migration guide: replace loadMicroApp() with registerMicroApps()\n ```\n\n**Scope Guidelines:**\n\n- `core`: Core qiankun functionality\n- `sandbox`: Sandbox isolation\n- `loader`: Resource loading\n- `utils`: Utility functions\n- `types`: TypeScript type definitions\n- `docs`: Documentation\n- `test`: Testing related\n- `ci`: CI/CD related\n- `build`: Build system related\n\n### 6. Create Pull Request\n\n1. Push your branch to your fork:\n\n ```bash\n git push origin feature/your-feature-name\n ```\n\n2. Create a Pull Request on GitHub\n\n3. PR title and description should be clear:\n - Title should briefly describe the changes\n - Description should detail:\n - Motivation and purpose of changes\n - Main changes made\n - Testing status\n - Any breaking changes\n - Related issue numbers\n\n4. Ensure all checks pass:\n - **DCO sign-off check**: All commits must be signed off\n - ESLint code style checks with TypeScript rules\n - TypeScript strict type checks (no `any` types, strict null checks)\n - All vitest tests pass\n - Test coverage meets requirements\n - Prettier formatting checks\n - Build passes with father bundler\n\n## Documentation Contributions\n\nDocumentation improvements are equally important:\n\n- Fix errors or outdated information in documentation\n- Improve clarity of existing documentation\n- Add examples and use cases\n- Translate documentation to other languages\n\n## Bug Reports\n\nWhen submitting bug reports, please include:\n\n- **Clear Title**: Briefly describe the issue\n- **Environment Information**:\n - Node.js version (>= 16.0.0)\n- pnpm version (should be 9.15.0)\n - qiankun version\n - Browser version\n - Operating system\n - Framework versions (React, Vue, Angular, etc.)\n - Build tool versions (webpack, vite, etc.)\n - Related dependency versions\n- **Reproduction Steps**: Detailed step-by-step instructions\n- **Expected Behavior**: Describe what should happen\n- **Actual Behavior**: Describe what actually happened\n- **Minimal Example**: Provide minimal code that reproduces the issue\n- **Relevant Logs**: Error messages, stack traces, etc.\n\n## Feature Requests\n\nWhen submitting feature requests, please:\n\n- Clearly describe the needed functionality\n- Explain why this feature is needed\n- Provide use cases and examples\n- Consider alternative solutions\n- Discuss impact on existing APIs\n\n## Release Process\n\nThis project uses [Changesets](https://github.com/changesets/changesets) for version management and publishing:\n\n### For Maintainers\n\n1. **Creating a changeset**: After merging PR, create a changeset:\n\n ```bash\n npx changeset\n ```\n\n2. **Release process**:\n\n ```bash\n # Alpha release (for testing)\n pnpm run prerelease:alpha # Enter pre-release mode and create changeset\n pnpm run release:alpha # Build and publish alpha version\n\n # Production release\n npx changeset version # Update package versions\n pnpm run build # Build all packages\n pnpm run ci:publish # Publish to npm\n ```\n\n### Build System\n\n- **Build Tool**: [father](https://github.com/umijs/father) - A library build tool\n- **Monorepo**: pnpm workspaces with packages in `packages/` directory\n- **Documentation**: [dumi](https://d.umijs.org/) for documentation site\n- **Testing**: [vitest](https://vitest.dev/) for unit testing\n- **Code Quality**: ESLint + Prettier + TypeScript strict mode\n\n## Getting Help\n\nIf you have any questions, you can get help through:\n\n- Create a [GitHub Issue](https://github.com/umijs/qiankun/issues)\n- Check existing [documentation](https://qiankun.umijs.org/)\n- Join our community discussions\n\n## Acknowledgments\n\nThanks to all developers who contribute to the qiankun project! Your contributions make this project better.\n\n---\n\nThank you again for your contribution! 🎉\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.md", "content": "---\nname: 'Bug report'\nabout: 'Report a bug to help us improve'\ntitle: ''\nlabels: ''\nassignees: ''\n---\n\n## What happens?\n\nA clear and concise description of what the bug is.\n\n## Mini Showcase Repository(REQUIRED)\n\n> Provide a mini GitHub repository which can reproduce the issue.\n\n\n\n## How To Reproduce\n\n**Steps to reproduce the behavior:** 1. 2.\n\n**Expected behavior** 1. 2.\n\n## Context\n\n- **qiankun Version**:\n- **Platform Version**:\n- **Browser Version**:\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report_cn.md", "content": "---\nname: '缺陷问题反馈'\nabout: '反馈问题以帮助我们改进'\ntitle: '[Bug]请遵循下文模板提交问题，否则您的问题会被关闭'\nlabels: ''\nassignees: ''\n---\n\n# 提问之前强烈建立您能先阅读一下[《如何正确的提出一个 Issue》](https://github.com/umijs/qiankun/issues/1115)\n\n\n\n## What happens?\n\n\n\n## 最小可复现仓库\n\n为节约大家的时间，无复现步骤的 ISSUE 会被关闭，提供之后再 REOPEN\n\n\n\n## 复现步骤，错误日志以及相关配置\n\n\n\n\n## 相关环境信息\n\n- **qiankun 版本**\n- **浏览器版本**：\n- **操作系统**：\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.md", "content": "---\nname: 'Feature request'\nabout: 'Suggest an idea for this project'\ntitle: '[Feature Request] say something'\nlabels: ''\nassignees: ''\n---\n\n## Background\n\nA clear and concise description of what the problem is. Ex. I'm always frustrated when [...]\n\n## Proposal\n\nDescribe the solution you'd like, better to provide some pseudo code.\n\n## Additional context\n\nAdd any other context or screenshots about the feature request here.\n" }, { "path": ".github/ISSUE_TEMPLATE/rfc_cn.md", "content": "---\nname: 'RFC Proposals'\nabout: 'Provide a solution for this project'\ntitle: '[RFC] say something'\nlabels: 'type: proposals'\nassignees: ''\n---\n\n## 背景\n\n> 描述你希望解决的问题的现状，附上相关的 issue 地址\n\n## 思路\n\n> 描述大概的解决思路，可以包含 API 设计和伪代码等\n\n## 跟进\n\n- [ ] some task\n- [ ] PR URL\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE.md", "content": "\n\n##### Checklist\n\n\n\n- [ ] `npm test` passes\n- [ ] tests are included\n- [ ] documentation is changed or added\n- [ ] commit message follows commit guidelines\n\n##### Description of change\n\n\n\n- any feature?\n- close https://github.com/umijs/qiankun/ISSUE_URL\n" }, { "path": ".github/workflows/announcement-notify.yml", "content": "name: Annoucement Notify\n\non:\n discussion:\n types: [created]\n\njobs:\n notify:\n runs-on: ubuntu-latest\n steps:\n - name: Send DingGroup1 Anouncement Notify\n uses: zcong1993/actions-ding@master\n if: github.event.discussion.category.name == 'Announcements'\n with:\n dingToken: ${{ secrets.DING_GROUP_1_TOKEN }}\n secret: ${{ secrets.DING_GROUP_1_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"Qiankun News\",\n \"text\": \"# 新闻播报📢 [${{github.event.discussion.title}}](${{github.event.discussion.html_url}}) \\n${{github.event.discussion.body}}\",\n }\n }\n\n - name: Send DingGroup2 Anouncement Notify\n uses: zcong1993/actions-ding@master\n if: github.event.discussion.category.name == 'Announcements'\n with:\n dingToken: ${{ secrets.DING_GROUP_2_TOKEN }}\n secret: ${{ secrets.DING_GROUP_2_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"Qiankun News\",\n \"text\": \"# 新闻播报📢 [${{github.event.discussion.title}}](${{github.event.discussion.html_url}}) \\n${{github.event.discussion.body}}\",\n }\n }\n\n - name: Send DingGroup3 Anouncement Notify\n uses: zcong1993/actions-ding@master\n if: github.event.discussion.category.name == 'Announcements'\n with:\n dingToken: ${{ secrets.DING_GROUP_3_TOKEN }}\n secret: ${{ secrets.DING_GROUP_3_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"Qiankun News\",\n \"text\": \"# 新闻播报📢 [${{github.event.discussion.title}}](${{github.event.discussion.html_url}}) \\n${{github.event.discussion.body}}\",\n }\n }\n\n - name: Send DingGroup4 Anouncement Notify\n uses: zcong1993/actions-ding@master\n if: github.event.discussion.category.name == 'Announcements'\n with:\n dingToken: ${{ secrets.DING_GROUP_4_TOKEN }}\n secret: ${{ secrets.DING_GROUP_4_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"Qiankun News\",\n \"text\": \"# 新闻播报📢 [${{github.event.discussion.title}}](${{github.event.discussion.html_url}}) \\n${{github.event.discussion.body}}\",\n }\n }\n\n - name: Send DingGroup5 Anouncement Notify\n uses: zcong1993/actions-ding@master\n if: github.event.discussion.category.name == 'Announcements'\n with:\n dingToken: ${{ secrets.DING_GROUP_5_TOKEN }}\n secret: ${{ secrets.DING_GROUP_5_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"Qiankun News\",\n \"text\": \"# 新闻播报📢 [${{github.event.discussion.title}}](${{github.event.discussion.html_url}}) \\n${{github.event.discussion.body}}\",\n }\n }\n\n - name: Send DingGroup6 Anouncement Notify\n uses: zcong1993/actions-ding@master\n if: github.event.discussion.category.name == 'Announcements'\n with:\n dingToken: ${{ secrets.DING_GROUP_6_TOKEN }}\n secret: ${{ secrets.DING_GROUP_6_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"Qiankun News\",\n \"text\": \"# 新闻播报📢 [${{github.event.discussion.title}}](${{github.event.discussion.html_url}}) \\n${{github.event.discussion.body}}\",\n }\n }\n\n - name: Send DingGroup7 Anouncement Notify\n uses: zcong1993/actions-ding@master\n if: github.event.discussion.category.name == 'Announcements'\n with:\n dingToken: ${{ secrets.DING_GROUP_7_TOKEN }}\n secret: ${{ secrets.DING_GROUP_7_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"Qiankun News\",\n \"text\": \"# 新闻播报📢 [${{github.event.discussion.title}}](${{github.event.discussion.html_url}}) \\n${{github.event.discussion.body}}\",\n }\n }\n" }, { "path": ".github/workflows/changeset-prerelease.yml", "content": "name: Changesets\n\non:\n push:\n branches:\n - next\n\npermissions:\n id-token: write\n contents: write\n pull-requests: write\n\njobs:\n changelog:\n timeout-minutes: 15\n runs-on: ubuntu-latest\n environment: changeset-release\n steps:\n - uses: actions/checkout@v4\n\n - name: Setup PNPM\n uses: pnpm/action-setup@v2\n\n - name: Setup Node\n uses: actions/setup-node@v4\n with:\n node-version: 24\n cache: \"pnpm\"\n registry-url: \"https://registry.npmjs.org\"\n\n - name: Install dependencies\n run: pnpm install\n\n - name: Build Packages\n run: pnpm run build\n\n - name: Create Release Pull Request or Publish\n id: changesets\n uses: changesets/action@v1\n with:\n commit: \"chore: update versions\"\n title: \"chore: update versions\"\n publish: pnpm ci:publish\n createGithubReleases: false\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n NPM_CONFIG_PROVENANCE: true\n\n - name: Create Unified GitHub Release\n if: steps.changesets.outputs.published == 'true'\n run: |\n VERSION=$(jq -r '.version' packages/qiankun/package.json)\n TAG=\"v${VERSION}\"\n\n node scripts/generate-release-notes.mjs '${{ steps.changesets.outputs.publishedPackages }}' > /tmp/release-notes.md\n\n gh release create \"${TAG}\" \\\n --title \"${TAG}\" \\\n --notes-file /tmp/release-notes.md \\\n --prerelease\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n pull_request:\n push:\n branches:\n - master\n - next\n - 1.x\n\njobs:\n build-check-and-lint:\n runs-on: ubuntu-latest\n\n strategy:\n matrix:\n node-version: [lts/*, latest]\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v2\n\n - name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v4\n with:\n node-version: ${{ matrix.node-version }}\n cache: \"pnpm\"\n\n - run: corepack enable # https://nodejs.org/api/corepack.html\n\n - run: pnpm install\n\n - name: TS Build Check\n run: pnpm run build\n\n - name: Run eslint\n run: pnpm run eslint\n\n - name: Run prettier\n run: pnpm run prettier:check\n\n - name: Doc Build check\n run: pnpm run docs:build\n\n unit-test:\n runs-on: ubuntu-latest\n\n strategy:\n matrix:\n node-version: [lts/*, latest]\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v2\n\n - name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v4\n with:\n node-version: ${{ matrix.node-version }}\n cache: \"pnpm\"\n\n - run: corepack enable # https://nodejs.org/api/corepack.html\n\n - run: pnpm install\n\n - name: Run unit test\n run: pnpm run test\n" }, { "path": ".github/workflows/emoji-helper.yml", "content": "name: Emoji Helper\n\non:\n release:\n types: [published]\n\njobs:\n emoji:\n runs-on: ubuntu-latest\n steps:\n - uses: actions-cool/emoji-helper@v1.0.0\n with:\n type: \"release\"\n emoji: \"+1, laugh, heart, hooray, rocket, eyes\"\n" }, { "path": ".github/workflows/github-pages.yml", "content": "name: Qiankun Github Pages Deploy\non:\n push:\n branches:\n - master\njobs:\n deploy-gh-pages:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-node@v4\n with:\n node-version: \"lts/*\"\n check-latest: true\n registry-url: \"https://registry.npmjs.org\"\n cache: \"pnpm\"\n - name: Install dependencies\n run: |\n corepack enable\n pnpm install --frozen-lockfile\n - name: Build docs\n run: pnpm run docs:build\n\n - name: Deploy\n uses: peaceiris/actions-gh-pages@v3\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n publish_dir: ./dist\n" }, { "path": ".github/workflows/issue-close-inactive.yml", "content": "name: Issue Close Inactive\n\non:\n schedule:\n - cron: \"0 0 * * *\"\n\njobs:\n close-issues:\n runs-on: ubuntu-latest\n steps:\n - name: close inactive issue without reprodction\n uses: actions-cool/issues-helper@v2.2.1\n with:\n actions: \"close-issues\"\n labels: \"Need Reproduction\"\n inactive-day: 30\n body: |\n Since the issue was labeled with `Need Reproduction`, but no response in 30 days. This issue will be close. If you have any questions, you can comment and reply.\n 由于该 issue 被标记为需要可复现步骤，却 30 天未收到回应。现关闭 issue，若有任何问题，可评论回复。\n\n - name: close inactive issue not use template\n uses: actions-cool/issues-helper@v2.2.1\n with:\n actions: \"close-issues\"\n labels: \"pls use issue template\"\n inactive-day: 30\n body: |\n Since the issue was labeled with `pls use issue template`, but no response in 30 days. This issue will be close. If you have any questions, you can comment and reply.\n 由于该 issue 被标记为需要使用模板，却 30 天未收到回应。现关闭 issue，若有任何问题，可评论回复。\n\n - name: close inactive issue out of scope\n uses: actions-cool/issues-helper@v2.2.1\n with:\n actions: \"close-issues\"\n labels: \"out-of-scope\"\n inactive-day: 30\n body: |\n Since the issue was labeled with `out-of-scope`, but no response in 30 days. This issue will be close. If you have any questions, you can comment and reply.\n 由于该 issue 被标记为与本项目无关，却 30 天未收到回应。现关闭 issue，若有任何问题，可评论回复。\n\n - name: close inactive issue\n uses: actions-cool/issues-helper@v2.2.1\n with:\n actions: \"close-issues\"\n labels: \"inactive\"\n inactive-day: 7\n body: |\n Since the issue was labeled with `inactive`, but no response in 7 days. This issue will be close. If you have any questions, you can comment and reply.\n 由于该 issue 被标记为不活跃，且 7 天未收到回应。现关闭 issue，若有任何问题，可评论回复。\n" }, { "path": ".github/workflows/issue-reply.yml", "content": "name: Issue Reply\n\non:\n issues:\n types: [labeled]\n\njobs:\n reply-helper:\n runs-on: ubuntu-latest\n steps:\n - name: help wanted\n if: github.event.label.name == 'pr welcome' || github.event.label.name == 'help wanted'\n uses: actions-cool/issues-helper@v2.0.0\n with:\n actions: \"create-comment\"\n issue-number: ${{ github.event.issue.number }}\n body: |\n Hello @${{ github.event.issue.user.login }}. We totally like your proposal/feedback, welcome to send us a Pull Request for it. Please be sure to fill in the default template in the Pull Request, provide changelog/documentation/test cases if needed and make sure CI passed, we will review it soon. We appreciate your effort in advance and looking forward to your contribution!\n\n 你好 @${{ github.event.issue.user.login }}，我们完全同意你的提议/反馈，欢迎直接在此仓库创建一个 Pull Request 来解决这个问题。请务必填写 Pull Request 内的预设模板，提供改动所需相应的 changelog、测试用例、文档等，并确保 CI 通过，我们会尽快进行 Review，提前感谢和期待您的贡献。\n\n - name: pls use issue template\n if: github.event.label.name == 'pls use issue template'\n uses: actions-cool/issues-helper@v2.0.0\n with:\n actions: \"create-comment, close-issue\"\n issue-number: ${{ github.event.issue.number }}\n body: |\n Hello @${{ github.event.issue.user.login }}. To save both time, please use the issue template to report. This issue will be closed.\n\n 你好 @${{ github.event.issue.user.login }}，为节约大家的时间，请使用 issue 模板反馈问题。该 issue 将要被关闭。\n\n - name: Need Reproduction\n if: github.event.label.name == 'Need Reproduction'\n uses: actions-cool/issues-helper@v2.0.0\n with:\n actions: \"create-comment\"\n issue-number: ${{ github.event.issue.number }}\n body: |\n Hello @${{ github.event.issue.user.login }}. In order to facilitate location and troubleshooting, we need you to provide a realistic example. Please forking these link [codesandbox](https://codesandbox.io/) or clone [qiankun examples](https://github.com/umijs/qiankun/tree/master/examples) to your GitHub repository.\n\n 你好 @${{ github.event.issue.user.login }}, 为了方便定位和排查问题，我们需要你提供一个重现实例，请提供一个尽可能精简的链接 [codesandbox](https://codesandbox.io/) 或直接 clone [qiankun examples](https://github.com/umijs/qiankun/tree/master/examples)，并上传到你的 GitHub 仓库。\n\n ![](https://gw.alipayobjects.com/zos/antfincdn/y9kwg7DVCd/reproduce.gif)\n" }, { "path": ".github/workflows/publish-1.x.yml", "content": "name: Publish 1.x Version\n\non:\n push:\n tags:\n - v1.*\n\njobs:\n publish:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v4\n\n - uses: actions/setup-node@v4\n with:\n node-version: \"lts/*\"\n check-latest: true\n registry-url: \"https://registry.npmjs.org\"\n cache: \"pnpm\"\n\n - run: corepack enable\n - run: pnpm install --frozen-lockfile\n - run: pnpm publish --tag qiankun1\n env:\n NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}\n" }, { "path": ".github/workflows/publish-latest.yml", "content": "name: Publish Latest Version\n\non:\n push:\n tags:\n - v2.*\n\njobs:\n publish:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v4\n\n - uses: actions/setup-node@v4\n with:\n node-version: \"lts/*\"\n check-latest: true\n registry-url: \"https://registry.npmjs.org\"\n cache: \"pnpm\"\n\n - run: corepack enable\n - run: pnpm install --frozen-lockfile\n - run: pnpm publish --tag latest\n env:\n NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}\n" }, { "path": ".github/workflows/release-notify.yml", "content": "name: Release Notify\n\non:\n release:\n types: [published]\n\njobs:\n notify:\n runs-on: ubuntu-latest\n steps:\n - name: Send DingGroup1 Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_1_TOKEN }}\n secret: ${{ secrets.DING_GROUP_1_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n\n - name: Send DingGroup2 Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_2_TOKEN }}\n secret: ${{ secrets.DING_GROUP_2_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n\n - name: Send DingGroup3 Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_3_TOKEN }}\n secret: ${{ secrets.DING_GROUP_3_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n\n - name: Send DingGroup4 Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_4_TOKEN }}\n secret: ${{ secrets.DING_GROUP_4_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n\n - name: Send DingGroup5 Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_5_TOKEN }}\n secret: ${{ secrets.DING_GROUP_5_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n\n - name: Send DingGroup6 Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_6_TOKEN }}\n secret: ${{ secrets.DING_GROUP_6_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n\n - name: Send DingGroup7 Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_7_TOKEN }}\n secret: ${{ secrets.DING_GROUP_7_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n\n - name: Send DingGroupInc Notify\n uses: zcong1993/actions-ding@master\n with:\n dingToken: ${{ secrets.DING_GROUP_INC_TOKEN }}\n secret: ${{ secrets.DING_GROUP_INC_SIGN }}\n body: |\n {\n \"msgtype\": \"markdown\",\n \"markdown\": {\n \"title\": \"qiankun ${{github.event.release.tag_name}} 发布公告\",\n \"text\": \"# qiankun [${{github.event.release.tag_name}}](${{github.event.release.html_url}}) 发布公告\\n${{github.event.release.body}}\",\n }\n }\n" }, { "path": ".gitignore", "content": "pids\nlogs\nnode_modules\nnpm-debug.log\ncoverage/\nrun\ndist\n.DS_Store\n.nyc_output\nconfig.local.js\n.umi\n.umi-production\n.idea/\n.vscode/\n.cache\nyarn.lock\nes\nlib\npackage-lock.json\n.eslintcache\n.history\n.worktrees\n.now\n.pnpm-store\n*.log\npackages/qiankun/src/version.ts\npackages/sandbox/src/core/sandbox/globals.ts\n.dumi/tmp\n.dumi/tmp-test\n.dumi/tmp-production\n" }, { "path": ".husky/commit-msg", "content": "#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nnpx --no-install commitlint --edit $1 " }, { "path": ".husky/pre-commit", "content": "#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\nnpx lint-staged\n" }, { "path": ".husky/pre-push", "content": "#!/usr/bin/env sh\n. \"$(dirname -- \"$0\")/_/husky.sh\"\n\n#pnpm run test\n" }, { "path": ".prettierignore", "content": "/test/fixtures\n**/*.gif\n/dist\n/docs\n/es\n/lib\n/coverage\n.cache\nexamples\n.umi\n.dumi\n.umi-production\n\n.changeset/*\npnpm-lock.yaml\npackages/sandbox/src/core/globals.ts\npackages/create-qiankun/template\n\n# changeset 会修改这个文件，导致 prettier:check 失败\npackages/**/*/package.json\n" }, { "path": ".prettierrc", "content": "{\n \"singleQuote\": true,\n \"trailingComma\": \"all\",\n \"proseWrap\": \"never\",\n \"overrides\": [\n {\n \"files\": [\"*.json\", \".prettierrc\"],\n \"options\": { \"parser\": \"json\" }\n },\n {\n \"files\": [\"*.{yaml,yml}\"],\n \"options\": { \"singleQuote\": false }\n }\n ]\n}\n" }, { "path": "AGENTS.md", "content": "# QIANKUN PROJECT KNOWLEDGE BASE\n\n**Generated:** 2026-01-10 **Commit:** 058166b6 **Branch:** next\n\n## OVERVIEW\n\nQiankun is a micro-frontend framework built on single-spa, providing HTML entry, JS sandbox, and style isolation. Monorepo managed by pnpm with `father` build tool.\n\n## STRUCTURE\n\n```\nqiankun/\n├── packages/\n│ ├── qiankun/ # Main facade - re-exports from loader/sandbox/shared\n│ ├── sandbox/ # JS isolation via Proxy membrane + Compartment (SEE packages/sandbox/AGENTS.md)\n│ ├── loader/ # Streaming HTML entry loader (SEE packages/loader/AGENTS.md)\n│ ├── shared/ # fetch-utils, asset transpilers, module-resolver (SEE packages/shared/AGENTS.md)\n│ ├── ui-bindings/ # React/Vue components\n│ ├── bundler-plugin/ # Entry point configuration plugin\n│ └── create-qiankun/ # CLI scaffolding tool\n├── examples/ # Integration examples (NOT in workspace currently)\n└── docs/ # VitePress documentation\n```\n\n## WHERE TO LOOK\n\n| Task | Location | Notes |\n| --- | --- | --- |\n| Core APIs (registerMicroApps, loadMicroApp) | `packages/qiankun/src/apis/` | Thin wrappers around loader/sandbox |\n| App loading lifecycle | `packages/qiankun/src/core/loadApp.ts` | Orchestrates sandbox+loader+hooks |\n| JS sandbox implementation | `packages/sandbox/src/core/` | Membrane, Compartment, StandardSandbox |\n| HTML streaming loader | `packages/loader/src/index.ts` | Uses writable-dom for streaming |\n| Script/link transpilation | `packages/shared/src/assets-transpilers/` | Blob URL sandboxing |\n| Fetch enhancements | `packages/shared/src/fetch-utils/` | Cache, retry, error handling |\n| Dependency sharing | `packages/shared/src/module-resolver/` | Semver-based matching |\n| React/Vue bindings | `packages/ui-bindings/{react,vue}/` | `` component |\n\n## CODE MAP\n\n### Package Dependencies (internal)\n\n```\nqiankun (facade)\n├── @qiankunjs/loader\n│ ├── @qiankunjs/sandbox\n│ └── @qiankunjs/shared\n├── @qiankunjs/sandbox\n│ └── @qiankunjs/shared\n└── @qiankunjs/shared (base utilities)\n```\n\n### Key Entry Points\n\n| Package | Entry | Primary Exports |\n| ------------------ | -------------- | --------------------------------------------------- |\n| qiankun | `src/index.ts` | `registerMicroApps`, `start`, `loadMicroApp` |\n| @qiankunjs/sandbox | `src/index.ts` | `createSandboxContainer`, `StandardSandbox` |\n| @qiankunjs/loader | `src/index.ts` | `loadEntry` |\n| @qiankunjs/shared | `src/index.ts` | `transpileScript`, `makeFetchCacheable`, `Deferred` |\n\n## CONVENTIONS\n\n### TypeScript (STRICT - enforced by eslint)\n\n- `@typescript-eslint/no-explicit-any`: ERROR - use `unknown` instead\n- `@typescript-eslint/consistent-type-imports`: inline-type-imports required\n- `@typescript-eslint/no-unnecessary-condition`: ERROR\n- Path aliases: `@qiankunjs/*` → `packages/*/src`\n\n### Code Style\n\n- No `as any`, `@ts-ignore`, `@ts-expect-error`\n- Unused vars: prefix with `_` (e.g., `_unused`)\n- Type exports: use `export type { X }` inline syntax\n\n### Build\n\n- Tool: `father` (UmiJS ecosystem)\n- Output: dual ESM + CJS in `dist/`\n- No `exports` field in package.json (uses `main`/`module`/`types`)\n\n## ANTI-PATTERNS (THIS PROJECT)\n\n- **NEVER** add more than 1 `entry` attribute script per HTML entry\n- **NEVER** use `!important` in CSS unless absolutely necessary (breaks isolation)\n- **ALWAYS** unmount micro-apps when finished (`loadMicroApp` returns unmount handle)\n- **AVOID** global variables in micro-apps - sandbox tracks `latestSetProp` for exports\n\n### Technical Debt (from codebase comments)\n\n- `FIXME` in `loadApp.ts`: async execution order coordination\n- `FIXME` in sandbox: System.js scope escape via indirect eval\n- `TODO`: Snapshot sandbox and GC not yet implemented\n\n## COMMANDS\n\n```bash\npnpm install # Install all workspace deps\npnpm run build # Build all packages (father build)\npnpm run test # Run vitest across workspace\npnpm run eslint # Lint packages/\npnpm run ci # Full CI: build + eslint + prettier:check\n\n# Development\npnpm run start:example # Build + run example apps\npnpm run docs:dev # VitePress dev server\n\n# Release (changesets)\npnpm run prerelease:alpha # Enter alpha, version bump\npnpm run release:alpha # Build, publish, exit alpha\n```\n\n## NOTES\n\n- **v3.0 Active Development**: Check roadmap at github.com/umijs/qiankun/discussions/1378\n- **Streaming Architecture**: v3 uses `writable-dom` for incremental HTML parsing\n- **Head Virtualization**: `` → `` for isolation\n- **Blob URL Execution**: Scripts wrapped and executed via `URL.createObjectURL`\n- **Test Environment**: Vitest + happy-dom; edge-runtime for fetch tests\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2019 Kuitos\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "

\n \n \"qiankun\n \n

\n\n

\n \"npm\n \"coverage\"\n \"npm\n \"build\n \"dumi\"\n

\n\n# qiankun（乾坤）\n\n> [!WARNING] 🚧 qiankun 3.0 is currently under active development. Check out the [Roadmap](https://github.com/umijs/qiankun/discussions/1378) for more details.\n\n> In Chinese, `qian(乾)` means heaven and `kun(坤)` earth. `qiankun` is the universe.\n\nQiankun enables you and your teams to build next-generation and enterprise-ready web applications leveraging [Micro Frontends](https://micro-frontends.org/). It is inspired by and based on [single-spa](https://github.com/single-spa/single-spa).\n\n## 🤔 Motivation\n\nA quick recap about the concept of `Micro Frontends`:\n\n> Techniques, strategies and recipes for building a **modern web app** with **multiple teams** using **different JavaScript frameworks**. — [Micro Frontends](https://micro-frontends.org/)\n\nQiankun was birthed internally in our group during the time web app development by distributed teams had turned to complete chaos. We faced every problem micro frontend was conceived to solve, so naturally, it became part of our solution.\n\nThe path was never easy, we stepped on every challenge there could possibly be. Just to name a few:\n\n- In what form do micro-apps publish static resources?\n- How does the framework integrate individual micro-apps?\n- How to ensure that sub-applications are isolated from one another (development independence and deployment independence) and runtime sandboxed?\n- Performance issues? What about public dependencies?\n- The list goes on long ...\n\nAfter solving these common problems of micro frontends and lots of polishing and testing, we extracted the minimal viable framework of our solution, and named it `qiankun`, as it can contain and serve anything. Not long after, it became the cornerstone of hundreds of our web applications in production, and we decided to open-source it to save you the suffering.\n\n**TLDR: Qiankun is probably the most complete micro-frontend solution you ever met🧐.**\n\n## :sparkles: Features\n\nQiankun inherits many benefits from [single-spa](https://github.com/single-spa/single-spa):\n\n- 📦 **Micro-apps Independent Deployment**\n- 🛴 **Lazy Load**\n- 📱 **Technology Agnostic**\n\nAnd on top of these, it offers:\n\n- 💃 **Elegant API**\n- 💪 **HTML Entry Access Mode**\n- 🛡 **Style Isolation**\n- 🧳 **JS Sandbox**\n- ⚡ **Prefetch Assets**\n- 🔌 **[Umi Plugin](https://github.com/umijs/plugins/tree/master/packages/plugin-qiankun) Integration**\n\n## Packages\n\n| Package | Version (click for changelogs) |\n| --- | :-- |\n| [qiankun](packages/qiankun) | [![qiankun version](https://img.shields.io/npm/v/qiankun/next.svg?style=flat-square)](packages/qiankun/CHANGELOG.md) |\n| [@qiankunjs/loader](packages/loader) | [![loader version](https://img.shields.io/npm/v/@qiankunjs/loader/rc.svg?style=flat-square)](packages/loader/CHANGELOG.md) |\n| [@qiankunjs/sandbox](packages/sandbox) | [![sandbox version](https://img.shields.io/npm/v/@qiankunjs/sandbox/rc.svg?style=flat-square)](packages/sandbox/CHANGELOG.md) |\n| [@qiankunjs/shared](packages/shared) | [![shared version](https://img.shields.io/npm/v/@qiankunjs/shared/rc.svg?style=flat-square)](packages/shared/CHANGELOG.md) |\n| [@qiankunjs/react](packages/ui-bindings/react) | [![react version](https://img.shields.io/npm/v/@qiankunjs/react/rc.svg?style=flat-square)](packages/ui-bindings/react/CHANGELOG.md) |\n| [@qiankunjs/vue](packages/ui-bindings/vue) | [![vue version](https://img.shields.io/npm/v/@qiankunjs/vue/rc.svg?style=flat-square)](packages/ui-bindings/vue/CHANGELOG.md) |\n| [@qiankunjs/ui-shared](packages/ui-bindings/shared) | [![ui-shared version](https://img.shields.io/npm/v/@qiankunjs/ui-shared/rc.svg?style=flat-square)](packages/ui-bindings/shared/CHANGELOG.md) |\n| [@qiankunjs/bundler-plugin](packages/bundler-plugin) | [![bundler-plugin version](https://img.shields.io/npm/v/@qiankunjs/bundler-plugin/rc.svg?style=flat-square)](packages/bundler-plugin/CHANGELOG.md) |\n| [create-qiankun](packages/create-qiankun) | [![create-qiankun version](https://img.shields.io/npm/v/create-qiankun/rc.svg?style=flat-square)](packages/create-qiankun/CHANGELOG.md) |\n\n## 📦 Installation\n\n```shell\n$ yarn add qiankun # or npm i qiankun -S\n```\n\n## 📖 Documentation\n\nYou can find the Qiankun documentation [on the website](https://qiankun.umijs.org/)\n\nCheck out the [Getting Started](https://qiankun.umijs.org/guide/getting-started) page for a quick overview.\n\nThe documentation is divided into several sections:\n\n- [Tutorial](https://qiankun.umijs.org/cookbook)\n- [API Reference](https://qiankun.umijs.org/api)\n- [FAQ](https://qiankun.umijs.org/faq)\n- [Community](https://qiankun.umijs.org/#-community)\n\n## 💿 Examples\n\nInside the `examples` folder, there is a sample Shell app and multiple mounted Micro FE apps. To get it running, first clone `qiankun`:\n\n```shell\n$ git clone https://github.com/umijs/qiankun.git\n$ cd qiankun\n```\n\nNow install and run the example:\n\n```shell\n$ pnpm install\n$ pnpm run examples:install\n$ pnpm run examples:start\n```\n\nVisit `http://localhost:7099`.\n\n![](./examples/example.gif)\n\n## 🎯 Roadmap\n\nSee [Qiankun 3.0 Roadmap](https://github.com/umijs/qiankun/discussions/1378)\n\n## 🤝 Contributing\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/umijs/qiankun)\n\nSee [contributing guide](./CONTRIBUTING.md).\n\n## 👥 Contributors\n\nThanks to all the contributors!\n\n\n \"contributors\"\n\n\n## 🎁 Acknowledgements\n\n- [single-spa](https://github.com/single-spa/single-spa) What an awesome meta-framework for micro-frontends!\n- [writable-dom](https://github.com/marko-js/writable-dom/) Utility to stream HTML content into a live document.\n\n## 📄 License\n\nQiankun is [MIT licensed](./LICENSE).\n" }, { "path": "commitlint.config.js", "content": "module.exports = {\n extends: ['@commitlint/config-conventional'],\n rules: {\n 'type-enum': [\n 2,\n 'always',\n ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'],\n ],\n 'subject-case': [0, 'never'],\n },\n};\n" }, { "path": "docs/.vitepress/config.mjs", "content": "import { defineConfig } from 'vitepress'\n\nexport default defineConfig({\n title: 'qiankun',\n description: 'Probably the most complete micro-frontends solution you ever met🧐',\n \n // Default to English\n lang: 'en-US',\n \n head: [\n ['link', { rel: 'icon', href: '/logo.png' }],\n ['meta', { name: 'theme-color', content: '#646cff' }],\n ['meta', { property: 'og:title', content: 'qiankun' }],\n ['meta', { property: 'og:description', content: 'Probably the most complete micro-frontends solution you ever met🧐' }],\n ['meta', { property: 'og:image', content: '/logo.png' }]\n ],\n\n locales: {\n root: {\n label: 'English',\n lang: 'en',\n title: 'qiankun',\n description: 'Probably the most complete micro-frontends solution you ever met🧐',\n themeConfig: {\n nav: [\n { text: 'Guide', link: '/guide/' },\n { text: 'API', link: '/api/' },\n { text: 'Ecosystem', link: '/ecosystem/' },\n { text: 'Cookbook', link: '/cookbook/' },\n { text: 'FAQ', link: '/faq/' },\n {\n text: 'Links',\n items: [\n { text: 'GitHub', link: 'https://github.com/umijs/qiankun' },\n { text: 'Changelog', link: 'https://github.com/umijs/qiankun/releases' },\n { text: 'Community', link: 'https://github.com/umijs/qiankun/discussions' },\n ]\n }\n ],\n sidebar: {\n '/guide/': [\n {\n text: 'Introduction',\n items: [\n { text: 'What is qiankun?', link: '/guide/' },\n { text: 'Quick Start', link: '/guide/quick-start' },\n { text: 'Tutorial', link: '/guide/tutorial' },\n ]\n }\n ],\n '/api/': [\n {\n text: 'Core APIs',\n items: [\n { text: 'Overview', link: '/api/' },\n { text: 'registerMicroApps', link: '/api/register-micro-apps' },\n { text: 'loadMicroApp', link: '/api/load-micro-app' },\n { text: 'start', link: '/api/start' },\n { text: 'isRuntimeCompatible', link: '/api/is-runtime-compatible' },\n ]\n },\n {\n text: 'Reference',\n items: [\n { text: 'Lifecycles', link: '/api/lifecycles' },\n { text: 'Configuration', link: '/api/configuration' },\n { text: 'Types', link: '/api/types' },\n ]\n }\n ],\n '/ecosystem/': [\n {\n text: 'UI Bindings',\n items: [\n { text: 'Overview', link: '/ecosystem/' },\n { text: 'React', link: '/ecosystem/react' },\n { text: 'Vue', link: '/ecosystem/vue' },\n ]\n },\n {\n text: 'Tools',\n items: [\n { text: 'Webpack Plugin', link: '/ecosystem/webpack-plugin' },\n { text: 'Create Qiankun', link: '/ecosystem/create-qiankun' },\n ]\n }\n ],\n '/cookbook/': [\n {\n text: 'Best Practices',\n items: [\n { text: 'Overview', link: '/cookbook/' },\n { text: 'Style Isolation', link: '/cookbook/style-isolation' },\n { text: 'Performance', link: '/cookbook/performance' },\n { text: 'Error Handling', link: '/cookbook/error-handling' },\n ]\n }\n ]\n }\n }\n },\n 'zh-CN': {\n label: '中文',\n lang: 'zh-CN',\n title: 'qiankun',\n description: '可能是你见过最完善的微前端解决方案🧐',\n themeConfig: {\n nav: [\n { text: '指南', link: '/zh-CN/guide/' },\n { text: 'API', link: '/zh-CN/api/' },\n { text: '生态系统', link: '/zh-CN/ecosystem/' },\n { text: '最佳实践', link: '/zh-CN/cookbook/' },\n { text: '常见问题', link: '/zh-CN/faq/' },\n {\n text: '相关链接',\n items: [\n { text: 'GitHub', link: 'https://github.com/umijs/qiankun' },\n { text: '更新日志', link: 'https://github.com/umijs/qiankun/releases' },\n { text: '社区讨论', link: 'https://github.com/umijs/qiankun/discussions' },\n ]\n }\n ],\n sidebar: {\n '/zh-CN/guide/': [\n {\n text: '介绍',\n items: [\n { text: '什么是 qiankun?', link: '/zh-CN/guide/' },\n { text: '快速开始', link: '/zh-CN/guide/quick-start' },\n { text: '详细教程', link: '/zh-CN/guide/tutorial' },\n ]\n }\n ],\n '/zh-CN/api/': [\n {\n text: '核心 API',\n items: [\n { text: '概览', link: '/zh-CN/api/' },\n { text: 'registerMicroApps', link: '/zh-CN/api/register-micro-apps' },\n { text: 'loadMicroApp', link: '/zh-CN/api/load-micro-app' },\n { text: 'start', link: '/zh-CN/api/start' },\n { text: 'isRuntimeCompatible', link: '/zh-CN/api/is-runtime-compatible' },\n ]\n }\n ],\n '/zh-CN/ecosystem/': [\n {\n text: 'UI 绑定',\n items: [\n { text: '概览', link: '/zh-CN/ecosystem/' },\n { text: 'React', link: '/zh-CN/ecosystem/react' },\n { text: 'Vue', link: '/zh-CN/ecosystem/vue' },\n ]\n }\n ],\n '/zh-CN/cookbook/': [\n {\n text: '最佳实践',\n items: [\n { text: '概览', link: '/zh-CN/cookbook/' },\n { text: '常见问题', link: '/zh-CN/cookbook/error-handling' },\n ]\n }\n ],\n '/zh-CN/faq/': [\n {\n text: '常见问题',\n items: [\n { text: 'FAQ', link: '/zh-CN/faq/' },\n ]\n }\n ]\n }\n }\n }\n },\n\n themeConfig: {\n logo: '/logo.png',\n \n socialLinks: [\n { icon: 'github', link: 'https://github.com/umijs/qiankun' }\n ],\n\n search: {\n provider: 'local'\n },\n\n editLink: {\n pattern: 'https://github.com/umijs/qiankun/edit/next/docs/:path',\n text: 'Edit this page on GitHub'\n },\n\n lastUpdated: {\n text: 'Last updated',\n formatOptions: {\n dateStyle: 'short',\n timeStyle: 'medium'\n }\n },\n\n footer: {\n message: 'Released under the MIT License.',\n copyright: 'Copyright © 2019-present qiankun contributors'\n }\n },\n\n markdown: {\n lineNumbers: true,\n theme: {\n light: 'github-light',\n dark: 'github-dark'\n }\n },\n\n cleanUrls: true,\n \n sitemap: {\n hostname: 'https://qiankun.umijs.org'\n },\n\n ignoreDeadLinks: true\n})" }, { "path": "docs/.vitepress/theme/index.js", "content": "// .vitepress/theme/index.js\nimport DefaultTheme from 'vitepress/theme'\nimport { onMounted, nextTick } from 'vue'\n\nexport default {\n extends: DefaultTheme,\n enhanceApp({ app, router }) {\n // 路由变化时重新渲染 Mermaid\n if (typeof window !== 'undefined') {\n router.onAfterRouteChanged = () => {\n nextTick(() => {\n renderMermaidCharts()\n })\n }\n }\n },\n setup() {\n onMounted(() => {\n // 初始加载时渲染 Mermaid\n setTimeout(() => {\n renderMermaidCharts()\n }, 100)\n })\n }\n}\n\nfunction renderMermaidCharts() {\n if (typeof window === 'undefined' || !window.mermaid) {\n return\n }\n\n try {\n // 初始化 mermaid\n window.mermaid.initialize({ \n startOnLoad: false,\n theme: 'default'\n })\n\n // 查找所有 mermaid 代码块\n const mermaidElements = document.querySelectorAll('pre code.language-mermaid')\n \n mermaidElements.forEach((element, index) => {\n // 如果已经渲染过，跳过\n if (element.getAttribute('data-processed') === 'true') {\n return\n }\n \n const code = element.textContent || element.innerText\n const uniqueId = `mermaid-${Date.now()}-${index}`\n \n // 创建容器\n const container = document.createElement('div')\n container.className = 'mermaid-container'\n container.id = uniqueId\n \n // 渲染图表\n window.mermaid.render(uniqueId + '-svg', code).then(({ svg }) => {\n container.innerHTML = svg\n \n // 替换原来的代码块\n const parent = element.closest('pre')\n if (parent && parent.parentNode) {\n parent.parentNode.replaceChild(container, parent)\n }\n }).catch(error => {\n console.warn('Mermaid 渲染错误:', error)\n })\n \n // 标记为已处理\n element.setAttribute('data-processed', 'true')\n })\n } catch (error) {\n console.warn('Mermaid 初始化错误:', error)\n }\n} " }, { "path": "docs/api/configuration.md", "content": "# Configuration\n\nqiankun provides flexible configuration options to customize the behavior of micro-frontend applications. This document covers all available configuration options for different use cases.\n\n## 📋 Configuration Types\n\n### AppConfiguration\n\nConfiguration for individual micro applications used with `loadMicroApp`.\n\n```typescript\ntype AppConfiguration = {\n sandbox?: boolean;\n globalContext?: WindowProxy;\n fetch?: Function;\n streamTransformer?: Function;\n nodeTransformer?: Function;\n};\n```\n\n### StartOpts\n\nConfiguration for starting the qiankun framework used with `start()`.\n\n```typescript\ninterface StartOpts {\n prefetch?: boolean | 'all' | string[] | ((apps: RegistrableApp[]) => { criticalAppNames: string[]; minorAppsName: string[] });\n sandbox?: boolean | { strictStyleIsolation?: boolean; experimentalStyleIsolation?: boolean; };\n singular?: boolean;\n urlRerouteOnly?: boolean;\n // ... other single-spa options\n}\n```\n\n## ⚙️ App Configuration Options\n\n### sandbox\n\n**Type**: `boolean` \n**Default**: `true` \n**Description**: Enable sandbox isolation for the micro application.\n\n#### Basic Usage\n\n```typescript\n// Enable sandbox (default)\nloadMicroApp({\n name: 'my-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n sandbox: true\n});\n\n// Disable sandbox (not recommended)\nloadMicroApp({\n name: 'legacy-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n sandbox: false\n});\n```\n\n#### Why Use Sandbox?\n\n```typescript\n// With sandbox enabled, global variables are isolated\nloadMicroApp({\n name: 'app1',\n entry: '//localhost:8001',\n container: '#container1',\n}, {\n sandbox: true // app1 gets its own global scope\n});\n\nloadMicroApp({\n name: 'app2', \n entry: '//localhost:8002',\n container: '#container2',\n}, {\n sandbox: true // app2 gets its own isolated global scope\n});\n```\n\n### globalContext\n\n**Type**: `WindowProxy` \n**Default**: `window` \n**Description**: Custom global context for the micro application.\n\n```typescript\n// Create a custom global context\nconst customGlobal = new Proxy(window, {\n get(target, prop) {\n // Custom logic for property access\n if (prop === 'customAPI') {\n return { version: '1.0' };\n }\n return target[prop];\n }\n});\n\nloadMicroApp({\n name: 'custom-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n globalContext: customGlobal\n});\n```\n\n### fetch\n\n**Type**: `Function` \n**Default**: `window.fetch` \n**Description**: Custom fetch function for loading application resources.\n\n#### Custom Headers\n\n```typescript\nconst customFetch = async (url, options) => {\n return fetch(url, {\n ...options,\n headers: {\n ...options?.headers,\n 'Authorization': `Bearer ${getToken()}`,\n 'X-Custom-Header': 'custom-value'\n }\n });\n};\n\nloadMicroApp({\n name: 'authenticated-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n fetch: customFetch\n});\n```\n\n#### Request Transformation\n\n```typescript\nconst transformFetch = async (url, options) => {\n // Transform URLs\n const transformedUrl = url.replace('//localhost', '//production-domain');\n \n // Add custom logic\n console.log(`Fetching: ${transformedUrl}`);\n \n const response = await fetch(transformedUrl, options);\n \n // Transform response\n if (!response.ok) {\n throw new Error(`Failed to fetch ${transformedUrl}: ${response.status}`);\n }\n \n return response;\n};\n```\n\n#### Caching Strategy\n\n```typescript\nconst cache = new Map();\n\nconst cachingFetch = async (url, options) => {\n const cacheKey = `${url}${JSON.stringify(options)}`;\n \n if (cache.has(cacheKey)) {\n console.log(`Cache hit for ${url}`);\n return cache.get(cacheKey);\n }\n \n const response = await fetch(url, options);\n cache.set(cacheKey, response.clone());\n \n return response;\n};\n```\n\n### streamTransformer\n\n**Type**: `Function` \n**Description**: Transform streaming HTML content during loading.\n\n```typescript\nconst customStreamTransformer = (stream) => {\n return stream.pipeThrough(new TransformStream({\n transform(chunk, controller) {\n // Transform HTML chunks\n const transformedChunk = chunk\n .replace(/old-api/g, 'new-api')\n .replace(/deprecated-feature/g, 'updated-feature');\n \n controller.enqueue(transformedChunk);\n }\n }));\n};\n\nloadMicroApp({\n name: 'streaming-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n streamTransformer: customStreamTransformer\n});\n```\n\n### nodeTransformer\n\n**Type**: `Function` \n**Description**: Transform DOM nodes during application loading.\n\n```typescript\nconst customNodeTransformer = (node, options) => {\n // Transform script tags\n if (node.tagName === 'SCRIPT') {\n // Add custom attributes\n node.setAttribute('data-app', 'my-app');\n \n // Modify script source\n if (node.src) {\n node.src = node.src.replace('localhost', 'production-domain');\n }\n }\n \n // Transform style tags\n if (node.tagName === 'STYLE') {\n // Add CSS scope\n node.textContent = `.app-scope { ${node.textContent} }`;\n }\n \n return node;\n};\n\nloadMicroApp({\n name: 'transformed-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n nodeTransformer: customNodeTransformer\n});\n```\n\n## 🚀 Start Configuration Options\n\n### prefetch\n\n**Type**: `boolean | 'all' | string[] | Function` \n**Default**: `true` \n**Description**: Resource prefetching strategy for better performance.\n\n#### Boolean Values\n\n```typescript\n// Disable prefetch\nstart({ prefetch: false });\n\n// Enable default prefetch\nstart({ prefetch: true });\n```\n\n#### Prefetch All\n\n```typescript\n// Prefetch all registered micro apps\nstart({ prefetch: 'all' });\n```\n\n#### Selective Prefetch\n\n```typescript\n// Prefetch specific apps\nstart({ \n prefetch: ['dashboard', 'user-profile', 'analytics'] \n});\n```\n\n#### Dynamic Prefetch Strategy\n\n```typescript\nstart({\n prefetch: (apps) => {\n // Business logic to determine prefetch strategy\n const currentTime = new Date().getHours();\n const isBusinessHours = currentTime >= 9 && currentTime <= 17;\n \n if (isBusinessHours) {\n // Prefetch business-critical apps during business hours\n return {\n criticalAppNames: ['dashboard', 'crm', 'finance'],\n minorAppsName: ['reporting', 'settings']\n };\n } else {\n // Minimal prefetch during off-hours\n return {\n criticalAppNames: ['dashboard'],\n minorAppsName: []\n };\n }\n }\n});\n```\n\n#### User-based Prefetch\n\n```typescript\nstart({\n prefetch: (apps) => {\n const userRole = getCurrentUserRole();\n \n switch (userRole) {\n case 'admin':\n return {\n criticalAppNames: ['admin-panel', 'user-management', 'system-monitor'],\n minorAppsName: ['reports', 'settings']\n };\n case 'user':\n return {\n criticalAppNames: ['dashboard', 'profile'],\n minorAppsName: ['help', 'feedback']\n };\n default:\n return {\n criticalAppNames: ['dashboard'],\n minorAppsName: []\n };\n }\n }\n});\n```\n\n### sandbox\n\n**Type**: `boolean | SandboxConfig` \n**Default**: `true` \n**Description**: Global sandbox configuration for all micro applications.\n\n#### Basic Sandbox\n\n```typescript\n// Enable sandbox for all apps\nstart({ sandbox: true });\n\n// Disable sandbox for all apps (not recommended)\nstart({ sandbox: false });\n```\n\n#### Advanced Sandbox Configuration\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // Enable Shadow DOM style isolation\n experimentalStyleIsolation: true, // Enable scoped CSS style isolation\n }\n});\n```\n\n#### Style Isolation Options\n\n**strictStyleIsolation**: Uses Shadow DOM to completely isolate styles\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // Strongest isolation but may break some UI libraries\n }\n});\n```\n\n**experimentalStyleIsolation**: Uses scoped CSS to isolate styles\n```typescript\nstart({\n sandbox: {\n experimentalStyleIsolation: true, // Good balance of isolation and compatibility\n }\n});\n```\n\n#### Combined Style Isolation\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: false, // Disable Shadow DOM\n experimentalStyleIsolation: true, // Enable scoped CSS\n }\n});\n```\n\n### singular\n\n**Type**: `boolean` \n**Default**: `true` \n**Description**: Whether only one micro app can be mounted at a time.\n\n```typescript\n// Only one app at a time (default)\nstart({ singular: true });\n\n// Allow multiple apps simultaneously\nstart({ \n singular: false // Useful for dashboard-style applications\n});\n```\n\n#### Use Cases for Multiple Apps\n\n```typescript\n// Dashboard with multiple widgets\nstart({ \n singular: false,\n // Other configurations\n});\n\n// Register widget-style micro apps\nregisterMicroApps([\n { name: 'widget-weather', entry: '//localhost:8001', container: '#widget-1', activeRule: '/dashboard' },\n { name: 'widget-stocks', entry: '//localhost:8002', container: '#widget-2', activeRule: '/dashboard' },\n { name: 'widget-news', entry: '//localhost:8003', container: '#widget-3', activeRule: '/dashboard' },\n]);\n```\n\n### urlRerouteOnly\n\n**Type**: `boolean` \n**Default**: `true` \n**Description**: Whether to trigger routing only on URL changes.\n\n```typescript\n// Only route on URL changes (default)\nstart({ urlRerouteOnly: true });\n\n// Route on both URL and programmatic changes\nstart({ \n urlRerouteOnly: false // More responsive but potentially more performance overhead\n});\n```\n\n## 🔧 Environment-based Configuration\n\n### Development Configuration\n\n```typescript\nconst developmentConfig = {\n prefetch: false, // Faster rebuilds\n sandbox: {\n strictStyleIsolation: false, // Easier debugging\n experimentalStyleIsolation: true,\n },\n singular: false, // More flexible development\n urlRerouteOnly: false, // More responsive navigation\n};\n\nif (process.env.NODE_ENV === 'development') {\n start(developmentConfig);\n}\n```\n\n### Production Configuration\n\n```typescript\nconst productionConfig = {\n prefetch: 'all', // Better user experience\n sandbox: {\n strictStyleIsolation: true, // Better isolation\n experimentalStyleIsolation: false,\n },\n singular: true, // Stable performance\n urlRerouteOnly: true, // Optimized routing\n};\n\nif (process.env.NODE_ENV === 'production') {\n start(productionConfig);\n}\n```\n\n### Mobile Configuration\n\n```typescript\nconst mobileConfig = {\n prefetch: (apps) => ({\n // Conservative prefetch on mobile\n criticalAppNames: ['home'],\n minorAppsName: []\n }),\n sandbox: {\n // Lighter sandbox for mobile performance\n strictStyleIsolation: false,\n experimentalStyleIsolation: true,\n },\n singular: true, // Better for mobile UX\n};\n\nconst isMobile = window.innerWidth < 768;\nif (isMobile) {\n start(mobileConfig);\n}\n```\n\n## 🎯 Advanced Configuration Patterns\n\n### 1. Feature Flag Integration\n\n```typescript\nconst getConfigWithFeatureFlags = async () => {\n const featureFlags = await getFeatureFlags();\n \n return {\n prefetch: featureFlags.enablePrefetch ? 'all' : false,\n sandbox: {\n strictStyleIsolation: featureFlags.strictIsolation,\n experimentalStyleIsolation: !featureFlags.strictIsolation,\n },\n singular: featureFlags.allowMultipleApps ? false : true,\n };\n};\n\ngetConfigWithFeatureFlags().then(config => start(config));\n```\n\n### 2. Performance-based Configuration\n\n```typescript\nconst getPerformanceConfig = () => {\n const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;\n const isSlowConnection = connection?.effectiveType === '2g' || connection?.effectiveType === 'slow-2g';\n \n if (isSlowConnection) {\n return {\n prefetch: false, // No prefetch on slow connections\n sandbox: {\n strictStyleIsolation: false,\n experimentalStyleIsolation: true,\n },\n singular: true,\n };\n }\n \n return {\n prefetch: 'all',\n sandbox: {\n strictStyleIsolation: true,\n experimentalStyleIsolation: false,\n },\n singular: false,\n };\n};\n\nstart(getPerformanceConfig());\n```\n\n### 3. User Role-based Configuration\n\n```typescript\nconst getRoleBasedConfig = (userRole) => {\n const baseConfig = {\n sandbox: true,\n singular: true,\n };\n \n switch (userRole) {\n case 'admin':\n return {\n ...baseConfig,\n prefetch: 'all', // Admins get all features\n singular: false, // Can use multiple admin tools\n };\n case 'poweruser':\n return {\n ...baseConfig,\n prefetch: ['dashboard', 'analytics', 'reports'],\n singular: false,\n };\n default:\n return {\n ...baseConfig,\n prefetch: ['dashboard'], // Basic users get minimal prefetch\n singular: true,\n };\n }\n};\n\nconst userRole = getCurrentUserRole();\nstart(getRoleBasedConfig(userRole));\n```\n\n## ⚠️ Important Notes\n\n### 1. Configuration Precedence\n\n```typescript\n// App-level configuration overrides global configuration\nstart({\n sandbox: true, // Global setting\n});\n\nloadMicroApp({\n name: 'special-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n sandbox: false // This overrides the global setting for this app\n});\n```\n\n### 2. Performance Considerations\n\n```typescript\n// ❌ Bad: Heavy configuration that impacts performance\nstart({\n prefetch: 'all', // Might slow down initial load\n sandbox: {\n strictStyleIsolation: true, // More overhead\n },\n singular: false, // More memory usage\n urlRerouteOnly: false, // More frequent route checks\n});\n\n// ✅ Good: Balanced configuration\nstart({\n prefetch: ['critical-app'], // Only prefetch what's needed\n sandbox: {\n experimentalStyleIsolation: true, // Good balance\n },\n singular: true, // Stable performance\n urlRerouteOnly: true, // Optimized routing\n});\n```\n\n### 3. Debugging Configuration\n\n```typescript\nconst debugConfig = {\n sandbox: {\n strictStyleIsolation: false, // Easier to inspect styles\n experimentalStyleIsolation: true,\n },\n // Custom fetch for logging\n fetch: async (url, options) => {\n console.log(`[DEBUG] Fetching: ${url}`);\n const response = await fetch(url, options);\n console.log(`[DEBUG] Response: ${response.status}`);\n return response;\n },\n // Custom node transformer for debugging\n nodeTransformer: (node, options) => {\n if (node.tagName === 'SCRIPT') {\n console.log(`[DEBUG] Processing script: ${node.src || 'inline'}`);\n }\n return node;\n }\n};\n```\n\n## 🔗 Related APIs\n\n- [start](/api/start) - Start qiankun with configuration\n- [loadMicroApp](/api/load-micro-app) - Load app with configuration\n- [registerMicroApps](/api/register-micro-apps) - Register apps " }, { "path": "docs/api/index.md", "content": "# API Reference\n\nqiankun provides a simple yet powerful API set for building micro-frontend applications. All APIs are fully typed with TypeScript definitions to ensure both developer experience and type safety.\n\n## 📚 Core APIs\n\n### Application Registration & Startup\n\n| API | Description | Type |\n|-----|-------------|------|\n| [`registerMicroApps`](/api/register-micro-apps) | Register micro applications | `(apps: RegistrableApp[], lifeCycles?: LifeCycles) => void` |\n| [`start`](/api/start) | Start qiankun framework | `(opts?: StartOpts) => void` |\n| [`loadMicroApp`](/api/load-micro-app) | Manually load micro application | `(app: LoadableApp, configuration?: AppConfiguration, lifeCycles?: LifeCycles) => MicroApp` |\n\n### Utility APIs\n\n| API | Description | Type |\n|-----|-------------|------|\n| [`isRuntimeCompatible`](/api/is-runtime-compatible) | Check runtime compatibility | `() => boolean` |\n\n## 🎯 Quick Navigation\n\n### By Use Case\n\n**Route-based Mode**\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\n// 1. Register micro apps\nregisterMicroApps([...]);\n\n// 2. Start framework\nstart();\n```\n\n**Manual Loading Mode**\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\n// Manually load micro app\nconst microApp = loadMicroApp({...});\n```\n\n**Compatibility Check**\n```typescript\nimport { isRuntimeCompatible } from 'qiankun';\n\nif (isRuntimeCompatible()) {\n // Start micro-frontend application\n}\n```\n\n### By Functionality\n\n| Category | Related APIs | Description |\n|----------|--------------|-------------|\n| **App Management** | `registerMicroApps`, `loadMicroApp` | Register and load micro applications |\n| **Framework Control** | `start` | Framework startup and configuration |\n| **Utilities** | `isRuntimeCompatible` | Helper utility methods |\n\n## 🔧 Type Definitions\n\nqiankun provides complete TypeScript type definitions:\n\n```typescript\nimport type {\n RegistrableApp,\n LoadableApp,\n MicroApp,\n LifeCycles,\n AppConfiguration,\n} from 'qiankun';\n```\n\nSee [Type Definitions](/api/types) for detailed information.\n\n## 📖 Detailed Documentation\n\n### Core APIs\n- [registerMicroApps](/api/register-micro-apps) - Register micro applications\n- [start](/api/start) - Start qiankun framework\n- [loadMicroApp](/api/load-micro-app) - Manually load micro applications\n- [isRuntimeCompatible](/api/is-runtime-compatible) - Runtime compatibility check\n\n### Reference Documentation\n- [Lifecycles](/api/lifecycles) - Application lifecycle hooks\n- [Configuration](/api/configuration) - Framework configuration options\n- [Types](/api/types) - TypeScript type definitions\n\n## 💡 Usage Recommendations\n\n### Recommended API Usage Patterns\n\n1. **Standard Route-based Mode** (Recommended)\n ```typescript\n registerMicroApps([...]) → start()\n ```\n\n2. **Dynamic Loading Mode**\n ```typescript\n loadMicroApp({...}) \n ```\n\n3. **Hybrid Mode**\n ```typescript\n registerMicroApps([...]) → start() + loadMicroApp({...})\n ```\n\n### Best Practices\n\n- ✅ Use TypeScript for complete type support\n- ✅ Register all micro apps before starting the framework\n- ✅ Use lifecycle hooks appropriately for state management\n- ✅ Configure proper error handling\n\n- ❌ Avoid registering duplicate app names\n- ❌ Avoid calling main app APIs from micro apps\n- ❌ Avoid time-consuming operations in lifecycle hooks " }, { "path": "docs/api/is-runtime-compatible.md", "content": "# isRuntimeCompatible\n\nCheck if the current browser environment is compatible with qiankun runtime features.\n\n## 🎯 Function Signature\n\n```typescript\nfunction isRuntimeCompatible(): boolean\n```\n\n## 📋 Parameters\n\nThis function takes no parameters.\n\n## 🔄 Return Value\n\n- **Type**: `boolean`\n- **Description**: Returns `true` if the current environment supports qiankun features, `false` otherwise.\n\n## 💡 Usage Examples\n\n### Basic Compatibility Check\n\n```typescript\nimport { isRuntimeCompatible, registerMicroApps, start } from 'qiankun';\n\nif (isRuntimeCompatible()) {\n // Environment supports qiankun\n registerMicroApps([...]);\n start();\n} else {\n // Fallback for unsupported browsers\n console.warn('Current browser does not support qiankun');\n initFallbackRouting();\n}\n```\n\n### With Graceful Degradation\n\n```typescript\nfunction initApplication() {\n if (isRuntimeCompatible()) {\n // Use qiankun micro-frontend architecture\n initMicroFrontend();\n } else {\n // Fall back to traditional SPA\n initTraditionalSPA();\n }\n}\n\nfunction initMicroFrontend() {\n registerMicroApps([\n {\n name: 'module-a',\n entry: '//localhost:8001',\n container: '#container',\n activeRule: '/module-a',\n }\n ]);\n start();\n}\n\nfunction initTraditionalSPA() {\n // Traditional routing setup\n import('./traditional-router').then(router => {\n router.init();\n });\n}\n```\n\n## 🔍 What It Checks\n\nThe `isRuntimeCompatible` function checks for the following browser features:\n\n### Required Features\n\n1. **Proxy Support**: For JavaScript sandbox isolation\n2. **Window.Proxy**: Essential for creating isolated execution contexts\n3. **Import Maps** (when used): For dynamic module loading\n4. **Dynamic Import**: For loading micro applications\n\n### Browser Compatibility\n\n| Browser | Minimum Version | Support |\n|---------|----------------|---------|\n| Chrome | 61+ | ✅ Full |\n| Firefox | 60+ | ✅ Full |\n| Safari | 11+ | ✅ Full |\n| Edge | 79+ | ✅ Full |\n| IE | Any | ❌ Not Supported |\n\n## 🚀 Best Practices\n\n### 1. Early Detection\n\n```typescript\n// Check compatibility before any qiankun setup\nfunction bootstrap() {\n if (!isRuntimeCompatible()) {\n showUnsupportedBrowserMessage();\n return;\n }\n\n // Safe to proceed with qiankun\n setupMicroFrontend();\n}\n```\n\n### 2. Progressive Enhancement\n\n```typescript\nclass ApplicationBootstrap {\n private isQiankunSupported = isRuntimeCompatible();\n\n init() {\n if (this.isQiankunSupported) {\n this.initWithMicroFrontend();\n } else {\n this.initWithoutMicroFrontend();\n }\n }\n\n private initWithMicroFrontend() {\n // Full micro-frontend experience\n registerMicroApps([...]);\n start();\n }\n\n private initWithoutMicroFrontend() {\n // Simplified experience for unsupported browsers\n this.loadAllModulesDirectly();\n }\n}\n```\n\n### 3. User Communication\n\n```typescript\nif (!isRuntimeCompatible()) {\n // Show user-friendly message\n const banner = document.createElement('div');\n banner.innerHTML = `\n
\n Browser Compatibility Notice:\n For the best experience, please use a modern browser like Chrome, Firefox, or Safari.\n Some features may be limited in your current browser.\n
\n `;\n document.body.insertBefore(banner, document.body.firstChild);\n}\n```\n\n## 🔧 Integration Patterns\n\n### 1. With Feature Flags\n\n```typescript\nconst featureFlags = {\n useMicroFrontend: isRuntimeCompatible() && process.env.ENABLE_MICRO_FRONTEND,\n useAdvancedFeatures: isRuntimeCompatible(),\n};\n\nif (featureFlags.useMicroFrontend) {\n // Full micro-frontend setup\n registerMicroApps([...]);\n start();\n} else {\n // Traditional setup\n initTraditionalApp();\n}\n```\n\n### 2. With Analytics\n\n```typescript\n// Track browser compatibility for analytics\nconst compatible = isRuntimeCompatible();\n\n// Send analytics event\nanalytics.track('browser_compatibility_check', {\n compatible,\n userAgent: navigator.userAgent,\n timestamp: Date.now(),\n});\n\nif (compatible) {\n initQiankunApp();\n} else {\n initFallbackApp();\n}\n```\n\n### 3. With Dynamic Loading\n\n```typescript\nasync function loadApplicationFramework() {\n if (isRuntimeCompatible()) {\n // Load qiankun and micro-frontend modules\n const [qiankun, microApps] = await Promise.all([\n import('qiankun'),\n import('./micro-apps-config'),\n ]);\n \n qiankun.registerMicroApps(microApps.default);\n qiankun.start();\n } else {\n // Load traditional SPA modules\n const traditionalApp = await import('./traditional-app');\n traditionalApp.init();\n }\n}\n```\n\n## ⚠️ Important Notes\n\n### 1. Performance Consideration\n\n```typescript\n// ✅ Good: Check once and cache the result\nconst QIANKUN_COMPATIBLE = isRuntimeCompatible();\n\nfunction someFunction() {\n if (QIANKUN_COMPATIBLE) {\n // Use cached result\n }\n}\n\n// ❌ Bad: Check multiple times\nfunction someFunction() {\n if (isRuntimeCompatible()) { // Redundant check\n // ...\n }\n}\n```\n\n### 2. SSR Considerations\n\n```typescript\n// In SSR environments, check if window is available\nfunction safeCompatibilityCheck() {\n if (typeof window === 'undefined') {\n // SSR environment - assume compatible\n return true;\n }\n \n return isRuntimeCompatible();\n}\n```\n\n### 3. Testing Environment\n\n```typescript\n// For testing, you might want to mock the compatibility\nif (process.env.NODE_ENV === 'test') {\n // Mock for testing\n global.mockQiankunCompatible = true;\n}\n\nfunction checkCompatibility() {\n if (process.env.NODE_ENV === 'test' && global.mockQiankunCompatible !== undefined) {\n return global.mockQiankunCompatible;\n }\n \n return isRuntimeCompatible();\n}\n```\n\n## 🎯 Common Scenarios\n\n### 1. Corporate Environment\n\n```typescript\n// Corporate environments might have older browsers\nfunction initCorporateApp() {\n const compatible = isRuntimeCompatible();\n \n if (!compatible) {\n // Inform IT department about browser requirements\n logToAdminConsole('User browser incompatible with micro-frontend features');\n }\n \n return compatible ? initMicroFrontend() : initLegacyApp();\n}\n```\n\n### 2. Public Website\n\n```typescript\n// Public websites need to support a wider range of browsers\nfunction initPublicSite() {\n if (isRuntimeCompatible()) {\n // Enhanced experience with micro-frontends\n loadAdvancedFeatures();\n } else {\n // Basic experience that works everywhere\n loadBasicFeatures();\n }\n}\n```\n\n### 3. Mobile App WebView\n\n```typescript\n// Mobile WebViews might have different compatibility\nfunction initMobileWebView() {\n const compatible = isRuntimeCompatible();\n \n // Log for mobile app developers\n if (window.ReactNativeWebView) {\n window.ReactNativeWebView.postMessage(JSON.stringify({\n type: 'qiankun_compatibility',\n compatible,\n }));\n }\n \n return compatible ? initMicroFrontend() : initSimplifiedView();\n}\n```\n\n## 🔗 Related APIs\n\n- [start](/api/start) - Start qiankun (should be called after compatibility check)\n- [registerMicroApps](/api/register-micro-apps) - Register micro applications\n- [loadMicroApp](/api/load-micro-app) - Manually load micro applications " }, { "path": "docs/api/lifecycles.md", "content": "# Lifecycles\n\nLifecycle hooks allow you to perform custom logic at different stages of a micro application's lifecycle. These hooks are executed automatically by qiankun during application loading, mounting, and unmounting processes.\n\n## 🎯 Type Definition\n\n```typescript\nexport type LifeCycleFn = (\n app: LoadableApp, \n global: WindowProxy\n) => Promise;\n\nexport type LifeCycles = {\n beforeLoad?: LifeCycleFn | Array>;\n beforeMount?: LifeCycleFn | Array>;\n afterMount?: LifeCycleFn | Array>;\n beforeUnmount?: LifeCycleFn | Array>;\n afterUnmount?: LifeCycleFn | Array>;\n};\n```\n\n## 📋 Available Lifecycle Hooks\n\n### beforeLoad\n\n**Timing**: Called before the micro application starts loading.\n\n**Purpose**: Perform setup tasks before the application code is fetched and parsed.\n\n```typescript\nbeforeLoad: async (app, global) => {\n console.log(`About to load ${app.name}`);\n // Setup global configurations\n global.__INITIAL_CONFIG__ = getInitialConfig();\n}\n```\n\n### beforeMount\n\n**Timing**: Called after the application is loaded but before it's mounted to the DOM.\n\n**Purpose**: Perform final setup before the application becomes active.\n\n```typescript\nbeforeMount: async (app, global) => {\n console.log(`About to mount ${app.name}`);\n // Initialize services\n await initializeServices();\n // Set loading state\n setLoadingState(false);\n}\n```\n\n### afterMount\n\n**Timing**: Called after the micro application has been successfully mounted.\n\n**Purpose**: Perform post-mount operations like analytics, feature initialization.\n\n```typescript\nafterMount: async (app, global) => {\n console.log(`${app.name} mounted successfully`);\n // Track analytics\n analytics.track('micro_app_mounted', { appName: app.name });\n // Initialize features that depend on DOM\n initializeDOMDependentFeatures();\n}\n```\n\n### beforeUnmount\n\n**Timing**: Called before the micro application starts unmounting.\n\n**Purpose**: Cleanup operations before the application is removed.\n\n```typescript\nbeforeUnmount: async (app, global) => {\n console.log(`About to unmount ${app.name}`);\n // Save application state\n saveApplicationState(app.name);\n // Cleanup event listeners\n cleanupEventListeners();\n}\n```\n\n### afterUnmount\n\n**Timing**: Called after the micro application has been completely unmounted.\n\n**Purpose**: Final cleanup and resource deallocation.\n\n```typescript\nafterUnmount: async (app, global) => {\n console.log(`${app.name} unmounted`);\n // Clear caches\n clearApplicationCache(app.name);\n // Reset global state\n resetGlobalState();\n}\n```\n\n## 🔄 Lifecycle Flow\n\n```mermaid\ngraph TD\n A[Start Loading] --> B[beforeLoad]\n B --> C[Load Application Code]\n C --> D[beforeMount]\n D --> E[Mount Application]\n E --> F[afterMount]\n F --> G[Application Running]\n G --> H[beforeUnmount]\n H --> I[Unmount Application]\n I --> J[afterUnmount]\n J --> K[Application Cleaned Up]\n```\n\n## 💡 Usage Examples\n\n### Basic Usage with registerMicroApps\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'react-app',\n entry: '//localhost:7100',\n container: '#subapp-viewport',\n activeRule: '/react',\n }\n], {\n beforeLoad: async (app) => {\n console.log('Loading app:', app.name);\n },\n afterMount: async (app) => {\n console.log('App mounted:', app.name);\n },\n beforeUnmount: async (app) => {\n console.log('Unmounting app:', app.name);\n }\n});\n\nstart();\n```\n\n### With loadMicroApp\n\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst microApp = loadMicroApp({\n name: 'dashboard',\n entry: '//localhost:8080',\n container: '#dashboard-container',\n}, undefined, {\n beforeLoad: async (app, global) => {\n // Setup dashboard-specific configurations\n global.DASHBOARD_CONFIG = getDashboardConfig();\n },\n afterMount: async (app) => {\n // Initialize dashboard widgets\n initializeDashboardWidgets();\n }\n});\n```\n\n### Multiple Hooks\n\n```typescript\n// You can provide multiple hooks as an array\nconst lifecycles = {\n beforeMount: [\n async (app) => {\n await setupDatabase();\n },\n async (app) => {\n await setupAnalytics();\n },\n async (app) => {\n await setupFeatureFlags();\n }\n ],\n afterMount: [\n async (app) => {\n trackPageView(app.name);\n },\n async (app) => {\n initializeUserTracking();\n }\n ]\n};\n```\n\n## 🔧 Advanced Patterns\n\n### 1. State Management Integration\n\n```typescript\nimport { store } from './store';\n\nconst lifecycles = {\n beforeLoad: async (app) => {\n // Set loading state\n store.dispatch({ type: 'SET_APP_LOADING', payload: { appName: app.name, loading: true } });\n },\n \n afterMount: async (app) => {\n // Update mounted apps list\n store.dispatch({ type: 'ADD_MOUNTED_APP', payload: app.name });\n store.dispatch({ type: 'SET_APP_LOADING', payload: { appName: app.name, loading: false } });\n },\n \n beforeUnmount: async (app) => {\n // Save app state before unmounting\n const appState = getAppState(app.name);\n store.dispatch({ type: 'SAVE_APP_STATE', payload: { appName: app.name, state: appState } });\n },\n \n afterUnmount: async (app) => {\n // Remove from mounted apps list\n store.dispatch({ type: 'REMOVE_MOUNTED_APP', payload: app.name });\n }\n};\n```\n\n### 2. Error Handling\n\n```typescript\nconst lifecycles = {\n beforeLoad: async (app) => {\n try {\n await performPreLoadChecks(app);\n } catch (error) {\n console.error(`Pre-load checks failed for ${app.name}:`, error);\n // Optionally prevent loading by throwing\n throw new Error(`Failed to initialize ${app.name}`);\n }\n },\n \n afterMount: async (app) => {\n try {\n await performPostMountTasks(app);\n } catch (error) {\n console.error(`Post-mount tasks failed for ${app.name}:`, error);\n // Log error but don't prevent the app from running\n reportError(error, { context: 'afterMount', appName: app.name });\n }\n }\n};\n```\n\n### 3. Performance Monitoring\n\n```typescript\nconst performanceTracker = new Map();\n\nconst lifecycles = {\n beforeLoad: async (app) => {\n performanceTracker.set(app.name, {\n loadStart: performance.now()\n });\n },\n \n beforeMount: async (app) => {\n const timing = performanceTracker.get(app.name);\n timing.loadEnd = performance.now();\n timing.mountStart = performance.now();\n },\n \n afterMount: async (app) => {\n const timing = performanceTracker.get(app.name);\n timing.mountEnd = performance.now();\n \n // Calculate and report metrics\n const loadTime = timing.loadEnd - timing.loadStart;\n const mountTime = timing.mountEnd - timing.mountStart;\n \n analytics.track('micro_app_performance', {\n appName: app.name,\n loadTime,\n mountTime,\n totalTime: loadTime + mountTime\n });\n }\n};\n```\n\n### 4. Resource Management\n\n```typescript\nconst resourceMap = new Map();\n\nconst lifecycles = {\n beforeMount: async (app) => {\n // Allocate resources\n const resources = await allocateResources(app.name);\n resourceMap.set(app.name, resources);\n },\n \n beforeUnmount: async (app) => {\n // Save critical data\n const resources = resourceMap.get(app.name);\n if (resources) {\n await saveCriticalData(app.name, resources);\n }\n },\n \n afterUnmount: async (app) => {\n // Release resources\n const resources = resourceMap.get(app.name);\n if (resources) {\n await releaseResources(resources);\n resourceMap.delete(app.name);\n }\n }\n};\n```\n\n## 🎯 Common Use Cases\n\n### 1. Loading States\n\n```typescript\nconst loadingManager = {\n show: (appName) => {\n const loader = document.createElement('div');\n loader.id = `loader-${appName}`;\n loader.innerHTML = '
Loading...
';\n document.body.appendChild(loader);\n },\n \n hide: (appName) => {\n const loader = document.getElementById(`loader-${appName}`);\n if (loader) loader.remove();\n }\n};\n\nconst lifecycles = {\n beforeLoad: async (app) => {\n loadingManager.show(app.name);\n },\n \n afterMount: async (app) => {\n loadingManager.hide(app.name);\n }\n};\n```\n\n### 2. Authentication Check\n\n```typescript\nconst lifecycles = {\n beforeLoad: async (app) => {\n const isAuthenticated = await checkAuthentication();\n if (!isAuthenticated) {\n throw new Error('User not authenticated');\n }\n },\n \n beforeMount: async (app, global) => {\n // Inject user context\n const userContext = await getUserContext();\n global.__USER_CONTEXT__ = userContext;\n }\n};\n```\n\n### 3. Theme Synchronization\n\n```typescript\nconst lifecycles = {\n beforeMount: async (app, global) => {\n // Sync theme with micro app\n const currentTheme = getCurrentTheme();\n global.__THEME__ = currentTheme;\n \n // Apply theme-specific styles\n applyThemeStyles(currentTheme);\n },\n \n afterUnmount: async (app) => {\n // Clean up theme styles\n removeThemeStyles(app.name);\n }\n};\n```\n\n### 4. Feature Flag Management\n\n```typescript\nconst lifecycles = {\n beforeLoad: async (app, global) => {\n // Load feature flags for the specific app\n const featureFlags = await getFeatureFlags(app.name);\n global.__FEATURE_FLAGS__ = featureFlags;\n },\n \n afterMount: async (app) => {\n // Track which features are enabled\n trackEnabledFeatures(app.name);\n }\n};\n```\n\n## ⚠️ Important Notes\n\n### 1. Hook Execution Order\n\n```typescript\n// Hooks are executed in this order:\n// 1. beforeLoad (before app code is loaded)\n// 2. beforeMount (after load, before DOM mount)\n// 3. afterMount (after DOM mount)\n// ... app is running ...\n// 4. beforeUnmount (before DOM unmount)\n// 5. afterUnmount (after DOM unmount)\n```\n\n### 2. Error Handling\n\n```typescript\n// ❌ Bad: Unhandled errors can break the lifecycle\nbeforeLoad: async (app) => {\n riskyOperation(); // This could throw\n}\n\n// ✅ Good: Always handle potential errors\nbeforeLoad: async (app) => {\n try {\n await riskyOperation();\n } catch (error) {\n console.error('Error in beforeLoad:', error);\n // Decide whether to throw or handle gracefully\n }\n}\n```\n\n### 3. Async Operations\n\n```typescript\n// ✅ Good: All lifecycle hooks are async\nbeforeMount: async (app) => {\n await setupDatabase();\n await loadUserPreferences();\n}\n\n// ❌ Bad: Don't forget await for async operations\nbeforeMount: async (app) => {\n setupDatabase(); // Missing await!\n loadUserPreferences(); // Missing await!\n}\n```\n\n### 4. Global Context\n\n```typescript\n// ✅ Good: Use the provided global context\nbeforeMount: async (app, global) => {\n global.MY_CONFIG = getConfig(); // Set on the isolated global\n}\n\n// ❌ Bad: Don't use window directly\nbeforeMount: async (app, global) => {\n window.MY_CONFIG = getConfig(); // Might affect other apps\n}\n```\n\n## 🚀 Best Practices\n\n### 1. Keep Hooks Lightweight\n\n```typescript\n// ✅ Good: Fast operations\nbeforeMount: async (app) => {\n setAppTheme(app.name);\n updateNavigationState();\n}\n\n// ❌ Bad: Heavy operations\nbeforeMount: async (app) => {\n await downloadLargeDataset(); // This will block mounting\n await processHeavyCalculations();\n}\n```\n\n### 2. Use Hook Arrays for Organization\n\n```typescript\nconst lifecycles = {\n beforeMount: [\n setupAuthentication,\n setupTheme,\n setupAnalytics,\n setupFeatureFlags\n ],\n afterMount: [\n trackPageView,\n initializeWidgets,\n preloadCriticalData\n ]\n};\n```\n\n### 3. Consistent Error Logging\n\n```typescript\nconst createSafeHook = (hookName, hookFn) => async (app, global) => {\n try {\n await hookFn(app, global);\n } catch (error) {\n console.error(`Error in ${hookName} for ${app.name}:`, error);\n // Report to error tracking service\n errorTracker.report(error, { hook: hookName, app: app.name });\n }\n};\n\nconst lifecycles = {\n beforeLoad: createSafeHook('beforeLoad', async (app) => {\n // Your beforeLoad logic\n }),\n afterMount: createSafeHook('afterMount', async (app) => {\n // Your afterMount logic\n })\n};\n```\n\n### 4. Resource Cleanup\n\n```typescript\n// Track resources in a way that survives app reloads\nconst globalResourceMap = window.__QIANKUN_RESOURCES__ || new Map();\nwindow.__QIANKUN_RESOURCES__ = globalResourceMap;\n\nconst lifecycles = {\n beforeMount: async (app) => {\n const resources = await allocateResources();\n globalResourceMap.set(app.name, resources);\n },\n \n afterUnmount: async (app) => {\n const resources = globalResourceMap.get(app.name);\n if (resources) {\n await cleanupResources(resources);\n globalResourceMap.delete(app.name);\n }\n }\n};\n```\n\n## 🔗 Related APIs\n\n- [registerMicroApps](/api/register-micro-apps) - Using lifecycles with registered apps\n- [loadMicroApp](/api/load-micro-app) - Using lifecycles with manually loaded apps\n- [start](/api/start) - Framework startup configuration " }, { "path": "docs/api/load-micro-app.md", "content": "# loadMicroApp\n\nManually load a micro application. This is useful for loading micro applications dynamically or when they are not associated with routing.\n\n## 🎯 Function Signature\n\n```typescript\nfunction loadMicroApp(\n app: LoadableApp,\n configuration?: AppConfiguration,\n lifeCycles?: LifeCycles\n): MicroApp\n```\n\n## 📋 Parameters\n\n### app\n\n- **Type**: `LoadableApp`\n- **Required**: ✅\n- **Description**: Micro application configuration\n\n#### LoadableApp Structure\n\n```typescript\ninterface LoadableApp {\n name: string; // Micro app name, globally unique\n entry: string | EntryOpts; // Micro app entry\n container: string | HTMLElement; // Container for the micro app\n props?: T; // Custom data passed to micro app\n}\n```\n\n| Property | Type | Required | Description |\n|----------|------|----------|-------------|\n| `name` | `string` | ✅ | Micro application name, used as unique identifier |\n| `entry` | `string \\| EntryOpts` | ✅ | Micro application entry, can be URL or resource configuration |\n| `container` | `string \\| HTMLElement` | ✅ | Container node selector or DOM element |\n| `props` | `T` | ❌ | Custom data passed to the micro application |\n\n### configuration\n\n- **Type**: `AppConfiguration`\n- **Required**: ❌\n- **Description**: Advanced configuration options\n\n```typescript\ninterface AppConfiguration {\n sandbox?: boolean; // Enable sandbox isolation\n globalContext?: WindowProxy; // Global context for the micro app\n fetch?: Function; // Custom fetch function\n streamTransformer?: Function; // Stream transformer\n nodeTransformer?: Function; // Node transformer\n}\n```\n\n### lifeCycles\n\n- **Type**: `LifeCycles`\n- **Required**: ❌\n- **Description**: Lifecycle hooks for this specific micro application\n\n## 🔄 Return Value\n\nReturns a `MicroApp` instance with the following methods:\n\n```typescript\ninterface MicroApp {\n mount(): Promise; // Mount the micro app\n unmount(): Promise; // Unmount the micro app\n update(props: any): Promise; // Update micro app props\n getStatus(): string; // Get current status\n loadPromise: Promise; // Loading promise\n mountPromise: Promise; // Mounting promise\n unmountPromise: Promise; // Unmounting promise\n}\n```\n\n## 💡 Usage Examples\n\n### Basic Usage\n\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst microApp = loadMicroApp({\n name: 'manual-app',\n entry: '//localhost:8080',\n container: '#manual-container',\n});\n\n// The micro app will be automatically mounted\n```\n\n### With Custom Props\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'dashboard',\n entry: '//localhost:8080',\n container: '#dashboard-container',\n props: {\n token: localStorage.getItem('token'),\n userId: getCurrentUserId(),\n theme: 'dark'\n }\n});\n```\n\n### With Configuration\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'third-party-app',\n entry: '//external.example.com',\n container: '#external-container',\n}, {\n sandbox: false, // Disable sandbox for legacy apps\n fetch: customFetch, // Use custom fetch\n});\n```\n\n### With Lifecycle Hooks\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'monitored-app',\n entry: '//localhost:8080',\n container: '#monitored-container',\n}, undefined, {\n beforeMount: (app) => {\n console.log('About to mount:', app.name);\n showLoadingSpinner();\n },\n afterMount: (app) => {\n console.log('Mounted successfully:', app.name);\n hideLoadingSpinner();\n },\n beforeUnmount: (app) => {\n console.log('About to unmount:', app.name);\n saveUserState();\n }\n});\n```\n\n## 🔧 Advanced Usage\n\n### Dynamic Loading with Conditions\n\n```typescript\nasync function loadAppConditionally(condition: boolean) {\n if (condition) {\n const microApp = loadMicroApp({\n name: 'conditional-app',\n entry: '//localhost:8080',\n container: '#conditional-container',\n });\n \n return microApp;\n }\n return null;\n}\n```\n\n### Loading Multiple Apps\n\n```typescript\nfunction loadMultipleApps() {\n const apps = [\n { name: 'app1', entry: '//localhost:8001', container: '#container1' },\n { name: 'app2', entry: '//localhost:8002', container: '#container2' },\n { name: 'app3', entry: '//localhost:8003', container: '#container3' },\n ];\n\n const microApps = apps.map(app => loadMicroApp(app));\n return microApps;\n}\n```\n\n### Manual Control\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'controlled-app',\n entry: '//localhost:8080',\n container: '#controlled-container',\n});\n\n// Manual unmount\nawait microApp.unmount();\n\n// Update props\nawait microApp.update({ newData: 'updated' });\n\n// Check status\nconsole.log(microApp.getStatus()); // 'MOUNTED', 'UNMOUNTED', etc.\n```\n\n## 🎭 Use Cases\n\n### 1. Modal/Dialog Applications\n\n```typescript\nfunction openAppModal() {\n const modal = document.createElement('div');\n modal.id = 'app-modal';\n document.body.appendChild(modal);\n\n const microApp = loadMicroApp({\n name: 'modal-app',\n entry: '//localhost:8080',\n container: modal,\n props: { \n onClose: () => {\n microApp.unmount().then(() => {\n document.body.removeChild(modal);\n });\n }\n }\n });\n\n return microApp;\n}\n```\n\n### 2. Tab-based Applications\n\n```typescript\nclass TabManager {\n private activeTabs = new Map();\n\n async switchTab(tabName: string, config: LoadableApp) {\n // Unmount current active tab\n const currentApp = this.activeTabs.get('active');\n if (currentApp) {\n await currentApp.unmount();\n }\n\n // Load new tab\n const newApp = loadMicroApp({\n ...config,\n container: '#tab-content'\n });\n\n this.activeTabs.set('active', newApp);\n this.activeTabs.set(tabName, newApp);\n }\n}\n```\n\n### 3. Widget System\n\n```typescript\nclass WidgetSystem {\n loadWidget(widgetConfig: any) {\n return loadMicroApp({\n name: `widget-${widgetConfig.id}`,\n entry: widgetConfig.url,\n container: `#widget-${widgetConfig.id}`,\n props: widgetConfig.props\n }, {\n sandbox: true // Isolate widgets\n });\n }\n}\n```\n\n## ⚠️ Important Notes\n\n### Container Management\n\n```typescript\n// ❌ Bad: Reusing containers without proper cleanup\nloadMicroApp({ name: 'app1', entry: '//localhost:8001', container: '#shared' });\nloadMicroApp({ name: 'app2', entry: '//localhost:8002', container: '#shared' }); // Conflict!\n\n// ✅ Good: Use unique containers or proper cleanup\nconst app1 = loadMicroApp({ name: 'app1', entry: '//localhost:8001', container: '#container1' });\nconst app2 = loadMicroApp({ name: 'app2', entry: '//localhost:8002', container: '#container2' });\n```\n\n### Memory Management\n\n```typescript\n// ✅ Good: Proper cleanup\nconst microApp = loadMicroApp({...});\n\n// When done, always unmount\nwindow.addEventListener('beforeunload', () => {\n microApp.unmount();\n});\n```\n\n### Error Handling\n\n```typescript\ntry {\n const microApp = loadMicroApp({\n name: 'potentially-failing-app',\n entry: '//unreliable-server.com',\n container: '#container',\n });\n\n // Wait for load\n await microApp.loadPromise;\n console.log('App loaded successfully');\n} catch (error) {\n console.error('Failed to load micro app:', error);\n // Handle error - show fallback UI, retry, etc.\n}\n```\n\n## 🆚 vs registerMicroApps\n\n| Feature | `loadMicroApp` | `registerMicroApps` |\n|---------|----------------|---------------------|\n| **Loading** | Manual, immediate | Automatic, route-based |\n| **Use Case** | Dynamic loading, widgets, modals | Main navigation, SPA routing |\n| **Lifecycle** | Manual control | Automatic by routing |\n| **Performance** | Load on demand | Can preload |\n\n## 🚀 Best Practices\n\n### 1. Resource Management\n\n```typescript\nclass MicroAppManager {\n private apps = new Map();\n\n async loadApp(config: LoadableApp) {\n // Check if already loaded\n if (this.apps.has(config.name)) {\n return this.apps.get(config.name);\n }\n\n const app = loadMicroApp(config);\n this.apps.set(config.name, app);\n \n // Auto cleanup on unmount\n app.unmountPromise.then(() => {\n this.apps.delete(config.name);\n });\n\n return app;\n }\n}\n```\n\n### 2. Props Management\n\n```typescript\n// ✅ Good: Reactive props\nfunction createReactiveMicroApp(baseConfig: LoadableApp) {\n let currentApp: MicroApp;\n\n return {\n async updateProps(newProps: any) {\n if (currentApp) {\n await currentApp.update(newProps);\n }\n },\n \n async reload(newConfig: LoadableApp) {\n if (currentApp) {\n await currentApp.unmount();\n }\n currentApp = loadMicroApp({\n ...baseConfig,\n ...newConfig\n });\n }\n };\n}\n```\n\n### 3. Error Boundaries\n\n```typescript\nfunction loadMicroAppWithFallback(config: LoadableApp, fallbackHTML: string) {\n const microApp = loadMicroApp(config);\n \n microApp.loadPromise.catch((error) => {\n console.error('Micro app failed to load:', error);\n // Show fallback content\n const container = typeof config.container === 'string' \n ? document.querySelector(config.container)\n : config.container;\n \n if (container) {\n container.innerHTML = fallbackHTML;\n }\n });\n\n return microApp;\n}\n```\n\n## 🔗 Related APIs\n\n- [registerMicroApps](/api/register-micro-apps) - For route-based micro app loading\n- [start](/api/start) - Start qiankun framework\n- [Lifecycles](/api/lifecycles) - Detailed lifecycle documentation " }, { "path": "docs/api/register-micro-apps.md", "content": "# registerMicroApps\n\n注册微应用到 qiankun 中，这是构建微前端应用的核心 API。\n\n## 🎯 函数签名\n\n```typescript\nfunction registerMicroApps(\n apps: Array>, \n lifeCycles?: LifeCycles\n): void\n```\n\n## 📋 参数\n\n### apps\n\n- **类型**: `Array>`\n- **必填**: ✅\n- **描述**: 微应用注册信息数组\n\n#### RegistrableApp 结构\n\n```typescript\ninterface RegistrableApp {\n name: string; // 微应用名称，全局唯一\n entry: string | { scripts?: string[], styles?: string[] }; // 微应用入口\n container: string | HTMLElement; // 微应用容器节点\n activeRule: string | (location: Location) => boolean; // 激活规则\n props?: T; // 传递给微应用的数据\n loader?: (loading: boolean) => void; // 加载状态回调\n}\n```\n\n| 属性 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `name` | `string` | ✅ | 微应用名称，作为微应用的唯一标识 |\n| `entry` | `string \\| EntryOpts` | ✅ | 微应用的入口，可以是 URL 或资源配置对象 |\n| `container` | `string \\| HTMLElement` | ✅ | 微应用的容器节点选择器或 DOM 节点 |\n| `activeRule` | `string \\| Function` | ✅ | 微应用的激活规则 |\n| `props` | `T` | ❌ | 传递给微应用的自定义数据 |\n| `loader` | `Function` | ❌ | 微应用加载状态改变时的回调函数 |\n\n### lifeCycles\n\n- **类型**: `LifeCycles`\n- **必填**: ❌\n- **描述**: 全局生命周期钩子\n\n```typescript\ninterface LifeCycles {\n beforeLoad?: LifeCycleFn | Array>;\n beforeMount?: LifeCycleFn | Array>;\n afterMount?: LifeCycleFn | Array>;\n beforeUnmount?: LifeCycleFn | Array>;\n afterUnmount?: LifeCycleFn | Array>;\n}\n```\n\n## 💡 使用示例\n\n### 基础用法\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'react16App',\n entry: '//localhost:7100',\n container: '#subapp-viewport',\n activeRule: '/react16',\n },\n {\n name: 'vue3App', \n entry: '//localhost:7101',\n container: '#subapp-viewport',\n activeRule: '/vue3',\n }\n]);\n\nstart();\n```\n\n### 高级配置\n\n```typescript\nregisterMicroApps([\n {\n name: 'dashboard',\n entry: {\n scripts: [\n '//localhost:7100/static/js/main.js'\n ],\n styles: [\n '//localhost:7100/static/css/main.css'\n ]\n },\n container: '#dashboard-container',\n activeRule: (location) => location.pathname.startsWith('/dashboard'),\n props: {\n token: 'your-auth-token',\n userId: 123,\n theme: 'dark'\n },\n loader: (loading) => {\n console.log('Dashboard app loading:', loading);\n // 显示/隐藏 loading 状态\n }\n }\n], {\n beforeLoad: [\n app => console.log('Before load:', app.name),\n app => trackEvent('micro-app-loading', { name: app.name })\n ],\n beforeMount: app => console.log('Before mount:', app.name),\n afterMount: app => console.log('After mount:', app.name),\n beforeUnmount: app => console.log('Before unmount:', app.name),\n afterUnmount: app => console.log('After unmount:', app.name),\n});\n```\n\n## ⚙️ Entry 配置详解\n\n### URL 字符串\n\n最简单的配置方式，qiankun 会通过这个 URL 获取微应用的 HTML：\n\n```typescript\n{\n name: 'app1',\n entry: '//localhost:8080',\n // ...\n}\n```\n\n### 资源对象\n\n精确控制微应用的资源加载：\n\n```typescript\n{\n name: 'app2',\n entry: {\n scripts: [\n '//localhost:8080/static/js/chunk.js',\n '//localhost:8080/static/js/main.js'\n ],\n styles: [\n '//localhost:8080/static/css/main.css'\n ]\n },\n // ...\n}\n```\n\n## 🎯 ActiveRule 配置\n\n### 字符串路径\n\n```typescript\n{\n activeRule: '/react16' // 匹配 /react16/xxx 路径\n}\n```\n\n### 函数判断\n\n```typescript\n{\n activeRule: (location) => {\n // 自定义激活逻辑\n return location.pathname.startsWith('/admin') && \n location.search.includes('module=dashboard');\n }\n}\n```\n\n### 常见模式\n\n```typescript\n// 1. 精确匹配\nactiveRule: (location) => location.pathname === '/exact-path'\n\n// 2. 多路径匹配\nactiveRule: (location) => ['/path1', '/path2'].some(path => \n location.pathname.startsWith(path)\n)\n\n// 3. 带参数匹配\nactiveRule: (location) => /^\\/user\\/\\d+/.test(location.pathname)\n\n// 4. 查询参数匹配\nactiveRule: (location) => new URLSearchParams(location.search).get('app') === 'module1'\n```\n\n## 🔧 Container 配置\n\n### CSS 选择器\n\n```typescript\n{\n container: '#micro-app-container'\n}\n```\n\n### DOM 节点\n\n```typescript\n{\n container: document.querySelector('#container')\n}\n```\n\n## 📨 Props 数据传递\n\n微应用可以通过 props 参数接收主应用传递的数据：\n\n```typescript\n// 主应用\nregisterMicroApps([{\n name: 'child-app',\n // ...\n props: {\n data: { user: 'john' },\n methods: {\n onGlobalStateChange: (state) => console.log(state),\n setGlobalState: (state) => updateGlobalState(state)\n }\n }\n}]);\n```\n\n```typescript\n// 微应用\nexport async function mount(props) {\n console.log(props.data); // { user: 'john' }\n console.log(props.methods); // { onGlobalStateChange, setGlobalState }\n}\n```\n\n## ⚠️ 注意事项\n\n### 应用名称唯一性\n\n```typescript\n// ❌ 错误：重复的应用名称\nregisterMicroApps([\n { name: 'app1', entry: '//localhost:8080', /*...*/ },\n { name: 'app1', entry: '//localhost:8081', /*...*/ }, // 重复！\n]);\n\n// ✅ 正确：唯一的应用名称\nregisterMicroApps([\n { name: 'app1', entry: '//localhost:8080', /*...*/ },\n { name: 'app2', entry: '//localhost:8081', /*...*/ },\n]);\n```\n\n### 容器节点存在性\n\n```typescript\n// ❌ 错误：容器节点不存在\nregisterMicroApps([{\n container: '#non-existent-container', // DOM 中不存在\n // ...\n}]);\n\n// ✅ 正确：确保容器节点存在\nregisterMicroApps([{\n container: '#app-container', // 确保 DOM 中存在\n // ...\n}]);\n```\n\n### 重复注册\n\n```typescript\n// ❌ 错误：重复注册会导致应用重复加载\nregisterMicroApps([...]);\nregisterMicroApps([...]); // 重复注册\n\n// ✅ 正确：只注册一次\nregisterMicroApps([...]);\n```\n\n## 🚀 最佳实践\n\n### 1. 应用配置管理\n\n```typescript\n// 推荐：将应用配置抽取为单独文件\nconst microApps = [\n {\n name: 'order-management',\n entry: getAppEntry('order'),\n container: '#subapp-container',\n activeRule: '/order',\n props: getAppProps('order')\n },\n // ...\n];\n\nregisterMicroApps(microApps, {\n beforeLoad: [initLoadingUI],\n afterMount: [removeLoadingUI],\n});\n```\n\n### 2. 环境配置\n\n```typescript\nconst getAppEntry = (name: string) => {\n const entries = {\n development: {\n order: '//localhost:8001',\n user: '//localhost:8002'\n },\n production: {\n order: '//order.example.com',\n user: '//user.example.com'\n }\n };\n \n return entries[process.env.NODE_ENV][name];\n};\n```\n\n### 3. 统一错误处理\n\n```typescript\nregisterMicroApps(microApps, {\n beforeLoad: (app) => {\n console.log(`Loading ${app.name}...`);\n },\n afterMount: (app) => {\n console.log(`${app.name} mounted successfully`);\n },\n beforeUnmount: (app) => {\n // 清理全局状态\n cleanupGlobalState(app.name);\n }\n});\n```\n\n## 🔗 相关 API\n\n- [start](/api/start) - 启动 qiankun\n- [loadMicroApp](/api/load-micro-app) - 手动加载微应用\n- [生命周期](/api/lifecycles) - 详细的生命周期说明 " }, { "path": "docs/api/start.md", "content": "# start\n\nStart the qiankun framework. This function initializes the micro-frontend system and enables automatic routing-based micro application loading.\n\n## 🎯 Function Signature\n\n```typescript\nfunction start(opts?: StartOpts): void\n```\n\n## 📋 Parameters\n\n### opts\n\n- **Type**: `StartOpts`\n- **Required**: ❌\n- **Description**: Startup configuration options\n\n```typescript\ninterface StartOpts {\n prefetch?: boolean | 'all' | string[] | ((apps: RegistrableApp[]) => { criticalAppNames: string[]; minorAppsName: string[] });\n sandbox?: boolean | { strictStyleIsolation?: boolean; experimentalStyleIsolation?: boolean; };\n singular?: boolean;\n urlRerouteOnly?: boolean;\n // ... other single-spa start options\n}\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `prefetch` | `boolean \\| 'all' \\| string[] \\| Function` | `true` | Resource prefetch strategy |\n| `sandbox` | `boolean \\| SandboxOpts` | `true` | Sandbox isolation configuration |\n| `singular` | `boolean` | `true` | Whether only one micro app can be mounted at a time |\n| `urlRerouteOnly` | `boolean` | `true` | Whether to trigger routing only on URL changes |\n\n## 💡 Usage Examples\n\n### Basic Usage\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\n// Register micro apps first\nregisterMicroApps([\n {\n name: 'react-app',\n entry: '//localhost:7100',\n container: '#subapp-viewport',\n activeRule: '/react',\n },\n {\n name: 'vue-app',\n entry: '//localhost:7101',\n container: '#subapp-viewport',\n activeRule: '/vue',\n },\n]);\n\n// Start qiankun\nstart();\n```\n\n### With Configuration\n\n```typescript\nstart({\n prefetch: false, // Disable prefetch\n sandbox: true, // Enable sandbox\n singular: true, // Only one app at a time\n urlRerouteOnly: true, // Route only on URL changes\n});\n```\n\n### Advanced Sandbox Configuration\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // Enable strict style isolation\n experimentalStyleIsolation: true, // Enable experimental style isolation\n }\n});\n```\n\n### Custom Prefetch Strategy\n\n```typescript\nstart({\n prefetch: 'all', // Prefetch all micro apps\n});\n\n// Or prefetch specific apps\nstart({\n prefetch: ['react-app', 'vue-app'], // Only prefetch these apps\n});\n\n// Or custom prefetch function\nstart({\n prefetch: (apps) => ({\n criticalAppNames: ['dashboard', 'user-center'], // Critical apps to prefetch immediately\n minorAppsName: ['analytics', 'settings'], // Minor apps to prefetch later\n })\n});\n```\n\n## ⚙️ Configuration Options\n\n### Prefetch Strategies\n\n#### 1. Boolean Values\n\n```typescript\n// Disable prefetch completely\nstart({ prefetch: false });\n\n// Enable default prefetch behavior\nstart({ prefetch: true });\n```\n\n#### 2. Prefetch All\n\n```typescript\n// Prefetch all registered micro apps\nstart({ prefetch: 'all' });\n```\n\n#### 3. Selective Prefetch\n\n```typescript\n// Prefetch only specified apps\nstart({ \n prefetch: ['critical-app1', 'critical-app2'] \n});\n```\n\n#### 4. Dynamic Prefetch Strategy\n\n```typescript\nstart({\n prefetch: (apps) => {\n // Custom logic to determine which apps to prefetch\n const criticalApps = apps\n .filter(app => app.name.includes('critical'))\n .map(app => app.name);\n \n const minorApps = apps\n .filter(app => !app.name.includes('critical'))\n .map(app => app.name);\n\n return {\n criticalAppNames: criticalApps, // Prefetch immediately\n minorAppsName: minorApps, // Prefetch when idle\n };\n }\n});\n```\n\n### Sandbox Configuration\n\n#### 1. Boolean Sandbox\n\n```typescript\n// Enable basic sandbox\nstart({ sandbox: true });\n\n// Disable sandbox (not recommended)\nstart({ sandbox: false });\n```\n\n#### 2. Advanced Sandbox\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // Shadow DOM based style isolation\n experimentalStyleIsolation: true, // Scoped CSS based style isolation\n }\n});\n```\n\n### Performance Options\n\n```typescript\nstart({\n singular: false, // Allow multiple apps to mount simultaneously\n urlRerouteOnly: false, // Trigger routing on both URL and programmatic changes\n});\n```\n\n## 🚀 Best Practices\n\n### 1. Call After Registration\n\n```typescript\n// ✅ Correct order\nregisterMicroApps([...]);\nstart();\n\n// ❌ Wrong order\nstart();\nregisterMicroApps([...]); // This won't work properly\n```\n\n### 2. Environment-based Configuration\n\n```typescript\nconst startOpts = {\n prefetch: process.env.NODE_ENV === 'production' ? 'all' : false,\n sandbox: {\n strictStyleIsolation: process.env.NODE_ENV === 'production',\n },\n};\n\nstart(startOpts);\n```\n\n### 3. Performance Optimization\n\n```typescript\n// For better performance in production\nstart({\n prefetch: (apps) => ({\n criticalAppNames: ['dashboard'], // Only prefetch critical apps\n minorAppsName: [], // Don't prefetch minor apps\n }),\n singular: true, // Prevent memory issues\n sandbox: {\n strictStyleIsolation: false, // Use lightweight style isolation\n experimentalStyleIsolation: true,\n },\n});\n```\n\n### 4. Development vs Production\n\n```typescript\nif (process.env.NODE_ENV === 'development') {\n start({\n prefetch: false, // Faster development reload\n sandbox: false, // Easier debugging\n singular: false, // More flexible development\n });\n} else {\n start({\n prefetch: 'all', // Better user experience\n sandbox: true, // Better isolation\n singular: true, // Stable performance\n });\n}\n```\n\n## 🔧 Integration Patterns\n\n### 1. With Loading States\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\nlet isQiankunStarted = false;\n\nfunction startQiankunWithLoading() {\n if (isQiankunStarted) return;\n\n showGlobalLoading();\n\n registerMicroApps([...], {\n beforeLoad: (app) => {\n console.log(`Loading ${app.name}...`);\n },\n afterMount: (app) => {\n console.log(`${app.name} mounted`);\n hideGlobalLoading();\n },\n });\n\n start({\n prefetch: 'all',\n sandbox: true,\n });\n\n isQiankunStarted = true;\n}\n```\n\n### 2. With Error Handling\n\n```typescript\nfunction startQiankunSafely() {\n try {\n registerMicroApps([...]);\n \n start({\n prefetch: 'all',\n sandbox: true,\n });\n\n console.log('Qiankun started successfully');\n } catch (error) {\n console.error('Failed to start qiankun:', error);\n // Fallback to traditional routing or show error page\n window.location.href = '/fallback';\n }\n}\n```\n\n### 3. With Feature Detection\n\n```typescript\nimport { isRuntimeCompatible } from 'qiankun';\n\nif (isRuntimeCompatible()) {\n registerMicroApps([...]);\n start();\n} else {\n console.warn('Browser not compatible with qiankun');\n // Fallback implementation\n initTraditionalRouting();\n}\n```\n\n## ⚠️ Important Notes\n\n### 1. Call Only Once\n\n```typescript\n// ❌ Bad: Multiple calls\nstart();\nstart(); // This will be ignored\n\n// ✅ Good: Single call\nstart();\n```\n\n### 2. Order Matters\n\n```typescript\n// ✅ Correct order\nregisterMicroApps([...]); // 1. Register apps first\nstart(); // 2. Then start\n\n// ❌ Wrong order - apps won't be registered properly\nstart();\nregisterMicroApps([...]);\n```\n\n### 3. Prefetch Considerations\n\n```typescript\n// ⚠️ Be careful with 'all' in large applications\nstart({ prefetch: 'all' }); // Might impact initial load performance\n\n// ✅ Better: Selective prefetch\nstart({ \n prefetch: ['critical-app1', 'critical-app2'] \n});\n```\n\n## 🎯 Common Use Cases\n\n### 1. E-commerce Platform\n\n```typescript\nregisterMicroApps([\n { name: 'product-catalog', entry: '//catalog.example.com', activeRule: '/products' },\n { name: 'shopping-cart', entry: '//cart.example.com', activeRule: '/cart' },\n { name: 'user-account', entry: '//account.example.com', activeRule: '/account' },\n]);\n\nstart({\n prefetch: (apps) => ({\n criticalAppNames: ['shopping-cart'], // Always prefetch cart\n minorAppsName: ['user-account'], // Prefetch account when idle\n }),\n sandbox: true,\n singular: true,\n});\n```\n\n### 2. Admin Dashboard\n\n```typescript\nstart({\n prefetch: false, // Don't prefetch - admin tools are used on demand\n sandbox: {\n strictStyleIsolation: true, // Prevent style conflicts between admin tools\n },\n singular: false, // Allow multiple admin tools open simultaneously\n});\n```\n\n### 3. Multi-tenant Platform\n\n```typescript\nconst tenantId = getCurrentTenantId();\n\nstart({\n prefetch: [`tenant-${tenantId}-dashboard`], // Only prefetch current tenant's apps\n sandbox: true, // Isolate tenant data\n singular: true,\n});\n```\n\n## 🔗 Related APIs\n\n- [registerMicroApps](/api/register-micro-apps) - Register micro applications\n- [loadMicroApp](/api/load-micro-app) - Manually load micro applications\n- [isRuntimeCompatible](/api/is-runtime-compatible) - Check browser compatibility " }, { "path": "docs/api/types.md", "content": "# TypeScript Types\n\nqiankun provides comprehensive TypeScript type definitions to ensure type safety and excellent developer experience. This document covers all available types and interfaces.\n\n## 📋 Core Types\n\n### ObjectType\n\n**Description**: Base type for generic object structures.\n\n```typescript\nexport type ObjectType = Record;\n```\n\n**Usage**:\n```typescript\n// Used as a constraint for generic types\nfunction processApp(props: T): void {\n // T can be any object type\n}\n```\n\n### HTMLEntry\n\n**Description**: Type for micro application entry points.\n\n```typescript\nexport type HTMLEntry = string;\n```\n\n**Usage**:\n```typescript\nconst appEntry: HTMLEntry = '//localhost:8080';\nconst appEntryWithPath: HTMLEntry = '//localhost:8080/micro-app';\n```\n\n## 🏗️ Application Types\n\n### AppMetadata\n\n**Description**: Base metadata for micro applications.\n\n```typescript\ntype AppMetadata = {\n name: string; // Unique application name\n entry: HTMLEntry; // Application entry URL\n};\n```\n\n### LoadableApp\\\n\n**Description**: Configuration for manually loaded micro applications.\n\n```typescript\nexport type LoadableApp = AppMetadata & {\n container: HTMLElement; // DOM container element\n props?: T; // Custom properties passed to the app\n};\n```\n\n**Usage**:\n```typescript\n// Basic usage\nconst app: LoadableApp<{}> = {\n name: 'my-app',\n entry: '//localhost:8080',\n container: document.getElementById('app-container')!,\n};\n\n// With custom props\ninterface MyAppProps {\n theme: 'light' | 'dark';\n userId: string;\n}\n\nconst appWithProps: LoadableApp = {\n name: 'themed-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n theme: 'dark',\n userId: '123'\n }\n};\n```\n\n### RegistrableApp\\\n\n**Description**: Configuration for route-based micro applications.\n\n```typescript\nexport type RegistrableApp = LoadableApp & {\n loader?: (loading: boolean) => void; // Loading state callback\n activeRule: RegisterApplicationConfig['activeWhen']; // Routing activation rule\n};\n```\n\n**Usage**:\n```typescript\nimport { registerMicroApps } from 'qiankun';\n\ninterface UserAppProps {\n currentUser: { id: string; name: string };\n}\n\nconst apps: RegistrableApp[] = [\n {\n name: 'user-dashboard',\n entry: '//localhost:8001',\n container: '#subapp-viewport',\n activeRule: '/dashboard',\n props: {\n currentUser: { id: '123', name: 'John' }\n },\n loader: (loading) => {\n if (loading) {\n showLoadingSpinner();\n } else {\n hideLoadingSpinner();\n }\n }\n }\n];\n\nregisterMicroApps(apps);\n```\n\n## ⚙️ Configuration Types\n\n### AppConfiguration\n\n**Description**: Configuration options for individual micro applications.\n\n```typescript\nexport type AppConfiguration = Partial> & {\n sandbox?: boolean; // Enable sandbox isolation\n globalContext?: WindowProxy; // Custom global context\n};\n```\n\n**Usage**:\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst customConfig: AppConfiguration = {\n sandbox: true,\n globalContext: window,\n fetch: async (url, options) => {\n // Custom fetch implementation\n return fetch(url, {\n ...options,\n headers: {\n ...options?.headers,\n 'Authorization': 'Bearer token'\n }\n });\n },\n nodeTransformer: (node, opts) => {\n // Transform DOM nodes\n if (node.tagName === 'SCRIPT') {\n node.setAttribute('data-app', 'my-app');\n }\n return node;\n }\n};\n\nloadMicroApp({\n name: 'configured-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!\n}, customConfig);\n```\n\n## 🔄 Lifecycle Types\n\n### LifeCycleFn\\\n\n**Description**: Type for lifecycle hook functions.\n\n```typescript\nexport type LifeCycleFn = (\n app: LoadableApp, \n global: WindowProxy\n) => Promise;\n```\n\n**Usage**:\n```typescript\nconst beforeLoadHook: LifeCycleFn<{ theme: string }> = async (app, global) => {\n console.log(`Loading app: ${app.name}`);\n global.__APP_THEME__ = app.props?.theme || 'default';\n};\n\nconst afterMountHook: LifeCycleFn = async (app, global) => {\n console.log(`App ${app.name} mounted successfully`);\n // Track analytics\n analytics.track('app_mounted', { appName: app.name });\n};\n```\n\n### LifeCycles\\\n\n**Description**: Complete lifecycle hooks configuration.\n\n```typescript\nexport type LifeCycles = {\n beforeLoad?: LifeCycleFn | Array>;\n beforeMount?: LifeCycleFn | Array>;\n afterMount?: LifeCycleFn | Array>;\n beforeUnmount?: LifeCycleFn | Array>;\n afterUnmount?: LifeCycleFn | Array>;\n};\n```\n\n**Usage**:\n```typescript\ninterface AppProps {\n userId: string;\n permissions: string[];\n}\n\nconst lifecycles: LifeCycles = {\n beforeLoad: async (app, global) => {\n // Setup before loading\n global.__USER_ID__ = app.props?.userId;\n },\n \n beforeMount: [\n async (app, global) => {\n // Multiple hooks as array\n await setupAuthentication(app.props?.userId);\n },\n async (app, global) => {\n await loadUserPermissions(app.props?.permissions);\n }\n ],\n \n afterMount: async (app) => {\n console.log(`${app.name} is ready`);\n },\n \n beforeUnmount: async (app) => {\n // Cleanup before unmounting\n await saveUserState(app.name);\n },\n \n afterUnmount: async (app) => {\n // Final cleanup\n await clearUserData(app.name);\n }\n};\n```\n\n## 🎯 Micro App Types\n\n### MicroApp\n\n**Description**: Instance of a loaded micro application.\n\n```typescript\nexport type MicroApp = Parcel;\n```\n\nThe `MicroApp` type extends the single-spa `Parcel` interface with these methods:\n\n```typescript\ninterface MicroApp {\n mount(): Promise; // Mount the application\n unmount(): Promise; // Unmount the application \n update(props: any): Promise; // Update application props\n getStatus(): string; // Get current status\n loadPromise: Promise; // Promise that resolves when loaded\n mountPromise: Promise; // Promise that resolves when mounted\n unmountPromise: Promise; // Promise that resolves when unmounted\n}\n```\n\n**Usage**:\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst microApp: MicroApp = loadMicroApp({\n name: 'my-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!\n});\n\n// Check status\nconsole.log(microApp.getStatus()); // 'LOADING', 'MOUNTED', 'UNMOUNTED', etc.\n\n// Wait for mounting\nawait microApp.mountPromise;\nconsole.log('App is mounted');\n\n// Update props\nawait microApp.update({ newTheme: 'dark' });\n\n// Unmount when done\nawait microApp.unmount();\n```\n\n### MicroAppLifeCycles\n\n**Description**: Internal lifecycle type used by qiankun.\n\n```typescript\nexport type MicroAppLifeCycles = FlattenArrayValue>;\n```\n\nThis type is primarily for internal use and represents the flattened lifecycle functions that micro applications must export.\n\n## 🌐 Global Types\n\n### Window Extensions\n\nqiankun extends the global `Window` interface with special properties:\n\n```typescript\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean; // Indicates app is running in qiankun\n __INJECTED_PUBLIC_PATH_BY_QIANKUN__?: string; // Injected public path\n __QIANKUN_DEVELOPMENT__?: boolean; // Development mode flag\n Zone?: CallableFunction; // Zone.js compatibility\n __zone_symbol__setTimeout?: Window['setTimeout']; // Zone.js timeout\n }\n}\n```\n\n**Usage in Micro Applications**:\n```typescript\n// Check if running in qiankun\nif (window.__POWERED_BY_QIANKUN__) {\n console.log('Running as a micro app');\n \n // Use injected public path\n const publicPath = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__ || '/';\n \n // Configure your app accordingly\n setupApp({ publicPath });\n} else {\n console.log('Running standalone');\n setupApp({ publicPath: '/' });\n}\n```\n\n## 🎨 Utility Types\n\n### Custom Type Guards\n\nCreate type guards for better type safety:\n\n```typescript\n// Type guard for LoadableApp\nfunction isLoadableApp(\n app: any\n): app is LoadableApp {\n return (\n typeof app === 'object' &&\n typeof app.name === 'string' &&\n typeof app.entry === 'string' &&\n app.container instanceof HTMLElement\n );\n}\n\n// Type guard for RegistrableApp\nfunction isRegistrableApp(\n app: any\n): app is RegistrableApp {\n return (\n isLoadableApp(app) &&\n (typeof app.activeRule === 'string' || typeof app.activeRule === 'function')\n );\n}\n\n// Usage\nfunction processApp(app: unknown) {\n if (isRegistrableApp(app)) {\n // TypeScript knows app is RegistrableApp here\n console.log(`Registering app: ${app.name} with rule: ${app.activeRule}`);\n } else if (isLoadableApp(app)) {\n // TypeScript knows app is LoadableApp here\n console.log(`Loading app: ${app.name}`);\n }\n}\n```\n\n### Generic Helper Types\n\nCreate reusable generic types for common patterns:\n\n```typescript\n// Props with theme support\ntype ThemedProps = T & {\n theme?: 'light' | 'dark';\n};\n\n// Props with user context\ntype UserAwareProps = T & {\n currentUser?: {\n id: string;\n name: string;\n role: string;\n };\n};\n\n// Combined props\ntype AppProps = ThemedProps>;\n\n// Usage\nconst app: LoadableApp> = {\n name: 'themed-user-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n theme: 'dark',\n currentUser: { id: '123', name: 'John', role: 'admin' },\n customData: 'custom value'\n }\n};\n```\n\n## 📖 Advanced Type Patterns\n\n### Conditional Types for Configuration\n\n```typescript\n// Configuration based on environment\ntype EnvironmentConfig = T extends 'development'\n ? {\n sandbox: false;\n prefetch: false;\n strictStyleIsolation: false;\n }\n : {\n sandbox: true;\n prefetch: 'all';\n strictStyleIsolation: true;\n };\n\n// Usage with environment detection\ndeclare const NODE_ENV: 'development' | 'production';\ntype CurrentConfig = EnvironmentConfig;\n```\n\n### Branded Types for App Names\n\n```typescript\n// Create branded type for app names to prevent mix-ups\ntype AppName = string & { readonly __brand: unique symbol };\n\nfunction createAppName(name: string): AppName {\n return name as AppName;\n}\n\n// Enhanced LoadableApp with branded name\ntype SafeLoadableApp = Omit, 'name'> & {\n name: AppName;\n};\n\n// Usage\nconst appName = createAppName('my-secure-app');\nconst app: SafeLoadableApp<{}> = {\n name: appName, // Type-safe app name\n entry: '//localhost:8080',\n container: document.getElementById('container')!\n};\n```\n\n### Lifecycle Event Types\n\n```typescript\n// Enhanced lifecycle with event data\ntype LifeCycleEvent = {\n app: LoadableApp;\n global: WindowProxy;\n timestamp: number;\n phase: 'beforeLoad' | 'beforeMount' | 'afterMount' | 'beforeUnmount' | 'afterUnmount';\n};\n\ntype EnhancedLifeCycleFn = (event: LifeCycleEvent) => Promise;\n\n// Usage\nconst enhancedHook: EnhancedLifeCycleFn<{ userId: string }> = async (event) => {\n console.log(`Phase: ${event.phase}, App: ${event.app.name}, Time: ${event.timestamp}`);\n \n if (event.phase === 'beforeMount') {\n // Setup user context\n event.global.__USER_ID__ = event.app.props?.userId;\n }\n};\n```\n\n## 🔍 Type Inference Examples\n\n### Automatic Props Type Inference\n\n```typescript\n// Helper function with automatic type inference\nfunction createTypedApp(\n config: {\n name: string;\n entry: string;\n container: HTMLElement;\n props: T;\n }\n): LoadableApp {\n return config; // TypeScript infers the correct type\n}\n\n// Usage - TypeScript automatically infers the props type\nconst app = createTypedApp({\n name: 'inferred-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n theme: 'dark',\n userId: '123',\n features: ['feature1', 'feature2']\n }\n // TypeScript knows props type is { theme: string; userId: string; features: string[] }\n});\n```\n\n### Lifecycle Type Inference\n\n```typescript\n// Helper for creating typed lifecycles\nfunction createLifecycles(\n lifecycles: LifeCycles\n): LifeCycles {\n return lifecycles;\n}\n\n// Usage with inference\nconst typedLifecycles = createLifecycles({\n beforeMount: async (app) => {\n // TypeScript infers app.props type based on usage\n console.log(app.props?.theme); // TypeScript knows this might be undefined\n }\n});\n```\n\n## ⚡ Best Practices\n\n### 1. Use Strict Types\n\n```typescript\n// ✅ Good: Strict typing\ninterface StrictAppProps {\n readonly userId: string;\n readonly theme: 'light' | 'dark';\n readonly permissions: readonly string[];\n}\n\nconst app: LoadableApp = {\n name: 'strict-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n userId: '123',\n theme: 'dark',\n permissions: ['read', 'write']\n }\n};\n\n// ❌ Bad: Loose typing\nconst looseApp: LoadableApp = {\n name: 'loose-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: { anything: 'goes' } // No type safety\n};\n```\n\n### 2. Create Domain-Specific Types\n\n```typescript\n// Create types specific to your domain\ninterface ECommerceAppProps {\n cartId: string;\n currency: 'USD' | 'EUR' | 'GBP';\n customerSegment: 'premium' | 'standard';\n features: {\n wishlist: boolean;\n recommendations: boolean;\n reviews: boolean;\n };\n}\n\ntype ECommerceApp = LoadableApp;\ntype ECommerceLifecycles = LifeCycles;\n```\n\n### 3. Use Generic Constraints\n\n```typescript\n// Constrain generic types for better type safety\ninterface BaseAppProps {\n version: string;\n environment: 'development' | 'staging' | 'production';\n}\n\nfunction createApp(\n config: Omit, 'container'> & {\n containerId: string;\n }\n): LoadableApp {\n const container = document.getElementById(config.containerId);\n if (!container) {\n throw new Error(`Container ${config.containerId} not found`);\n }\n \n return {\n ...config,\n container\n };\n}\n```\n\n## 🔗 Related Documentation\n\n- [API Reference](/api/) - Main API documentation\n- [Lifecycles](/api/lifecycles) - Detailed lifecycle documentation\n- [Configuration](/api/configuration) - Configuration options " }, { "path": "docs/cookbook/error-handling.md", "content": "# Error Handling\n\nRobust error handling is essential for micro-frontend applications where multiple independent applications run within the same context. This guide covers comprehensive strategies for handling errors, implementing graceful degradation, and maintaining application stability across qiankun-based micro-frontend systems.\n\n## 🎯 Error Types in Micro-Frontends\n\n### Common Error Categories\n\nMicro-frontend applications face unique error scenarios:\n\n- **Loading Errors**: Failed to fetch or parse micro application resources\n- **Runtime Errors**: JavaScript errors within micro applications\n- **Communication Errors**: Failed inter-application communication\n- **Network Errors**: API calls and resource loading failures\n- **Sandbox Errors**: Issues with JavaScript and CSS isolation\n- **Lifecycle Errors**: Problems during mount/unmount processes\n- **Version Conflicts**: Dependency version mismatches\n\n### Error Impact Assessment\n\n```javascript\n// Error severity levels for micro-frontend applications\nconst ERROR_LEVELS = {\n CRITICAL: 'critical', // Main app or core functionality affected\n HIGH: 'high', // Major micro app functionality lost\n MEDIUM: 'medium', // Partial micro app functionality affected\n LOW: 'low', // Minor features or visual issues\n INFO: 'info' // Non-blocking informational issues\n};\n\nconst ErrorClassifier = {\n classify(error, appName, context) {\n // Critical: Main app crashes or core navigation fails\n if (appName === 'main' || context.includes('navigation')) {\n return ERROR_LEVELS.CRITICAL;\n }\n \n // High: User cannot complete primary workflows\n if (context.includes('checkout') || context.includes('auth')) {\n return ERROR_LEVELS.HIGH;\n }\n \n // Medium: Feature degradation but app still usable\n if (error.name === 'ChunkLoadError' || error.name === 'TypeError') {\n return ERROR_LEVELS.MEDIUM;\n }\n \n // Default to low for other errors\n return ERROR_LEVELS.LOW;\n }\n};\n```\n\n## 🛡️ qiankun Error Boundaries\n\n### Global Error Handling\n\nSet up global error handlers for the entire micro-frontend ecosystem:\n\n```javascript\nimport { addGlobalUncaughtErrorHandler, removeGlobalUncaughtErrorHandler } from 'qiankun';\n\n// Global error handler for all micro apps\nconst globalErrorHandler = (event) => {\n const { error, appName, lifecycleName } = event;\n \n console.error(`Error in micro app \"${appName}\" during \"${lifecycleName}\":`, error);\n \n // Report to error tracking service\n reportError({\n error,\n appName,\n lifecycle: lifecycleName,\n timestamp: Date.now(),\n userAgent: navigator.userAgent,\n url: window.location.href\n });\n \n // Implement recovery strategy\n handleMicroAppError(appName, error, lifecycleName);\n};\n\n// Register global error handler\naddGlobalUncaughtErrorHandler(globalErrorHandler);\n\n// Remove when cleaning up (e.g., in app unmount)\n// removeGlobalUncaughtErrorHandler(globalErrorHandler);\n```\n\n### Lifecycle-Specific Error Handling\n\n```javascript\n// Error handling in lifecycle hooks\nconst errorHandlingLifecycles = {\n async beforeLoad(app) {\n try {\n // Pre-loading checks\n const healthCheck = await fetch(`${app.entry}/health`);\n if (!healthCheck.ok) {\n throw new Error(`Health check failed for ${app.name}`);\n }\n } catch (error) {\n console.warn(`Pre-load health check failed for ${app.name}:`, error);\n // Continue with loading but flag as potentially unstable\n markAppAsUnstable(app.name);\n }\n },\n\n async beforeMount(app) {\n try {\n // Validate app requirements\n validateAppRequirements(app);\n } catch (error) {\n // Attempt to fix common issues\n await attemptAutoFix(app, error);\n }\n },\n\n async afterMount(app) {\n // Verify successful mount\n setTimeout(() => {\n const container = document.querySelector(app.container);\n if (!container || container.children.length === 0) {\n console.error(`Mount verification failed for ${app.name}`);\n showFallbackContent(app.container, app.name);\n }\n }, 1000);\n },\n\n async beforeUnmount(app) {\n try {\n // Clean up resources\n cleanupAppResources(app.name);\n } catch (error) {\n console.warn(`Cleanup error for ${app.name}:`, error);\n // Force cleanup\n forceCleanup(app.name);\n }\n }\n};\n```\n\n## 🚨 Framework-Specific Error Boundaries\n\n### React Error Boundaries\n\n```jsx\n// React error boundary for micro applications\nimport React from 'react';\n\nclass MicroAppErrorBoundary extends React.Component {\n constructor(props) {\n super(props);\n this.state = {\n hasError: false,\n error: null,\n errorInfo: null,\n retryCount: 0,\n lastRetry: null\n };\n }\n\n static getDerivedStateFromError(error) {\n return { hasError: true };\n }\n\n componentDidCatch(error, errorInfo) {\n this.setState({\n error,\n errorInfo\n });\n\n // Report error\n this.reportError(error, errorInfo);\n\n // Attempt automatic recovery\n this.attemptRecovery(error);\n }\n\n reportError = (error, errorInfo) => {\n const errorReport = {\n error: {\n name: error.name,\n message: error.message,\n stack: error.stack\n },\n errorInfo,\n appName: this.props.appName,\n timestamp: Date.now(),\n url: window.location.href,\n userAgent: navigator.userAgent,\n retryCount: this.state.retryCount\n };\n\n // Send to error tracking service\n fetch('/api/errors', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(errorReport)\n }).catch(err => console.error('Failed to report error:', err));\n };\n\n attemptRecovery = (error) => {\n const { retryCount, lastRetry } = this.state;\n const now = Date.now();\n \n // Prevent too frequent retries\n if (lastRetry && now - lastRetry < 5000) {\n return;\n }\n \n // Limit retry attempts\n if (retryCount >= 3) {\n console.error(`Max retry attempts reached for ${this.props.appName}`);\n return;\n }\n\n setTimeout(() => {\n this.setState({\n hasError: false,\n error: null,\n errorInfo: null,\n retryCount: retryCount + 1,\n lastRetry: now\n });\n }, 2000 * Math.pow(2, retryCount)); // Exponential backoff\n };\n\n render() {\n if (this.state.hasError) {\n const { appName, fallbackComponent: FallbackComponent } = this.props;\n \n if (FallbackComponent) {\n return (\n this.attemptRecovery(this.state.error)}\n />\n );\n }\n\n return (\n
\n

Application Error

\n

The {appName} application encountered an error.

\n \n
\n Error Details\n 
{this.state.error?.stack}
\n
\n
\n );\n }\n\n return this.props.children;\n }\n}\n\n// Usage with micro app\nfunction MicroAppContainer({ appName, entry }) {\n return (\n \n
\n \n );\n}\n```\n\n### Vue Error Handling\n\n```javascript\n// Vue global error handler for micro apps\nconst app = createApp(MainApp);\n\napp.config.errorHandler = (err, instance, info) => {\n const appName = instance?.$root?.$options?.name || 'unknown';\n \n console.error(`Vue error in ${appName}:`, err, info);\n \n // Report error\n reportVueError({\n error: err,\n appName,\n info,\n timestamp: Date.now()\n });\n \n // Attempt recovery\n if (instance && typeof instance.$forceUpdate === 'function') {\n instance.$forceUpdate();\n }\n};\n\n// Vue 2 error boundary component\nVue.component('ErrorBoundary', {\n data() {\n return {\n hasError: false,\n error: null\n };\n },\n \n errorCaptured(err, instance, info) {\n this.hasError = true;\n this.error = err;\n \n // Report error\n this.reportError(err, info);\n \n // Prevent error from propagating\n return false;\n },\n \n methods: {\n reportError(error, info) {\n // Error reporting logic\n },\n \n retry() {\n this.hasError = false;\n this.error = null;\n this.$forceUpdate();\n }\n },\n \n render(h) {\n if (this.hasError) {\n return h('div', { class: 'error-boundary' }, [\n h('h3', 'Something went wrong'),\n h('button', { on: { click: this.retry } }, 'Retry'),\n h('pre', this.error?.message)\n ]);\n }\n \n return this.$slots.default;\n }\n});\n```\n\n## 🔄 Graceful Degradation Strategies\n\n### Progressive Enhancement\n\n```javascript\n// Progressive feature loading with fallbacks\nclass FeatureLoader {\n constructor() {\n this.features = new Map();\n this.fallbacks = new Map();\n }\n \n register(featureName, loader, fallback) {\n this.features.set(featureName, loader);\n this.fallbacks.set(featureName, fallback);\n }\n \n async load(featureName) {\n try {\n const loader = this.features.get(featureName);\n if (!loader) {\n throw new Error(`Feature \"${featureName}\" not registered`);\n }\n \n const feature = await loader();\n return feature;\n \n } catch (error) {\n console.warn(`Failed to load feature \"${featureName}\":`, error);\n \n const fallback = this.fallbacks.get(featureName);\n if (fallback) {\n return await fallback();\n }\n \n throw error;\n }\n }\n}\n\n// Usage example\nconst featureLoader = new FeatureLoader();\n\n// Register advanced dashboard with fallback\nfeatureLoader.register(\n 'advanced-dashboard',\n () => import('./AdvancedDashboard'),\n () => import('./BasicDashboard')\n);\n\n// Register chart component with static fallback\nfeatureLoader.register(\n 'interactive-charts',\n () => import('./InteractiveCharts'),\n () => Promise.resolve(() => '
Charts unavailable
')\n);\n```\n\n### Fallback UI Components\n\n```jsx\n// Comprehensive fallback components\nconst ErrorFallbacks = {\n // Network error fallback\n NetworkError: ({ onRetry, appName }) => (\n
\n
🌐
\n

Connection Problem

\n

Unable to load {appName}. Please check your internet connection.

\n
\n \n \n
\n
\n ),\n\n // JavaScript error fallback\n JavaScriptError: ({ error, appName, onRetry }) => (\n
\n
⚠️
\n

Application Error

\n

The {appName} application encountered a technical issue.

\n
\n \n \n
\n {process.env.NODE_ENV === 'development' && (\n
\n Technical Details\n 
{error.stack}
\n
\n )}\n
\n ),\n\n // Loading timeout fallback\n LoadingTimeout: ({ appName, onRetry }) => (\n
\n
⏱️
\n

Loading Timeout

\n

{appName} is taking longer than expected to load.

\n
\n \n \n
\n
\n ),\n\n // Generic fallback\n Generic: ({ error, appName, onRetry }) => (\n
\n
🔧
\n

Temporary Issue

\n

We're experiencing technical difficulties with {appName}.

\n
\n \n
\n
\n )\n};\n```\n\n### Circuit Breaker Pattern\n\n```javascript\n// Circuit breaker for micro app loading\nclass CircuitBreaker {\n constructor(threshold = 5, timeout = 60000, monitor = 30000) {\n this.failureThreshold = threshold;\n this.timeout = timeout;\n this.monitoringPeriod = monitor;\n this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN\n this.failureCount = 0;\n this.lastFailureTime = null;\n this.nextAttemptTime = null;\n }\n\n async execute(operation, appName) {\n if (this.state === 'OPEN') {\n if (Date.now() < this.nextAttemptTime) {\n throw new Error(`Circuit breaker is OPEN for ${appName}`);\n }\n this.state = 'HALF_OPEN';\n }\n\n try {\n const result = await operation();\n this.onSuccess();\n return result;\n } catch (error) {\n this.onFailure();\n throw error;\n }\n }\n\n onSuccess() {\n this.failureCount = 0;\n this.state = 'CLOSED';\n }\n\n onFailure() {\n this.failureCount++;\n this.lastFailureTime = Date.now();\n\n if (this.failureCount >= this.failureThreshold) {\n this.state = 'OPEN';\n this.nextAttemptTime = Date.now() + this.timeout;\n }\n }\n\n getState() {\n return this.state;\n }\n}\n\n// Usage with micro app loading\nconst circuitBreakers = new Map();\n\nconst loadMicroAppWithCircuitBreaker = async (appConfig) => {\n const { name } = appConfig;\n \n if (!circuitBreakers.has(name)) {\n circuitBreakers.set(name, new CircuitBreaker());\n }\n \n const breaker = circuitBreakers.get(name);\n \n try {\n return await breaker.execute(() => loadMicroApp(appConfig), name);\n } catch (error) {\n console.error(`Circuit breaker prevented loading ${name}:`, error);\n throw error;\n }\n};\n```\n\n## 📊 Error Monitoring and Reporting\n\n### Comprehensive Error Tracking\n\n```javascript\n// Advanced error tracking system\nclass ErrorTracker {\n constructor(config) {\n this.config = {\n endpoint: '/api/errors',\n batchSize: 10,\n batchTimeout: 5000,\n maxRetries: 3,\n ...config\n };\n \n this.errorQueue = [];\n this.batchTimeout = null;\n this.retryCount = new Map();\n }\n\n track(error, context = {}) {\n const errorData = this.serializeError(error, context);\n \n // Add to queue\n this.errorQueue.push(errorData);\n \n // Process batch if queue is full\n if (this.errorQueue.length >= this.config.batchSize) {\n this.processBatch();\n } else {\n // Set timeout for batch processing\n this.scheduleBatchProcessing();\n }\n }\n\n serializeError(error, context) {\n return {\n id: this.generateErrorId(),\n timestamp: Date.now(),\n error: {\n name: error.name,\n message: error.message,\n stack: error.stack,\n fileName: error.fileName,\n lineNumber: error.lineNumber,\n columnNumber: error.columnNumber\n },\n context: {\n appName: context.appName || 'unknown',\n userId: context.userId,\n sessionId: this.getSessionId(),\n url: window.location.href,\n userAgent: navigator.userAgent,\n viewport: {\n width: window.innerWidth,\n height: window.innerHeight\n },\n ...context\n },\n environment: {\n isDevelopment: process.env.NODE_ENV === 'development',\n timestamp: Date.now(),\n timezone: Intl.DateTimeFormat().resolvedOptions().timeZone\n }\n };\n }\n\n scheduleBatchProcessing() {\n if (this.batchTimeout) {\n clearTimeout(this.batchTimeout);\n }\n \n this.batchTimeout = setTimeout(() => {\n this.processBatch();\n }, this.config.batchTimeout);\n }\n\n async processBatch() {\n if (this.errorQueue.length === 0) return;\n \n const batch = this.errorQueue.splice(0, this.config.batchSize);\n \n try {\n await this.sendErrors(batch);\n \n // Clear retry count on success\n batch.forEach(error => {\n this.retryCount.delete(error.id);\n });\n \n } catch (error) {\n console.error('Failed to send error batch:', error);\n \n // Retry logic\n batch.forEach(errorData => {\n const retries = this.retryCount.get(errorData.id) || 0;\n if (retries < this.config.maxRetries) {\n this.retryCount.set(errorData.id, retries + 1);\n this.errorQueue.unshift(errorData); // Add back to front of queue\n }\n });\n }\n }\n\n async sendErrors(errors) {\n const response = await fetch(this.config.endpoint, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ errors })\n });\n\n if (!response.ok) {\n throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n }\n\n return response.json();\n }\n\n generateErrorId() {\n return `error_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;\n }\n\n getSessionId() {\n // Implementation to get/generate session ID\n return sessionStorage.getItem('sessionId') || 'anonymous';\n }\n}\n\n// Initialize global error tracker\nconst errorTracker = new ErrorTracker();\n\n// Track unhandled errors\nwindow.addEventListener('error', (event) => {\n errorTracker.track(event.error, {\n type: 'unhandled_error',\n source: 'window.onerror'\n });\n});\n\n// Track unhandled promise rejections\nwindow.addEventListener('unhandledrejection', (event) => {\n errorTracker.track(event.reason, {\n type: 'unhandled_rejection',\n source: 'unhandledrejection'\n });\n});\n```\n\n### Performance Impact Monitoring\n\n```javascript\n// Monitor error impact on performance\nclass ErrorImpactMonitor {\n constructor() {\n this.errorImpacts = new Map();\n this.performanceBaseline = this.measureBaseline();\n }\n\n measureBaseline() {\n return {\n loadTime: performance.now(),\n memoryUsage: performance.memory ? performance.memory.usedJSHeapSize : 0,\n timing: performance.timing\n };\n }\n\n recordErrorImpact(errorId, appName) {\n const impact = {\n errorId,\n appName,\n timestamp: Date.now(),\n performance: {\n loadTime: performance.now(),\n memoryUsage: performance.memory ? performance.memory.usedJSHeapSize : 0,\n timing: performance.timing\n },\n userExperience: {\n pageVisible: !document.hidden,\n userActive: this.isUserActive(),\n scrollPosition: window.scrollY\n }\n };\n\n this.errorImpacts.set(errorId, impact);\n this.analyzeImpact(impact);\n }\n\n analyzeImpact(impact) {\n const { performance: current } = impact;\n const baseline = this.performanceBaseline;\n\n const memoryIncrease = current.memoryUsage - baseline.memoryUsage;\n const loadTimeIncrease = current.loadTime - baseline.loadTime;\n\n if (memoryIncrease > 50 * 1024 * 1024) { // 50MB\n console.warn('High memory impact detected after error:', impact);\n }\n\n if (loadTimeIncrease > 5000) { // 5 seconds\n console.warn('Significant performance degradation after error:', impact);\n }\n }\n\n isUserActive() {\n // Simple user activity detection\n return Date.now() - this.lastUserActivity < 30000;\n }\n}\n```\n\n## 🔧 Recovery Mechanisms\n\n### Automatic Recovery Strategies\n\n```javascript\n// Comprehensive recovery system\nclass RecoveryManager {\n constructor() {\n this.recoveryStrategies = new Map();\n this.setupDefaultStrategies();\n }\n\n setupDefaultStrategies() {\n // Network error recovery\n this.register('NetworkError', async (error, context) => {\n await this.waitForConnection();\n return this.reloadMicroApp(context.appName);\n });\n\n // Chunk load error recovery\n this.register('ChunkLoadError', async (error, context) => {\n // Clear webpack cache\n if (window.__webpack_require__ && window.__webpack_require__.cache) {\n delete window.__webpack_require__.cache[error.request];\n }\n \n // Reload with cache busting\n return this.reloadWithCacheBust(context.appName);\n });\n\n // Script error recovery\n this.register('TypeError', async (error, context) => {\n // Attempt to reload dependencies\n await this.reloadDependencies(context.appName);\n return this.remountMicroApp(context.appName);\n });\n\n // Memory error recovery\n this.register('RangeError', async (error, context) => {\n // Force garbage collection\n if (window.gc) window.gc();\n \n // Reduce memory footprint\n await this.reducememoryFootprint(context.appName);\n return this.reloadMicroApp(context.appName);\n });\n }\n\n register(errorType, strategy) {\n this.recoveryStrategies.set(errorType, strategy);\n }\n\n async recover(error, context) {\n const strategy = this.recoveryStrategies.get(error.name);\n \n if (strategy) {\n try {\n console.log(`Attempting recovery for ${error.name} in ${context.appName}`);\n const result = await strategy(error, context);\n console.log(`Recovery successful for ${context.appName}`);\n return result;\n } catch (recoveryError) {\n console.error(`Recovery failed for ${context.appName}:`, recoveryError);\n return this.fallbackRecovery(context);\n }\n }\n \n return this.fallbackRecovery(context);\n }\n\n async waitForConnection() {\n return new Promise((resolve) => {\n if (navigator.onLine) {\n resolve();\n } else {\n const handleOnline = () => {\n window.removeEventListener('online', handleOnline);\n resolve();\n };\n window.addEventListener('online', handleOnline);\n }\n });\n }\n\n async reloadMicroApp(appName) {\n // Unmount current instance\n try {\n await unmountMicroApp(appName);\n } catch (error) {\n console.warn(`Failed to unmount ${appName}:`, error);\n }\n\n // Reload the micro app\n const appConfig = getAppConfig(appName);\n return loadMicroApp(appConfig);\n }\n\n async reloadWithCacheBust(appName) {\n const appConfig = getAppConfig(appName);\n const cacheBustEntry = `${appConfig.entry}?t=${Date.now()}`;\n \n return loadMicroApp({\n ...appConfig,\n entry: cacheBustEntry\n });\n }\n\n async fallbackRecovery(context) {\n console.log(`Using fallback recovery for ${context.appName}`);\n \n // Show fallback UI\n showFallbackUI(context.appName);\n \n // Report recovery failure\n reportRecoveryFailure(context);\n \n return null;\n }\n}\n```\n\n### User-Initiated Recovery\n\n```jsx\n// User-controlled recovery interface\nconst RecoveryPanel = ({ appName, error, onRecover, onDismiss }) => {\n const [recovering, setRecovering] = useState(false);\n const [lastAttempt, setLastAttempt] = useState(null);\n\n const handleRecover = async (strategy) => {\n setRecovering(true);\n setLastAttempt(Date.now());\n \n try {\n await onRecover(strategy);\n } catch (error) {\n console.error('User-initiated recovery failed:', error);\n } finally {\n setRecovering(false);\n }\n };\n\n const recoveryOptions = [\n {\n key: 'reload',\n label: 'Reload Application',\n description: 'Restart the application from scratch',\n action: () => handleRecover('reload')\n },\n {\n key: 'reset',\n label: 'Reset to Default',\n description: 'Clear all data and reload',\n action: () => handleRecover('reset')\n },\n {\n key: 'safe-mode',\n label: 'Safe Mode',\n description: 'Load with minimal features',\n action: () => handleRecover('safe-mode')\n }\n ];\n\n return (\n
\n
\n

Recovery Options for {appName}

\n \n
\n \n
\n

Error: {error.message}

\n {lastAttempt && (\n

Last attempt: {new Date(lastAttempt).toLocaleTimeString()}

\n )}\n
\n \n
\n {recoveryOptions.map(option => (\n \n
{option.label}
\n
{option.description}
\n \n ))}\n
\n \n {recovering && (\n
\n
\n Attempting recovery...\n
\n )}\n
\n );\n};\n```\n\n## 🎯 Best Practices Summary\n\n### ✅ Error Handling Do's\n\n1. **Implement global error handlers** for comprehensive coverage\n2. **Use error boundaries** in each micro application\n3. **Provide meaningful error messages** for users\n4. **Implement graceful degradation** with fallback UIs\n5. **Monitor and track errors** systematically\n6. **Test error scenarios** during development\n7. **Implement automatic recovery** where possible\n8. **Clear error context** in reports\n9. **Handle network failures** gracefully\n10. **Provide user recovery options**\n\n### ❌ Error Handling Don'ts\n\n1. **Don't ignore errors** or fail silently\n2. **Don't show technical details** to end users\n3. **Don't retry indefinitely** without limits\n4. **Don't block the entire application** for one micro app error\n5. **Don't forget to clean up** after errors\n6. **Don't rely solely on automatic recovery**\n7. **Don't overwhelm users** with error messages\n8. **Don't forget about memory leaks** in error scenarios\n9. **Don't skip error testing** in production-like environments\n10. **Don't ignore user feedback** about errors\n\n### 🔄 Error Recovery Checklist\n\n```javascript\n// Comprehensive error handling checklist\nconst errorHandlingChecklist = {\n prevention: {\n validation: '✓ Input validation implemented',\n typeChecking: '✓ TypeScript or PropTypes used',\n testing: '✓ Error scenarios tested',\n monitoring: '✓ Health checks in place'\n },\n \n detection: {\n globalHandlers: '✓ Global error handlers set up',\n boundaries: '✓ Error boundaries implemented',\n logging: '✓ Comprehensive error logging',\n alerting: '✓ Real-time error alerts'\n },\n \n recovery: {\n gracefulDegradation: '✓ Fallback UIs implemented',\n automaticRecovery: '✓ Auto-recovery strategies',\n userRecovery: '✓ User-initiated recovery options',\n resourceCleanup: '✓ Proper cleanup on errors'\n },\n \n learning: {\n errorTracking: '✓ Error analytics in place',\n trendAnalysis: '✓ Error trend monitoring',\n rootCauseAnalysis: '✓ RCA process defined',\n continuousImprovement: '✓ Regular error review meetings'\n }\n};\n```\n\n## 🔗 Related Documentation\n\n- [Performance Optimization](/cookbook/performance) - Error impact on performance\n- [Debugging](/cookbook/debugging) - Error debugging techniques\n- [Style Isolation](/cookbook/style-isolation) - CSS error handling\n- [Configuration](/api/configuration) - Error-related configurations " }, { "path": "docs/cookbook/index.md", "content": "# Best Practices\n\nThis section contains practical guides and best practices for building production-ready micro-frontend applications with qiankun. These guides are based on real-world experience and common challenges faced when implementing micro-frontend architectures.\n\n## 🎯 Overview\n\nBuilding micro-frontends requires careful consideration of various aspects including architecture design, performance optimization, development workflow, and deployment strategies. These guides will help you avoid common pitfalls and implement robust solutions.\n\n## 📚 Available Guides\n\n### 🎨 [Style Isolation](/cookbook/style-isolation)\n\nLearn how to prevent CSS conflicts between micro applications and implement effective style isolation strategies.\n\n**What you'll learn:**\n- CSS isolation techniques\n- Shadow DOM implementation\n- CSS scoping strategies\n- Runtime style conflict resolution\n- Best practices for component libraries\n\n### ⚡ [Performance Optimization](/cookbook/performance)\n\nOptimize your micro-frontend applications for better load times and runtime performance.\n\n**What you'll learn:**\n- Resource loading optimization\n- Bundle splitting strategies\n- Caching mechanisms\n- Lazy loading techniques\n- Performance monitoring\n\n### 🛠️ [Error Handling](/cookbook/error-handling)\n\nImplement robust error handling and recovery mechanisms for micro-frontend applications.\n\n**What you'll learn:**\n- Error boundaries implementation\n- Graceful degradation strategies\n- Error monitoring and reporting\n- Recovery mechanisms\n- User experience considerations\n\n### 🔍 [Debugging & Development](/cookbook/debugging)\n\nMaster debugging techniques and development workflows for micro-frontend applications.\n\n**What you'll learn:**\n- Development environment setup\n- Debugging tools and techniques\n- Hot reload configuration\n- Cross-application debugging\n- Production debugging strategies\n\n### 🚀 [Deployment Strategies](/cookbook/deployment)\n\nLearn deployment patterns and CI/CD strategies for micro-frontend applications.\n\n**What you'll learn:**\n- Independent deployment workflows\n- Version management\n- Rollback strategies\n- Environment configuration\n- Zero-downtime deployments\n\n### 🔄 [State Management](/cookbook/state-management)\n\nImplement effective state management across micro applications.\n\n**What you'll learn:**\n- Cross-application state sharing\n- Event-driven communication\n- State synchronization\n- Data flow patterns\n- Store management\n\n### 🌐 [Routing & Navigation](/cookbook/routing)\n\nDesign and implement navigation patterns for micro-frontend applications.\n\n**What you'll learn:**\n- Route configuration strategies\n- Deep linking support\n- Navigation guards\n- History management\n- SEO considerations\n\n### 🔒 [Security](/cookbook/security)\n\nImplement security best practices for micro-frontend architectures.\n\n**What you'll learn:**\n- Content Security Policy (CSP)\n- Cross-origin resource sharing (CORS)\n- Authentication and authorization\n- Secure communication patterns\n- Vulnerability prevention\n\n### 🧪 [Testing Strategies](/cookbook/testing)\n\nDevelop comprehensive testing strategies for micro-frontend applications.\n\n**What you'll learn:**\n- Unit testing micro applications\n- Integration testing strategies\n- End-to-end testing\n- Visual regression testing\n- Performance testing\n\n### 📊 [Monitoring & Analytics](/cookbook/monitoring)\n\nImplement monitoring and analytics for micro-frontend applications.\n\n**What you'll learn:**\n- Performance monitoring\n- Error tracking\n- User analytics\n- Application health checks\n- Business metrics\n\n## 🎯 Getting Started\n\nIf you're new to qiankun or micro-frontends, we recommend starting with these guides in order:\n\n1. **[Style Isolation](/cookbook/style-isolation)** - Essential for preventing CSS conflicts\n2. **[Error Handling](/cookbook/error-handling)** - Critical for production stability\n3. **[Performance Optimization](/cookbook/performance)** - Important for user experience\n4. **[Debugging & Development](/cookbook/debugging)** - Improves development productivity\n\n## 🏗️ Common Patterns\n\n### Micro-Frontend Architecture Patterns\n\n```mermaid\ngraph TB\n A[Main Application] --> B[User Management]\n A --> C[Product Catalog]\n A --> D[Shopping Cart]\n A --> E[Order Processing]\n \n B --> F[User Service]\n C --> G[Product Service]\n D --> H[Cart Service]\n E --> I[Order Service]\n \n F --> J[User Database]\n G --> K[Product Database]\n H --> L[Session Storage]\n I --> M[Order Database]\n```\n\n### Communication Patterns\n\n```mermaid\nsequenceDiagram\n participant M as Main App\n participant A as Micro App A\n participant B as Micro App B\n participant S as Shared Store\n \n M->>A: Load & Mount\n A->>S: Subscribe to Events\n M->>B: Load & Mount\n B->>S: Subscribe to Events\n \n A->>S: Emit Event\n S->>B: Notify Event\n B->>S: Update State\n S->>A: Broadcast Update\n```\n\n## 🎪 Real-World Examples\n\n### E-commerce Platform\n\nA typical e-commerce platform might be structured as:\n\n- **Main Application**: Navigation, layout, user session\n- **Product Catalog**: Browse and search products\n- **Shopping Cart**: Manage cart items and checkout\n- **User Account**: Profile management and order history\n- **Admin Panel**: Content management and analytics\n\n### Enterprise Dashboard\n\nAn enterprise dashboard might include:\n\n- **Main Shell**: Authentication and navigation\n- **Analytics Module**: Business intelligence and reporting\n- **User Management**: Role and permission management\n- **Content Management**: Dynamic content editing\n- **Settings Module**: System configuration\n\n## ⚠️ Common Pitfalls\n\n### 1. Over-Engineering\n\n**Problem**: Creating too many micro applications for small features.\n\n**Solution**: Start with a monolith and extract micro applications when teams or domains naturally separate.\n\n### 2. Shared Dependencies\n\n**Problem**: Micro applications sharing dependencies causing version conflicts.\n\n**Solution**: Use proper bundling strategies and consider module federation for shared libraries.\n\n### 3. Performance Issues\n\n**Problem**: Multiple micro applications loading simultaneously causing performance degradation.\n\n**Solution**: Implement lazy loading, proper caching, and resource optimization.\n\n### 4. Testing Complexity\n\n**Problem**: Testing micro applications in isolation doesn't catch integration issues.\n\n**Solution**: Implement comprehensive integration testing alongside unit tests.\n\n## 🔧 Development Workflow\n\n### Recommended Development Flow\n\n1. **Design Phase**\n - Define application boundaries\n - Plan communication patterns\n - Design shared interfaces\n\n2. **Development Phase**\n - Set up development environment\n - Implement micro applications\n - Configure build and deployment\n\n3. **Testing Phase**\n - Unit test individual applications\n - Integration test the complete system\n - Performance and security testing\n\n4. **Deployment Phase**\n - Deploy applications independently\n - Monitor application health\n - Implement rollback strategies\n\n### Team Organization\n\n```mermaid\ngraph LR\n A[Platform Team] --> B[Shared Infrastructure]\n A --> C[Main Application]\n \n D[Feature Team 1] --> E[Micro App 1]\n F[Feature Team 2] --> G[Micro App 2]\n H[Feature Team 3] --> I[Micro App 3]\n \n B --> E\n B --> G\n B --> I\n```\n\n## 📖 Further Reading\n\n- [Micro Frontends Architecture](https://micro-frontends.org/)\n- [Module Federation](https://webpack.js.org/concepts/module-federation/)\n- [Single-SPA Documentation](https://single-spa.js.org/)\n- [qiankun GitHub Repository](https://github.com/umijs/qiankun)\n\n## 🤝 Contributing\n\nHave a pattern or practice you'd like to share? Contributions to the cookbook are welcome! Please follow our [contribution guidelines](https://github.com/umijs/qiankun/blob/master/CONTRIBUTING.md).\n\n## 🔗 Related Documentation\n\n- [API Reference](/api/) - Complete API documentation\n- [Quick Start Guide](/guide/quick-start) - Get started with qiankun\n- [Ecosystem](/ecosystem/) - UI bindings and tools " }, { "path": "docs/cookbook/performance.md", "content": "# Performance Optimization\n\nPerformance is crucial for micro-frontend applications. With multiple applications loading and running simultaneously, it's essential to optimize resource loading, runtime performance, and user experience. This guide covers comprehensive strategies for optimizing qiankun-based micro-frontend applications.\n\n## 🎯 Performance Overview\n\n### Common Performance Challenges\n\nMicro-frontend architectures introduce unique performance considerations:\n\n- **Multiple Bundle Loading**: Each micro app loads its own JavaScript and CSS\n- **Resource Duplication**: Shared dependencies loaded multiple times\n- **Runtime Overhead**: Multiple application instances running simultaneously\n- **Network Latency**: Additional HTTP requests for each micro app\n- **Memory Usage**: Increased memory consumption from multiple apps\n\n### Performance Metrics to Monitor\n\n```javascript\n// Key metrics for micro-frontend performance\nconst performanceMetrics = {\n // Loading Performance\n timeToFirstByte: 'TTFB',\n firstContentfulPaint: 'FCP',\n largestContentfulPaint: 'LCP',\n \n // Interactivity\n firstInputDelay: 'FID',\n timeToInteractive: 'TTI',\n \n // Micro-frontend Specific\n microAppLoadTime: 'Custom metric',\n microAppMountTime: 'Custom metric',\n totalBundleSize: 'Custom metric'\n};\n```\n\n## 🚀 Resource Loading Optimization\n\n### Prefetching Strategies\n\nqiankun provides several prefetching options to improve loading performance:\n\n#### Basic Prefetching\n\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n prefetch: true // Enable default prefetching\n});\n```\n\n#### Selective Prefetching\n\n```javascript\nstart({\n prefetch: ['critical-app-1', 'critical-app-2'] // Only prefetch specific apps\n});\n```\n\n#### Smart Prefetching\n\n```javascript\nstart({\n prefetch: (apps) => {\n // Custom prefetch logic based on user behavior, time, or network conditions\n const now = new Date().getHours();\n const isBusinessHours = now >= 9 && now <= 17;\n \n if (isBusinessHours) {\n return {\n criticalAppNames: ['dashboard', 'user-management'],\n minorAppsName: ['analytics']\n };\n }\n \n return {\n criticalAppNames: ['dashboard'],\n minorAppsName: []\n };\n }\n});\n```\n\n#### Network-Aware Prefetching\n\n```javascript\n// Advanced prefetching based on network conditions\nconst networkAwarePrefetch = (apps) => {\n const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;\n \n if (!connection) {\n // Default behavior for unknown connection\n return { criticalAppNames: apps.slice(0, 2), minorAppsName: [] };\n }\n \n const effectiveType = connection.effectiveType;\n const saveData = connection.saveData;\n \n if (saveData || effectiveType === 'slow-2g' || effectiveType === '2g') {\n // Minimal prefetching for slow connections\n return { criticalAppNames: [], minorAppsName: [] };\n }\n \n if (effectiveType === '3g') {\n // Moderate prefetching for 3G\n return { criticalAppNames: apps.slice(0, 1), minorAppsName: [] };\n }\n \n // Aggressive prefetching for 4G and above\n return {\n criticalAppNames: apps.slice(0, 3),\n minorAppsName: apps.slice(3)\n };\n};\n\nstart({\n prefetch: networkAwarePrefetch\n});\n```\n\n### Lazy Loading\n\n#### Route-Based Lazy Loading\n\n```javascript\n// Only load micro apps when their routes are accessed\nregisterMicroApps([\n {\n name: 'user-management',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/users',\n // App will only load when /users route is accessed\n },\n {\n name: 'analytics',\n entry: '//localhost:8081',\n container: '#container',\n activeRule: '/analytics',\n // Loaded on demand\n }\n]);\n```\n\n#### Conditional Loading\n\n```javascript\n// Load micro apps based on user permissions or features\nconst userPermissions = getCurrentUserPermissions();\n\nconst microApps = [\n {\n name: 'dashboard',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/dashboard'\n }\n];\n\n// Conditionally add admin app\nif (userPermissions.includes('admin')) {\n microApps.push({\n name: 'admin-panel',\n entry: '//localhost:8082',\n container: '#container',\n activeRule: '/admin'\n });\n}\n\nregisterMicroApps(microApps);\n```\n\n#### Intersection Observer for Lazy Loading\n\n```javascript\n// Load micro apps when they come into viewport\nconst observerCallback = (entries, observer) => {\n entries.forEach(entry => {\n if (entry.isIntersecting) {\n const appName = entry.target.dataset.app;\n loadMicroApp({\n name: appName,\n entry: entry.target.dataset.entry,\n container: entry.target\n });\n observer.unobserve(entry.target);\n }\n });\n};\n\nconst observer = new IntersectionObserver(observerCallback, {\n threshold: 0.1\n});\n\ndocument.querySelectorAll('[data-lazy-app]').forEach(el => {\n observer.observe(el);\n});\n```\n\n## 📦 Bundle Optimization\n\n### Code Splitting\n\n#### Micro App Level Splitting\n\n```javascript\n// webpack.config.js for micro applications\nmodule.exports = {\n optimization: {\n splitChunks: {\n chunks: 'all',\n cacheGroups: {\n vendor: {\n test: /[\\\\/]node_modules[\\\\/]/,\n name: 'vendors',\n chunks: 'all',\n priority: 10\n },\n common: {\n name: 'common',\n minChunks: 2,\n chunks: 'all',\n priority: 5\n }\n }\n }\n }\n};\n```\n\n#### Dynamic Imports in Micro Apps\n\n```javascript\n// React component with dynamic import\nimport React, { Suspense, lazy } from 'react';\n\nconst HeavyComponent = lazy(() => import('./HeavyComponent'));\n\nfunction MyMicroApp() {\n return (\n
\n

Micro App

\n Loading heavy component...
}>\n \n \n
\n );\n}\n```\n\n### Shared Dependencies\n\n#### External Dependencies\n\n```javascript\n// webpack.config.js - Externalize shared libraries\nmodule.exports = {\n externals: {\n 'react': 'React',\n 'react-dom': 'ReactDOM',\n 'lodash': '_',\n 'moment': 'moment'\n }\n};\n```\n\n#### Module Federation\n\n```javascript\n// webpack.config.js for main application\nconst ModuleFederationPlugin = require('@module-federation/webpack');\n\nmodule.exports = {\n plugins: [\n new ModuleFederationPlugin({\n name: 'shell',\n shared: {\n react: {\n singleton: true,\n requiredVersion: '^18.0.0'\n },\n 'react-dom': {\n singleton: true,\n requiredVersion: '^18.0.0'\n }\n }\n })\n ]\n};\n\n// webpack.config.js for micro application\nmodule.exports = {\n plugins: [\n new ModuleFederationPlugin({\n name: 'microApp',\n shared: {\n react: {\n singleton: true,\n requiredVersion: '^18.0.0'\n },\n 'react-dom': {\n singleton: true,\n requiredVersion: '^18.0.0'\n }\n }\n })\n ]\n};\n```\n\n## 🏎️ Runtime Performance\n\n### Memory Management\n\n#### Cleanup on Unmount\n\n```javascript\n// Proper cleanup in lifecycle hooks\nconst lifeCycles = {\n async afterUnmount(app) {\n // Clear timers\n if (window.microAppTimers) {\n window.microAppTimers.forEach(timer => clearInterval(timer));\n window.microAppTimers = [];\n }\n \n // Remove event listeners\n if (window.microAppListeners) {\n window.microAppListeners.forEach(({ element, event, handler }) => {\n element.removeEventListener(event, handler);\n });\n window.microAppListeners = [];\n }\n \n // Clear caches\n if (window.microAppCache) {\n window.microAppCache.clear();\n }\n \n // Force garbage collection (if available)\n if (window.gc) {\n window.gc();\n }\n }\n};\n```\n\n#### Memory Leak Detection\n\n```javascript\n// Monitor memory usage\nconst memoryMonitor = {\n baseline: null,\n \n measureBaseline() {\n this.baseline = performance.memory ? {\n usedJSHeapSize: performance.memory.usedJSHeapSize,\n totalJSHeapSize: performance.memory.totalJSHeapSize\n } : null;\n },\n \n checkForLeaks(appName) {\n if (!performance.memory || !this.baseline) return;\n \n const current = {\n usedJSHeapSize: performance.memory.usedJSHeapSize,\n totalJSHeapSize: performance.memory.totalJSHeapSize\n };\n \n const growth = current.usedJSHeapSize - this.baseline.usedJSHeapSize;\n const growthMB = growth / (1024 * 1024);\n \n if (growthMB > 50) { // Alert if memory grew by more than 50MB\n console.warn(`Potential memory leak in ${appName}: ${growthMB.toFixed(2)}MB growth`);\n }\n }\n};\n```\n\n### Virtual DOM Optimization\n\n#### React Optimization\n\n```javascript\n// Optimize React micro apps\nimport React, { memo, useMemo, useCallback } from 'react';\n\nconst OptimizedComponent = memo(({ data, onUpdate }) => {\n // Memoize expensive calculations\n const processedData = useMemo(() => {\n return data.map(item => ({\n ...item,\n calculated: expensiveCalculation(item)\n }));\n }, [data]);\n \n // Memoize event handlers\n const handleUpdate = useCallback((id, newValue) => {\n onUpdate(id, newValue);\n }, [onUpdate]);\n \n return (\n
\n {processedData.map(item => (\n \n ))}\n
\n );\n});\n```\n\n#### Vue Optimization\n\n```vue\n\n\n\n```\n\n## 🗄️ Caching Strategies\n\n### HTTP Caching\n\n#### Micro App Assets\n\n```javascript\n// Configure caching headers for micro app assets\n// nginx.conf\nserver {\n location ~* \\.(js|css|png|jpg|jpeg|gif|svg|woff|woff2)$ {\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n add_header Vary \"Accept-Encoding\";\n }\n \n location /api/ {\n expires -1;\n add_header Cache-Control \"no-cache, no-store, must-revalidate\";\n }\n}\n```\n\n#### Service Worker Caching\n\n```javascript\n// sw.js - Service worker for micro app caching\nconst CACHE_NAME = 'micro-app-cache-v1';\nconst MICRO_APP_URLS = [\n '/micro-app-1/static/js/main.js',\n '/micro-app-1/static/css/main.css',\n '/micro-app-2/static/js/main.js',\n '/micro-app-2/static/css/main.css'\n];\n\nself.addEventListener('install', event => {\n event.waitUntil(\n caches.open(CACHE_NAME)\n .then(cache => cache.addAll(MICRO_APP_URLS))\n );\n});\n\nself.addEventListener('fetch', event => {\n if (MICRO_APP_URLS.some(url => event.request.url.includes(url))) {\n event.respondWith(\n caches.match(event.request)\n .then(response => response || fetch(event.request))\n );\n }\n});\n```\n\n### Application-Level Caching\n\n#### Intelligent App Caching\n\n```javascript\n// Cache micro app instances for faster remounting\nclass MicroAppCache {\n constructor() {\n this.cache = new Map();\n this.maxSize = 5;\n }\n \n set(appName, appInstance) {\n if (this.cache.size >= this.maxSize) {\n // Remove least recently used app\n const firstKey = this.cache.keys().next().value;\n this.cache.delete(firstKey);\n }\n \n this.cache.set(appName, {\n instance: appInstance,\n timestamp: Date.now()\n });\n }\n \n get(appName) {\n const cached = this.cache.get(appName);\n if (cached) {\n // Move to end (mark as recently used)\n this.cache.delete(appName);\n this.cache.set(appName, cached);\n return cached.instance;\n }\n return null;\n }\n \n has(appName) {\n return this.cache.has(appName);\n }\n \n clear() {\n this.cache.clear();\n }\n}\n\nconst appCache = new MicroAppCache();\n```\n\n## ⚡ Network Optimization\n\n### Connection Optimizations\n\n#### HTTP/2 Push\n\n```javascript\n// Express.js server with HTTP/2 push for micro app assets\nconst express = require('express');\nconst spdy = require('spdy');\n\nconst app = express();\n\napp.get('/main-app', (req, res) => {\n // Push critical micro app resources\n res.push('/micro-app-1/static/js/main.js');\n res.push('/micro-app-1/static/css/main.css');\n \n res.sendFile(__dirname + '/index.html');\n});\n\nconst server = spdy.createServer(options, app);\n```\n\n#### Resource Hints\n\n```html\n\n\n \n \n \n \n \n \n \n \n \n \n\n```\n\n### CDN Strategy\n\n#### Multi-CDN Setup\n\n```javascript\n// Intelligent CDN selection based on performance\nclass CDNManager {\n constructor() {\n this.cdns = [\n 'https://cdn1.example.com',\n 'https://cdn2.example.com',\n 'https://cdn3.example.com'\n ];\n this.performanceCache = new Map();\n }\n \n async getBestCDN() {\n if (this.performanceCache.size === 0) {\n await this.measureCDNPerformance();\n }\n \n // Return fastest CDN\n return [...this.performanceCache.entries()]\n .sort((a, b) => a[1] - b[1])[0][0];\n }\n \n async measureCDNPerformance() {\n const promises = this.cdns.map(async (cdn) => {\n const start = performance.now();\n try {\n await fetch(`${cdn}/health-check`);\n const latency = performance.now() - start;\n this.performanceCache.set(cdn, latency);\n } catch (error) {\n this.performanceCache.set(cdn, Infinity);\n }\n });\n \n await Promise.all(promises);\n }\n}\n```\n\n## 📊 Performance Monitoring\n\n### Real-Time Metrics\n\n#### Performance Observer\n\n```javascript\n// Monitor micro app loading performance\nclass MicroAppPerformanceMonitor {\n constructor() {\n this.metrics = new Map();\n this.initObservers();\n }\n \n initObservers() {\n // Monitor loading performance\n if ('PerformanceObserver' in window) {\n const loadObserver = new PerformanceObserver((list) => {\n for (const entry of list.getEntries()) {\n if (entry.name.includes('micro-app')) {\n this.recordLoadTime(entry);\n }\n }\n });\n \n loadObserver.observe({ entryTypes: ['navigation', 'resource'] });\n \n // Monitor layout shifts\n const cls Observer = new PerformanceObserver((list) => {\n for (const entry of list.getEntries()) {\n if (!entry.hadRecentInput) {\n this.recordLayoutShift(entry);\n }\n }\n });\n \n clsObserver.observe({ entryTypes: ['layout-shift'] });\n }\n }\n \n recordLoadTime(entry) {\n const appName = this.extractAppName(entry.name);\n this.metrics.set(`${appName}_load_time`, entry.loadEnd - entry.loadStart);\n }\n \n recordLayoutShift(entry) {\n const currentCLS = this.metrics.get('cumulative_layout_shift') || 0;\n this.metrics.set('cumulative_layout_shift', currentCLS + entry.value);\n }\n \n getMetrics() {\n return Object.fromEntries(this.metrics);\n }\n}\n```\n\n#### Custom Timing API\n\n```javascript\n// Custom timing for micro app lifecycle\nclass MicroAppTiming {\n static mark(name) {\n performance.mark(name);\n }\n \n static measure(name, startMark, endMark) {\n performance.measure(name, startMark, endMark);\n \n // Send to analytics\n const measure = performance.getEntriesByName(name)[0];\n this.sendToAnalytics({\n metric: name,\n duration: measure.duration,\n timestamp: Date.now()\n });\n }\n \n static sendToAnalytics(data) {\n // Send to your analytics service\n fetch('/api/analytics/performance', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(data)\n });\n }\n}\n\n// Usage in micro app lifecycle\nconst lifeCycles = {\n async beforeLoad(app) {\n MicroAppTiming.mark(`${app.name}_load_start`);\n },\n \n async afterMount(app) {\n MicroAppTiming.mark(`${app.name}_mount_end`);\n MicroAppTiming.measure(\n `${app.name}_total_time`,\n `${app.name}_load_start`,\n `${app.name}_mount_end`\n );\n }\n};\n```\n\n### Performance Analytics\n\n#### User Experience Metrics\n\n```javascript\n// Track user experience metrics for micro apps\nclass UXMetrics {\n constructor() {\n this.metrics = {};\n this.initTracking();\n }\n \n initTracking() {\n // Time to Interactive for micro apps\n this.trackTimeToInteractive();\n \n // User engagement metrics\n this.trackUserEngagement();\n \n // Error rates\n this.trackErrorRates();\n }\n \n trackTimeToInteractive() {\n const observer = new PerformanceObserver((list) => {\n for (const entry of list.getEntries()) {\n if (entry.entryType === 'measure' && entry.name.includes('tti')) {\n this.metrics.timeToInteractive = entry.duration;\n }\n }\n });\n \n observer.observe({ entryTypes: ['measure'] });\n }\n \n trackUserEngagement() {\n let interactions = 0;\n \n ['click', 'scroll', 'keydown'].forEach(event => {\n document.addEventListener(event, () => {\n interactions++;\n this.metrics.interactions = interactions;\n });\n });\n }\n \n trackErrorRates() {\n window.addEventListener('error', (event) => {\n const appName = this.getAppFromError(event);\n this.metrics.errors = this.metrics.errors || {};\n this.metrics.errors[appName] = (this.metrics.errors[appName] || 0) + 1;\n });\n }\n}\n```\n\n## 🎨 UI/UX Performance\n\n### Loading States\n\n#### Skeleton Loading\n\n```jsx\n// React skeleton component for micro app loading\nimport React from 'react';\n\nconst MicroAppSkeleton = ({ appName }) => {\n return (\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n );\n};\n\n// Usage with micro app loading\nfunction MicroAppContainer({ appName, entry }) {\n const [loading, setLoading] = useState(true);\n const [app, setApp] = useState(null);\n \n useEffect(() => {\n loadMicroApp({\n name: appName,\n entry,\n container: '#micro-app-container'\n }).then(() => {\n setLoading(false);\n });\n }, [appName, entry]);\n \n if (loading) {\n return ;\n }\n \n return
;\n}\n```\n\n#### Progressive Enhancement\n\n```javascript\n// Progressive enhancement for micro apps\nclass ProgressiveLoader {\n constructor(container, config) {\n this.container = container;\n this.config = config;\n this.loadingStates = ['initial', 'skeleton', 'partial', 'complete'];\n this.currentState = 'initial';\n }\n \n async load() {\n // Show initial loading state\n this.setState('skeleton');\n this.renderSkeleton();\n \n try {\n // Load critical CSS first\n await this.loadCriticalCSS();\n \n // Show partial content\n this.setState('partial');\n await this.loadCriticalJS();\n \n // Load remaining resources\n await this.loadRemainingAssets();\n \n // Complete loading\n this.setState('complete');\n this.mountApp();\n \n } catch (error) {\n this.handleLoadError(error);\n }\n }\n \n renderSkeleton() {\n this.container.innerHTML = this.config.skeletonHTML;\n }\n \n async loadCriticalCSS() {\n const link = document.createElement('link');\n link.rel = 'stylesheet';\n link.href = `${this.config.entry}/critical.css`;\n \n return new Promise((resolve, reject) => {\n link.onload = resolve;\n link.onerror = reject;\n document.head.appendChild(link);\n });\n }\n}\n```\n\n### Animation Performance\n\n#### Hardware Acceleration\n\n```css\n/* Optimize animations for micro app transitions */\n.micro-app-transition {\n /* Use transform instead of changing layout properties */\n transform: translateX(0);\n transition: transform 0.3s ease-out;\n \n /* Enable hardware acceleration */\n will-change: transform;\n \n /* Use GPU compositing */\n transform: translateZ(0);\n}\n\n.micro-app-enter {\n transform: translateX(100%);\n}\n\n.micro-app-enter-active {\n transform: translateX(0);\n}\n\n.micro-app-exit {\n transform: translateX(0);\n}\n\n.micro-app-exit-active {\n transform: translateX(-100%);\n}\n```\n\n#### Intersection Observer for Animations\n\n```javascript\n// Efficient animation triggering using Intersection Observer\nclass AnimationManager {\n constructor() {\n this.observer = new IntersectionObserver(\n this.handleIntersection.bind(this),\n { threshold: 0.1 }\n );\n }\n \n observe(element) {\n this.observer.observe(element);\n }\n \n handleIntersection(entries) {\n entries.forEach(entry => {\n if (entry.isIntersecting) {\n this.triggerAnimation(entry.target);\n this.observer.unobserve(entry.target);\n }\n });\n }\n \n triggerAnimation(element) {\n // Use CSS classes for hardware-accelerated animations\n element.classList.add('animate-in');\n \n // Or use Web Animations API for complex animations\n element.animate([\n { opacity: 0, transform: 'translateY(20px)' },\n { opacity: 1, transform: 'translateY(0)' }\n ], {\n duration: 300,\n easing: 'ease-out'\n });\n }\n}\n```\n\n## 📱 Mobile Performance\n\n### Mobile-Specific Optimizations\n\n#### Touch Event Optimization\n\n```javascript\n// Optimize touch events for mobile micro apps\nclass TouchOptimizer {\n constructor() {\n this.setupPassiveListeners();\n this.optimizeTouchHandling();\n }\n \n setupPassiveListeners() {\n // Use passive listeners for scroll performance\n document.addEventListener('touchstart', this.handleTouchStart, { passive: true });\n document.addEventListener('touchmove', this.handleTouchMove, { passive: true });\n }\n \n optimizeTouchHandling() {\n // Debounce touch events\n let touchTimeout;\n \n document.addEventListener('touchend', () => {\n clearTimeout(touchTimeout);\n touchTimeout = setTimeout(() => {\n // Handle touch end with delay to prevent accidental double taps\n }, 300);\n });\n }\n \n handleTouchStart(event) {\n // Minimal processing in touch start\n }\n \n handleTouchMove(event) {\n // Use requestAnimationFrame for smooth scrolling\n requestAnimationFrame(() => {\n // Handle touch move\n });\n }\n}\n```\n\n#### Viewport Management\n\n```javascript\n// Optimize viewport for different micro apps\nclass ViewportManager {\n constructor() {\n this.defaultViewport = 'width=device-width, initial-scale=1.0';\n this.viewportMeta = document.querySelector('meta[name=\"viewport\"]');\n }\n \n setViewportForApp(appName) {\n const appViewports = {\n 'mobile-first-app': 'width=device-width, initial-scale=1.0, user-scalable=no',\n 'desktop-app': 'width=1024, initial-scale=0.5',\n 'responsive-app': 'width=device-width, initial-scale=1.0'\n };\n \n const viewport = appViewports[appName] || this.defaultViewport;\n this.viewportMeta.setAttribute('content', viewport);\n }\n \n resetViewport() {\n this.viewportMeta.setAttribute('content', this.defaultViewport);\n }\n}\n```\n\n## 🔧 Development vs Production Optimization\n\n### Environment-Specific Configurations\n\n#### Development Optimizations\n\n```javascript\n// webpack.config.dev.js for micro apps\nmodule.exports = {\n mode: 'development',\n \n optimization: {\n // Disable minification for faster builds\n minimize: false,\n \n // Split chunks for better debugging\n splitChunks: {\n chunks: 'all',\n cacheGroups: {\n vendor: {\n test: /[\\\\/]node_modules[\\\\/]/,\n name: 'vendors',\n chunks: 'all'\n }\n }\n }\n },\n \n devServer: {\n // Enable hot reloading\n hot: true,\n \n // Optimize for development\n liveReload: true,\n \n // CORS for micro app communication\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n};\n```\n\n#### Production Optimizations\n\n```javascript\n// webpack.config.prod.js for micro apps\nconst CompressionPlugin = require('compression-webpack-plugin');\nconst { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');\n\nmodule.exports = {\n mode: 'production',\n \n optimization: {\n // Enable all optimizations\n minimize: true,\n sideEffects: false,\n \n // Advanced chunk splitting\n splitChunks: {\n chunks: 'all',\n maxSize: 244000,\n cacheGroups: {\n vendor: {\n test: /[\\\\/]node_modules[\\\\/]/,\n name: 'vendors',\n chunks: 'all',\n priority: 10\n },\n common: {\n name: 'common',\n minChunks: 2,\n chunks: 'all',\n priority: 5\n }\n }\n }\n },\n \n plugins: [\n // Gzip compression\n new CompressionPlugin({\n algorithm: 'gzip',\n test: /\\.(js|css|html|svg)$/,\n threshold: 8192,\n minRatio: 0.8\n }),\n \n // Bundle analysis (optional)\n new BundleAnalyzerPlugin({\n analyzerMode: 'static',\n openAnalyzer: false\n })\n ]\n};\n```\n\n## 🎯 Performance Best Practices Summary\n\n### ✅ Do's\n\n1. **Implement prefetching** for critical micro apps\n2. **Use code splitting** within micro applications\n3. **Leverage caching** at multiple levels\n4. **Monitor performance** continuously\n5. **Optimize for mobile** experiences\n6. **Use lazy loading** for non-critical features\n7. **Implement proper cleanup** in unmount hooks\n8. **Share dependencies** efficiently\n9. **Use service workers** for caching\n10. **Optimize animations** with hardware acceleration\n\n### ❌ Don'ts\n\n1. **Don't load all micro apps** at once\n2. **Don't ignore bundle sizes** \n3. **Don't duplicate large dependencies**\n4. **Don't forget memory cleanup**\n5. **Don't block the main thread**\n6. **Don't ignore mobile performance**\n7. **Don't over-prefetch** on slow connections\n8. **Don't use synchronous operations**\n9. **Don't ignore error boundaries**\n10. **Don't skip performance monitoring**\n\n### 📊 Performance Checklist\n\n```javascript\n// Performance audit checklist for micro apps\nconst performanceChecklist = {\n loading: {\n prefetchStrategy: '✓ Implemented smart prefetching',\n bundleSize: '✓ Bundles under 250KB gzipped',\n codesplitting: '✓ Critical path separated',\n caching: '✓ Aggressive caching enabled'\n },\n \n runtime: {\n memoryLeaks: '✓ Cleanup implemented',\n animationPerf: '✓ Hardware acceleration used',\n eventOptimization: '✓ Passive listeners used',\n lazyLoading: '✓ Non-critical features lazy loaded'\n },\n \n monitoring: {\n coreWebVitals: '✓ LCP, FID, CLS monitored',\n customMetrics: '✓ App-specific metrics tracked',\n errorTracking: '✓ Performance errors logged',\n analytics: '✓ User experience measured'\n }\n};\n```\n\n## 🔗 Related Documentation\n\n- [Style Isolation](/cookbook/style-isolation) - CSS performance and isolation\n- [Error Handling](/cookbook/error-handling) - Performance impact of errors\n- [Configuration](/api/configuration) - Performance-related configurations\n- [Debugging](/cookbook/debugging) - Performance debugging techniques " }, { "path": "docs/cookbook/style-isolation.md", "content": "# Style Isolation\n\nStyle isolation is one of the most critical aspects of micro-frontend architecture. When multiple applications run in the same browser context, CSS conflicts can cause visual inconsistencies and broken layouts. This guide covers various strategies to achieve effective style isolation in qiankun applications.\n\n## 🎯 Understanding the Problem\n\n### CSS Conflicts in Micro-Frontends\n\nWhen multiple micro applications are loaded into the same page, they share the same global CSS namespace. This can lead to:\n\n- **Style Overriding**: Later-loaded applications overriding earlier styles\n- **Selector Conflicts**: Same class names causing unintended styling\n- **Global Pollution**: Micro apps affecting main application styles\n- **Layout Breaks**: Unexpected layout changes due to conflicting styles\n\n### Example of a CSS Conflict\n\n```css\n/* Main Application */\n.button {\n background: blue;\n padding: 10px;\n}\n\n/* Micro Application */\n.button {\n background: red; /* This will override main app styles! */\n border: none;\n}\n```\n\n## 🛡️ qiankun's Built-in Style Isolation\n\nqiankun provides several built-in style isolation mechanisms that you can enable through configuration.\n\n### Strict Style Isolation\n\nThe most robust isolation method using Shadow DOM:\n\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n sandbox: {\n strictStyleIsolation: true\n }\n});\n```\n\n**How it works:**\n- Creates a Shadow DOM for each micro application\n- Completely isolates styles between applications\n- Prevents any style leakage\n\n**Pros:**\n- Complete style isolation\n- No CSS conflicts possible\n- Easy to implement\n\n**Cons:**\n- Some third-party libraries may not work properly\n- Debugging can be more complex\n- Performance overhead for large applications\n\n### Experimental Style Isolation\n\nA less intrusive approach using CSS scoping:\n\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n sandbox: {\n experimentalStyleIsolation: true\n }\n});\n```\n\n**How it works:**\n- Adds unique prefixes to CSS selectors\n- Scopes styles to micro application containers\n- Maintains DOM structure\n\n**Pros:**\n- Better third-party library compatibility\n- Easier debugging\n- Less performance overhead\n\n**Cons:**\n- Not as robust as strict isolation\n- Some edge cases may still cause conflicts\n\n## 🎨 CSS-in-JS Solutions\n\nCSS-in-JS libraries provide natural style isolation by generating unique class names.\n\n### Styled Components\n\n```jsx\n// Micro Application using Styled Components\nimport styled from 'styled-components';\n\nconst Button = styled.button`\n background: ${props => props.primary ? 'blue' : 'grey'};\n padding: 10px 20px;\n border: none;\n border-radius: 4px;\n \n &:hover {\n opacity: 0.8;\n }\n`;\n\nfunction MyComponent() {\n return (\n
\n \n \n
\n );\n}\n```\n\n### Emotion\n\n```jsx\n/** @jsxImportSource @emotion/react */\nimport { css } from '@emotion/react';\n\nconst buttonStyle = css`\n background: blue;\n color: white;\n padding: 10px 20px;\n border: none;\n border-radius: 4px;\n \n &:hover {\n background: darkblue;\n }\n`;\n\nfunction MyComponent() {\n return ;\n}\n```\n\n### CSS Modules with Dynamic Imports\n\n```css\n/* Button.module.css */\n.button {\n background: blue;\n color: white;\n padding: 10px 20px;\n border: none;\n border-radius: 4px;\n}\n\n.button:hover {\n background: darkblue;\n}\n```\n\n```jsx\n// Button.jsx\nimport styles from './Button.module.css';\n\nfunction Button({ children, ...props }) {\n return (\n \n );\n}\n```\n\n## 🏗️ CSS Scoping Strategies\n\n### BEM Methodology\n\nUse Block, Element, Modifier naming convention to avoid conflicts:\n\n```css\n/* Main Application */\n.main-app__button {\n background: blue;\n}\n\n.main-app__button--primary {\n background: darkblue;\n}\n\n/* Micro Application */\n.micro-app__button {\n background: red;\n}\n\n.micro-app__button--large {\n padding: 15px 30px;\n}\n```\n\n### Namespace Prefixing\n\nAdd unique prefixes to all CSS classes:\n\n```css\n/* User Management Micro App */\n.user-mgmt-container { }\n.user-mgmt-header { }\n.user-mgmt-button { }\n\n/* Product Catalog Micro App */\n.product-cat-container { }\n.product-cat-header { }\n.product-cat-button { }\n```\n\n### CSS Custom Properties (Variables)\n\nUse CSS variables for consistent theming without conflicts:\n\n```css\n/* Main Application - Define theme variables */\n:root {\n --primary-color: #007bff;\n --secondary-color: #6c757d;\n --success-color: #28a745;\n --danger-color: #dc3545;\n}\n\n/* Micro Application - Use theme variables */\n.micro-app-button {\n background: var(--primary-color);\n color: white;\n}\n```\n\n## 🎭 Runtime Style Management\n\n### Dynamic CSS Loading\n\nLoad CSS dynamically when micro applications mount:\n\n```javascript\n// Lifecycle hooks for dynamic CSS loading\nconst lifeCycles = {\n async beforeMount(app) {\n // Load micro app specific CSS\n const link = document.createElement('link');\n link.rel = 'stylesheet';\n link.href = `${app.entry}/static/css/main.css`;\n link.id = `${app.name}-styles`;\n document.head.appendChild(link);\n },\n \n async afterUnmount(app) {\n // Remove micro app CSS\n const link = document.getElementById(`${app.name}-styles`);\n if (link) {\n document.head.removeChild(link);\n }\n }\n};\n\nregisterMicroApps([\n {\n name: 'micro-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/micro-app'\n }\n], lifeCycles);\n```\n\n### CSS Scoping with PostCSS\n\nUse PostCSS plugins to automatically scope CSS:\n\n```javascript\n// postcss.config.js\nmodule.exports = {\n plugins: [\n require('postcss-prefixwrap')('.micro-app-container')\n ]\n};\n```\n\n**Input CSS:**\n```css\n.button {\n background: blue;\n}\n```\n\n**Output CSS:**\n```css\n.micro-app-container .button {\n background: blue;\n}\n```\n\n## 🔧 Framework-Specific Solutions\n\n### React Applications\n\n#### Using CSS Modules with Create React App\n\n```javascript\n// Button.module.css\n.button {\n background: blue;\n color: white;\n}\n\n// Button.jsx\nimport styles from './Button.module.css';\n\nfunction Button({ children }) {\n return ;\n}\n```\n\n#### Custom CSS Prefix Hook\n\n```javascript\nimport { useMemo } from 'react';\n\nfunction useCSSPrefix(prefix) {\n return useMemo(() => {\n return (className) => `${prefix}-${className}`;\n }, [prefix]);\n}\n\n// Usage\nfunction MyComponent() {\n const cx = useCSSPrefix('user-mgmt');\n \n return (\n
\n \n
\n );\n}\n```\n\n### Vue Applications\n\n#### Scoped Styles\n\n```vue\n\n\n\n```\n\n#### CSS Modules in Vue\n\n```vue\n\n\n\n```\n\n### Angular Applications\n\n#### ViewEncapsulation\n\n```typescript\nimport { Component, ViewEncapsulation } from '@angular/core';\n\n@Component({\n selector: 'app-my-component',\n template: `\n
\n \n
\n `,\n styles: [`\n .component {\n padding: 20px;\n }\n .button {\n background: blue;\n color: white;\n }\n `],\n encapsulation: ViewEncapsulation.Emulated // Default\n})\nexport class MyComponent { }\n```\n\n## 🎪 Component Library Strategies\n\n### Design System Approach\n\nCreate a shared design system that all micro applications consume:\n\n```javascript\n// shared-design-system/Button.js\nexport const Button = ({ variant = 'primary', size = 'medium', children, ...props }) => {\n const baseClasses = 'btn';\n const variantClasses = {\n primary: 'btn-primary',\n secondary: 'btn-secondary'\n };\n const sizeClasses = {\n small: 'btn-sm',\n medium: 'btn-md',\n large: 'btn-lg'\n };\n \n const className = [\n baseClasses,\n variantClasses[variant],\n sizeClasses[size]\n ].join(' ');\n \n return ;\n};\n```\n\n### CSS Custom Properties for Theming\n\n```css\n/* Design system CSS */\n:root {\n --btn-primary-bg: #007bff;\n --btn-primary-color: white;\n --btn-secondary-bg: #6c757d;\n --btn-secondary-color: white;\n --btn-padding-sm: 8px 12px;\n --btn-padding-md: 10px 16px;\n --btn-padding-lg: 12px 20px;\n}\n\n.btn {\n border: none;\n border-radius: 4px;\n cursor: pointer;\n font-family: inherit;\n}\n\n.btn-primary {\n background: var(--btn-primary-bg);\n color: var(--btn-primary-color);\n}\n\n.btn-secondary {\n background: var(--btn-secondary-bg);\n color: var(--btn-secondary-color);\n}\n\n.btn-sm { padding: var(--btn-padding-sm); }\n.btn-md { padding: var(--btn-padding-md); }\n.btn-lg { padding: var(--btn-padding-lg); }\n```\n\n## 🚫 Third-Party Library Handling\n\n### Isolating Third-Party Styles\n\nWhen using third-party libraries that inject global styles:\n\n```javascript\n// Load third-party CSS in isolation\nconst loadLibraryStyles = (libraryName, cssUrl) => {\n return new Promise((resolve) => {\n const iframe = document.createElement('iframe');\n iframe.style.display = 'none';\n document.body.appendChild(iframe);\n \n const iframeDoc = iframe.contentDocument;\n const link = iframeDoc.createElement('link');\n link.rel = 'stylesheet';\n link.href = cssUrl;\n link.onload = () => {\n // Extract and scope the CSS\n const styles = Array.from(iframeDoc.styleSheets[0].cssRules)\n .map(rule => rule.cssText)\n .join('\\n');\n \n const scopedStyles = scopeCSS(styles, `.${libraryName}-container`);\n \n const style = document.createElement('style');\n style.textContent = scopedStyles;\n style.id = `${libraryName}-scoped-styles`;\n document.head.appendChild(style);\n \n document.body.removeChild(iframe);\n resolve();\n };\n iframeDoc.head.appendChild(link);\n });\n};\n```\n\n### CSS-in-JS for Third-Party Integration\n\n```javascript\nimport { createGlobalStyle } from 'styled-components';\n\n// Scope third-party styles to specific container\nconst AntdStyles = createGlobalStyle`\n .micro-app-container {\n .ant-btn {\n /* Override Ant Design button styles specifically for this micro app */\n border-radius: 8px;\n }\n \n .ant-table {\n /* Override Ant Design table styles */\n border: 1px solid #f0f0f0;\n }\n }\n`;\n\nfunction MicroApp() {\n return (\n
\n \n {/* Your micro app content */}\n
\n );\n}\n```\n\n## 🔍 Debugging Style Conflicts\n\n### Development Tools\n\n#### Style Inspection Script\n\n```javascript\n// Add to browser console for debugging\nconst findStyleConflicts = (selector) => {\n const elements = document.querySelectorAll(selector);\n \n elements.forEach((el, index) => {\n const styles = window.getComputedStyle(el);\n const rules = [];\n \n for (let i = 0; i < document.styleSheets.length; i++) {\n try {\n const sheet = document.styleSheets[i];\n const cssRules = sheet.cssRules || sheet.rules;\n \n for (let j = 0; j < cssRules.length; j++) {\n if (el.matches(cssRules[j].selectorText)) {\n rules.push({\n selector: cssRules[j].selectorText,\n rule: cssRules[j].cssText,\n sheet: sheet.href || 'inline'\n });\n }\n }\n } catch (e) {\n // Cross-origin stylesheet\n }\n }\n \n console.log(`Element ${index + 1}:`, el);\n console.log('Applied styles:', rules);\n });\n};\n\n// Usage: findStyleConflicts('.button');\n```\n\n#### Style Source Tracker\n\n```javascript\n// Track which micro app loaded which styles\nconst styleTracker = {\n styles: new Map(),\n \n track(appName, styleElement) {\n if (!this.styles.has(appName)) {\n this.styles.set(appName, []);\n }\n this.styles.get(appName).push(styleElement);\n },\n \n getByApp(appName) {\n return this.styles.get(appName) || [];\n },\n \n getConflicts() {\n const allSelectors = new Map();\n \n this.styles.forEach((styles, appName) => {\n styles.forEach(style => {\n // Parse CSS and check for selector conflicts\n // Implementation depends on CSS parser\n });\n });\n \n return allSelectors;\n }\n};\n```\n\n### Runtime Conflict Detection\n\n```javascript\n// Detect style conflicts at runtime\nconst detectStyleConflicts = () => {\n const observer = new MutationObserver((mutations) => {\n mutations.forEach((mutation) => {\n if (mutation.type === 'childList') {\n mutation.addedNodes.forEach((node) => {\n if (node.tagName === 'STYLE' || node.tagName === 'LINK') {\n checkForConflicts(node);\n }\n });\n }\n });\n });\n \n observer.observe(document.head, { childList: true });\n};\n\nconst checkForConflicts = (styleNode) => {\n // Implementation to check for CSS selector conflicts\n console.warn('New style node added:', styleNode);\n};\n```\n\n## 📊 Performance Considerations\n\n### CSS Loading Performance\n\n```javascript\n// Optimize CSS loading for micro applications\nconst optimizedCSSLoader = {\n cache: new Map(),\n \n async loadCSS(url, appName) {\n if (this.cache.has(url)) {\n return this.cache.get(url);\n }\n \n const response = await fetch(url);\n const css = await response.text();\n const optimizedCSS = this.optimizeCSS(css, appName);\n \n this.cache.set(url, optimizedCSS);\n return optimizedCSS;\n },\n \n optimizeCSS(css, appName) {\n // Remove unused selectors\n // Add app-specific prefixes\n // Minify if needed\n return css.replace(/(\\.[a-zA-Z-_]+)/g, `.${appName}-$1`);\n }\n};\n```\n\n### Bundle Splitting for Styles\n\n```javascript\n// webpack.config.js - Split CSS by micro app\nmodule.exports = {\n optimization: {\n splitChunks: {\n cacheGroups: {\n styles: {\n name: 'styles',\n test: /\\.css$/,\n chunks: 'all',\n enforce: true\n }\n }\n }\n }\n};\n```\n\n## 🎯 Best Practices Summary\n\n### ✅ Do's\n\n1. **Use qiankun's built-in isolation** when possible\n2. **Implement consistent naming conventions** (BEM, namespacing)\n3. **Use CSS-in-JS** for automatic isolation\n4. **Create a shared design system** for consistency\n5. **Test style isolation** in development\n6. **Monitor for conflicts** in production\n7. **Document style guidelines** for your team\n\n### ❌ Don'ts\n\n1. **Don't rely on global CSS** in micro applications\n2. **Don't use overly generic class names** (.button, .container)\n3. **Don't forget to clean up styles** when unmounting\n4. **Don't ignore third-party library styles**\n5. **Don't skip testing** style isolation\n6. **Don't use !important** unless absolutely necessary\n\n### 🎪 Real-World Example\n\nHere's a complete example of a well-isolated micro application:\n\n```jsx\n// MicroApp.jsx\nimport React from 'react';\nimport styled, { createGlobalStyle } from 'styled-components';\n\n// Global styles scoped to this micro app\nconst GlobalStyles = createGlobalStyle`\n .user-management-app {\n font-family: 'Inter', sans-serif;\n \n * {\n box-sizing: border-box;\n }\n }\n`;\n\n// Styled components with isolation\nconst Container = styled.div`\n padding: 20px;\n background: #f8f9fa;\n min-height: 100vh;\n`;\n\nconst Header = styled.h1`\n color: #343a40;\n margin-bottom: 20px;\n`;\n\nconst Button = styled.button`\n background: ${props => props.primary ? '#007bff' : '#6c757d'};\n color: white;\n border: none;\n padding: 10px 20px;\n border-radius: 4px;\n cursor: pointer;\n \n &:hover {\n opacity: 0.9;\n }\n`;\n\nfunction UserManagementApp() {\n return (\n
\n \n \n
User Management
\n \n \n \n
\n );\n}\n\nexport default UserManagementApp;\n```\n\n## 🔗 Related Documentation\n\n- [Performance Optimization](/cookbook/performance) - Optimize loading and runtime performance\n- [Error Handling](/cookbook/error-handling) - Handle CSS-related errors\n- [Configuration](/api/configuration) - Configure style isolation options\n- [Debugging](/cookbook/debugging) - Debug style conflicts " }, { "path": "docs/ecosystem/bundler-plugin.md", "content": "# Bundler Plugin\n\nThe `@qiankunjs/bundler-plugin` provides bundler plugins for the qiankun micro-frontend framework. Currently it supports Webpack (4 & 5), with plans to support other bundlers like Vite and Turbopack in the future.\n\n## Installation\n\n```bash\nnpm install @qiankunjs/bundler-plugin --save-dev\n# or\nyarn add @qiankunjs/bundler-plugin --dev\n# or\npnpm add @qiankunjs/bundler-plugin --save-dev\n```\n\n## Webpack Plugin\n\n### Features\n\n- **Automatic Library Configuration**: Sets the correct output library name and format for qiankun consumption\n- **Unique JSONP Function**: Ensures unique `jsonpFunction`/`chunkLoadingGlobal` names to prevent conflicts between micro applications\n- **Browser Compatibility**: Sets global object to `window` for proper browser execution\n- **Entry Script Marking**: Automatically adds `entry` attribute to the main entry script tag in HTML using webpack entrypoints\n- **Webpack 4 & 5 Support**: Compatible with both Webpack 4 and Webpack 5\n- **Zero Configuration**: Works out of the box with sensible defaults\n\n### Basic Usage\n\n```javascript\n// webpack.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/bundler-plugin');\n\nmodule.exports = {\n entry: './src/index.js',\n plugins: [\n new QiankunWebpackPlugin()\n ]\n};\n```\n\nThis basic configuration will:\n- Use the `name` field from your `package.json` as the library name\n- Automatically mark the entry script tag with the `entry` attribute (based on webpack entrypoints)\n- Configure the output for qiankun consumption\n\n### With Custom Options\n\n```javascript\n// webpack.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/bundler-plugin');\n\nmodule.exports = {\n entry: './src/index.js',\n plugins: [\n new QiankunWebpackPlugin({\n packageName: 'my-micro-app',\n })\n ]\n};\n```\n\n### Configuration Options\n\n#### `packageName` (optional)\n\n- **Type**: `string`\n- **Default**: Value from `package.json` name field\n- **Description**: Specifies the name of the output library that qiankun will use to identify your micro application\n\n### Framework Integration\n\n#### React (CRACO)\n\n```javascript\n// craco.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/bundler-plugin');\n\nmodule.exports = {\n webpack: {\n configure: (webpackConfig) => {\n webpackConfig.plugins.push(\n new QiankunWebpackPlugin({\n packageName: process.env.REACT_APP_NAME || 'react-app'\n })\n );\n return webpackConfig;\n }\n }\n};\n```\n\n#### Vue CLI\n\n```javascript\n// vue.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/bundler-plugin');\n\nmodule.exports = {\n configureWebpack: {\n plugins: [\n new QiankunWebpackPlugin()\n ]\n },\n devServer: {\n port: 8080,\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n};\n```\n\n#### Angular\n\n```javascript\n// custom-webpack.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/bundler-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunWebpackPlugin({\n packageName: 'angular-micro-app'\n })\n ]\n};\n```\n\n### What the Plugin Does\n\n#### 1. Output Library Configuration\n\n**Webpack 4:**\n```javascript\n{\n output: {\n library: 'your-app-name',\n libraryTarget: 'window',\n jsonpFunction: 'webpackJsonp_your-app-name',\n globalObject: 'window'\n }\n}\n```\n\n**Webpack 5:**\n```javascript\n{\n output: {\n library: {\n name: 'your-app-name',\n type: 'window'\n }\n }\n}\n```\n\n#### 2. Entry Script Marking\n\nThe plugin uses webpack entrypoints to identify the main entry chunk and marks its script tag with `entry`. If multiple entrypoints exist, it matches by HTML filename; otherwise it falls back to the first entrypoint. If detection fails, it marks the last injected script.\n\n### Troubleshooting\n\n- **Library Not Exposed**: Ensure `package.json` has a valid name field, or explicitly set `packageName` in plugin options.\n- **Entry Attribute Missing**: Verify `html-webpack-plugin` is present and the plugin is listed after it in `plugins`. The plugin relies on webpack `compilation.entrypoints` to find the main chunk.\n\n## Related Documentation\n\n- [Core APIs](/api/) - qiankun core APIs\n- [Create Qiankun](/ecosystem/create-qiankun) - Project scaffolding tool\n- [React Bindings](/ecosystem/react) - React UI bindings\n- [Vue Bindings](/ecosystem/vue) - Vue UI bindings\n\n## Contributing\n\nFound an issue or want to contribute? Check out the [GitHub repository](https://github.com/umijs/qiankun) and contribute to the `packages/bundler-plugin` directory.\n" }, { "path": "docs/ecosystem/create-qiankun.md", "content": "# Create Qiankun\n\n`create-qiankun` is a CLI scaffolding tool designed specifically for the qiankun micro-frontend framework. It helps developers quickly bootstrap example projects and get started with micro-frontend development efficiently.\n\n## 🚀 Quick Start\n\n### Using npm\n\n```bash\nnpx create-qiankun@latest\n```\n\n### Using yarn\n\n```bash\nyarn create qiankun@latest\n```\n\n### Using pnpm\n\n```bash\npnpm dlx create-qiankun@latest\n```\n\n## 🎯 Features\n\n- **Multiple Project Types**: Choose between main app only, micro apps only, or complete setup\n- **Framework Support**: React 18, Vue 3, Vue 2, and Umi 4 templates\n- **Routing Modes**: Support for both hash and history routing patterns\n- **Package Manager Options**: npm, yarn, pnpm, or pnpm workspace\n- **Auto Configuration**: Automatic port conflict detection and startup scripts injection\n- **Monorepo Support**: Built-in pnpm workspace setup for managing multiple applications\n\n## 📋 Requirements\n\n- **Node.js**: v18 or higher (recommended: use [fnm](https://github.com/Schniz/fnm) for version management)\n- **Package Manager**: npm, yarn, or pnpm\n\n## 🎮 Interactive Setup\n\nWhen you run `create-qiankun`, you'll be guided through an interactive setup process:\n\n### Step 1: Project Name\n\n```bash\n? Project name: › my-qiankun-project\n```\n\n### Step 2: Project Type\n\n```bash\n? Choose a way to create › \n❯ Create main application and sub applications\n Just create main application \n Just create sub applications\n```\n\n**Options:**\n- **Create main application and sub applications**: Complete setup with main app and multiple micro apps\n- **Just create main application**: Only create the main (shell) application\n- **Just create sub applications**: Only create micro applications\n\n### Step 3: Main Application Framework (if applicable)\n\n```bash\n? Choose a framework for your main application › \n❯ React18+Webpack\n Vue3+Webpack\n React18+umi4\n```\n\n### Step 4: Routing Pattern (if applicable)\n\n```bash\n? Choose a route pattern for your main application › \n❯ hash\n history\n```\n\n### Step 5: Sub Applications Framework (if applicable)\n\n```bash\n? Choose a framework for your sub application › \nSpace to select. Return to submit.\n\n❯◯ React18+Webpack\n ◯ Vue3+Webpack \n ◯ Vue2+Webpack\n ◯ React18+umi4\n```\n\n### Step 6: Package Manager\n\n```bash\n? Which package manager do you want to use? › \n❯ npm\n yarn\n pnpm\n pnpm with workspace\n```\n\n## 📦 Available Templates\n\n### Main Application Templates\n\n| Template | Description | Features |\n|----------|-------------|----------|\n| **React18+Webpack** | React 18 with Webpack 5 | Modern React, TypeScript support, Hot reload |\n| **Vue3+Webpack** | Vue 3 with Vue CLI | Composition API, TypeScript, Element Plus |\n| **React18+umi4** | Umi 4 framework | Built-in qiankun support, Ant Design Pro |\n\n### Sub Application Templates\n\n| Template | Description | Status | Notes |\n|----------|-------------|--------|-------|\n| **React18+Webpack** | React 18 micro app | ✅ Stable | Production ready |\n| **Vue3+Webpack** | Vue 3 micro app | ✅ Stable | Production ready |\n| **Vue2+Webpack** | Vue 2 micro app | ⚠️ Limited | Issues with pnpm workspace |\n| **React18+umi4** | Umi 4 micro app | ✅ Stable | Built-in micro app support |\n| **Vite+Vue3** | Vue 3 with Vite | 🚧 WIP | Under development |\n| **Vite+React18** | React 18 with Vite | 🚧 WIP | Under development |\n\n## 🏗️ Project Structure\n\n### Single Project Structure\n\n```\nmy-qiankun-project/\n├── main-app/ # Main application\n│ ├── src/\n│ ├── package.json\n│ └── webpack.config.js\n├── react18-sub/ # React micro app\n│ ├── src/\n│ ├── package.json\n│ └── webpack.config.js\n├── vue3-sub/ # Vue micro app\n│ ├── src/\n│ ├── package.json\n│ └── vue.config.js\n└── package.json\n```\n\n### Pnpm Workspace Structure\n\n```\nmy-qiankun-project/\n├── packages/\n│ ├── main-app/ # Main application\n│ ├── react18-sub/ # React micro app\n│ └── vue3-sub/ # Vue micro app\n├── package.json # Workspace configuration\n├── pnpm-workspace.yaml # Workspace definition\n└── scripts/\n └── checkPnpm.js # Package manager validation\n```\n\n## 🔧 Generated Configuration\n\n### Main Application Configuration\n\nThe main application is automatically configured with:\n\n```typescript\n// Main app micro app registration\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'react18-sub',\n entry: '//localhost:8080',\n container: '#subapp-viewport',\n activeRule: '/react18-sub',\n },\n {\n name: 'vue3-sub', \n entry: '//localhost:8081',\n container: '#subapp-viewport',\n activeRule: '/vue3-sub',\n }\n]);\n\nstart();\n```\n\n### Micro Application Configuration\n\nEach micro application includes:\n\n**React Micro App:**\n```javascript\n// webpack.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunWebpackPlugin()\n ]\n};\n```\n\n**Vue Micro App:**\n```javascript\n// vue.config.js\nconst { defineConfig } = require('@vue/cli-service');\nconst { QiankunWebpackPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = defineConfig({\n configureWebpack: {\n plugins: [\n new QiankunWebpackPlugin()\n ]\n }\n});\n```\n\n### Port Configuration\n\nAutomatic port assignment prevents conflicts:\n\n```json\n{\n \"scripts\": {\n \"dev\": \"PORT=8080 react-scripts start\",\n \"check-port\": \"node scripts/checkPort.js\"\n }\n}\n```\n\n## 🎨 Customization Options\n\n### Environment-specific Configuration\n\n```javascript\n// config/development.js\nmodule.exports = {\n microApps: [\n {\n name: 'react-app',\n entry: '//localhost:8080',\n activeRule: '/react-app'\n }\n ]\n};\n\n// config/production.js\nmodule.exports = {\n microApps: [\n {\n name: 'react-app', \n entry: '//app.example.com',\n activeRule: '/react-app'\n }\n ]\n};\n```\n\n### Custom Routing\n\n```typescript\n// Hash routing (default)\nconst router = createRouter({\n history: createWebHashHistory(),\n routes: [...]\n});\n\n// History routing \nconst router = createRouter({\n history: createWebHistory(),\n routes: [...]\n});\n```\n\n## 🚀 Development Workflow\n\n### Single Package Manager\n\n```bash\n# Start main application\ncd main-app && npm run dev\n\n# Start micro applications (in separate terminals)\ncd react18-sub && npm run dev \ncd vue3-sub && npm run dev\n```\n\n### Pnpm Workspace\n\n```bash\n# Install all dependencies\npnpm install\n\n# Start all applications concurrently\npnpm run dev\n\n# Start specific application\npnpm --filter main-app run dev\npnpm --filter react18-sub run dev\n```\n\n### Generated Scripts\n\nThe CLI automatically injects useful scripts:\n\n```json\n{\n \"scripts\": {\n \"dev\": \"concurrently \\\"npm run dev:main\\\" \\\"npm run dev:subs\\\"\",\n \"dev:main\": \"cd main-app && npm run dev\",\n \"dev:subs\": \"concurrently \\\"cd react18-sub && npm run dev\\\" \\\"cd vue3-sub && npm run dev\\\"\",\n \"build\": \"npm run build:main && npm run build:subs\",\n \"clean\": \"rimraf node_modules **/*/node_modules\"\n }\n}\n```\n\n## 🔧 Advanced Usage\n\n### Command Line Arguments\n\nSkip the interactive prompts by providing arguments:\n\n```bash\nnpx create-qiankun my-project CreateMainAndSubApp react18-main hash react18-webpack-sub,vue3-webpack-sub pnpm\n```\n\n**Arguments order:**\n1. Project name\n2. Create kind (`CreateMainApp` | `CreateSubApp` | `CreateMainAndSubApp`)\n3. Main app template (if applicable)\n4. Routing pattern (if applicable) \n5. Sub app templates (comma-separated, if applicable)\n6. Package manager\n\n### Batch Creation\n\n```bash\n# Create multiple projects\nfor project in app1 app2 app3; do\n npx create-qiankun $project CreateMainAndSubApp react18-main history react18-webpack-sub pnpm\ndone\n```\n\n### Custom Templates\n\nYou can extend the CLI with custom templates by contributing to the project or forking the repository.\n\n## 🎯 Project Examples\n\n### Complete React + Vue Setup\n\n```bash\nnpx create-qiankun my-micro-frontend-app\n# Choose: Create main application and sub applications\n# Main: React18+Webpack\n# Routing: history\n# Subs: React18+Webpack, Vue3+Webpack\n# Package Manager: pnpm with workspace\n```\n\n**Result:**\n- Main React app with routing\n- React 18 micro app\n- Vue 3 micro app \n- Automatic port assignment (3000, 8080, 8081)\n- Workspace configuration\n- Development scripts\n\n### Umi-based Monorepo\n\n```bash\nnpx create-qiankun enterprise-app\n# Choose: Create main application and sub applications \n# Main: React18+umi4\n# Routing: history\n# Subs: React18+umi4, Vue3+Webpack\n# Package Manager: pnpm with workspace\n```\n\n**Features:**\n- Umi 4 main application with built-in qiankun support\n- Umi 4 micro application\n- Vue 3 micro application\n- Ant Design Pro components\n- TypeScript configuration\n\n## 📚 Best Practices\n\n### 1. Use Descriptive Names\n\n```bash\n# ✅ Good: Descriptive project names\nnpx create-qiankun e-commerce-platform\nnpx create-qiankun admin-dashboard\n\n# ❌ Bad: Generic names\nnpx create-qiankun app1\nnpx create-qiankun project\n```\n\n### 2. Choose Appropriate Package Manager\n\n```bash\n# For simple projects\nnpm / yarn\n\n# For monorepo with multiple teams\npnpm with workspace\n```\n\n### 3. Plan Your Routing Strategy\n\n```bash\n# Hash routing - simpler deployment\n# History routing - better SEO, requires server configuration\n```\n\n### 4. Consider Framework Compatibility\n\n- **React + Vue**: Good for mixed teams\n- **Same Framework**: Easier dependency management\n- **Umi**: Best for enterprise applications\n\n## 🐛 Troubleshooting\n\n### Port Conflicts\n\nThe CLI automatically detects and resolves port conflicts. If you encounter issues:\n\n```bash\n# Check running processes\nlsof -i :8080\n\n# Kill conflicting processes\nkill -9 $(lsof -t -i:8080)\n```\n\n### Pnpm Workspace Issues\n\n```bash\n# Clear node_modules and reinstall\npnpm run clean\npnpm install\n\n# Check workspace configuration\ncat pnpm-workspace.yaml\n```\n\n### Build Errors\n\n```bash\n# Clear build cache\nrm -rf dist/ build/ .cache/\n\n# Reinstall dependencies\nrm -rf node_modules package-lock.json\nnpm install\n```\n\n### Vue 2 with Pnpm Workspace\n\nKnown limitation: Vue 2 templates have compatibility issues with pnpm workspace. Use alternative approaches:\n\n```bash\n# Use regular pnpm instead\n# Choose: pnpm (not pnpm with workspace)\n\n# Or use yarn/npm for Vue 2 projects\n```\n\n## 🔗 Generated Project Features\n\n### Automatic Configuration\n\n- **Webpack optimization** for micro-frontend builds\n- **CORS handling** for cross-origin requests \n- **Public path** configuration for different environments\n- **Development proxy** setup for local development\n\n### Development Experience\n\n- **Hot module replacement** in all applications\n- **Error boundaries** for micro app failures\n- **Loading states** during micro app transitions\n- **TypeScript support** where applicable\n\n### Production Ready\n\n- **Build optimization** for micro-frontend deployment\n- **Asset optimization** and code splitting\n- **Environment configuration** for different stages\n- **CI/CD friendly** structure\n\n## 📖 Next Steps\n\nAfter creating your project:\n\n1. **Explore the generated code** to understand the structure\n2. **Customize the configuration** based on your needs\n3. **Add more micro applications** as your project grows\n4. **Set up CI/CD pipelines** for automated deployment\n5. **Read the qiankun documentation** for advanced features\n\n## 🔗 Related Documentation\n\n- [Core APIs](/api/) - qiankun core APIs\n- [React Bindings](/ecosystem/react) - React UI bindings\n- [Vue Bindings](/ecosystem/vue) - Vue UI bindings\n- [Webpack Plugin](/ecosystem/webpack-plugin) - Build tool configuration\n\n## 🤝 Contributing\n\nWant to add new templates or improve the CLI? Check out the [GitHub repository](https://github.com/umijs/qiankun) and contribute to the `packages/create-qiankun` directory. " }, { "path": "docs/ecosystem/index.md", "content": "# Ecosystem\n\nqiankun provides a rich ecosystem of UI bindings and tools to help you build and maintain micro-frontend applications efficiently.\n\n## 🧩 UI Bindings\n\nqiankun offers declarative UI components for popular frameworks, making it easier to load and manage micro applications within your main application.\n\n### React\n\n**`@qiankunjs/react`** - Official React bindings for qiankun\n\n- **Features**: Declarative MicroApp component, automatic loading states, error boundaries\n- **Benefits**: Type-safe, React hooks support, seamless integration\n- **Use Case**: Perfect for React-based main applications\n\n```bash\nnpm install @qiankunjs/react\n```\n\n[Learn more about React bindings →](/ecosystem/react)\n\n### Vue\n\n**`@qiankunjs/vue`** - Official Vue bindings for qiankun\n\n- **Features**: Vue 2/3 compatible, composition API support, slot-based customization\n- **Benefits**: Reactive loading states, template-based approach, TypeScript support\n- **Use Case**: Ideal for Vue-based main applications\n\n```bash\nnpm install @qiankunjs/vue\n```\n\n[Learn more about Vue bindings →](/ecosystem/vue)\n\n## 🛠️ Development Tools\n\n### Webpack Plugin\n\n**`@qiankunjs/webpack-plugin`** - Webpack plugin for micro applications\n\n- **Features**: Automatic public path injection, build optimization, development mode support\n- **Benefits**: Zero-config setup, improved developer experience, production-ready builds\n- **Use Case**: Essential for webpack-based micro applications\n\n```bash\nnpm install @qiankunjs/webpack-plugin --save-dev\n```\n\n[Learn more about Webpack Plugin →](/ecosystem/webpack-plugin)\n\n### Create Qiankun\n\n**`create-qiankun`** - CLI tool for scaffolding qiankun projects\n\n- **Features**: Multiple templates, main app + micro app setup, best practices included\n- **Benefits**: Quick project initialization, production-ready configurations, modern tooling\n- **Use Case**: Starting new qiankun projects or adding micro-frontend capabilities\n\n```bash\nnpx create-qiankun my-micro-frontend-app\n```\n\n[Learn more about Create Qiankun →](/ecosystem/create-qiankun)\n\n## 🎯 Quick Start Comparison\n\n### Without UI Bindings (Core API)\n\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\n// Manual approach\nconst microApp = loadMicroApp({\n name: 'my-app',\n entry: '//localhost:8080',\n container: '#subapp-container'\n});\n\n// Manual lifecycle management\nmicroApp.mountPromise.then(() => {\n setLoading(false);\n}).catch(error => {\n setError(error);\n});\n```\n\n### With React Binding\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n### With Vue Binding\n\n```vue\n\n\n\n```\n\n## 🔄 Integration Flow\n\n```mermaid\ngraph LR\n A[Main App] --> B[UI Binding]\n B --> C[qiankun Core]\n C --> D[Micro App 1]\n C --> E[Micro App 2]\n C --> F[Micro App 3]\n \n G[Webpack Plugin] --> D\n G --> E\n G --> F\n \n H[Create Qiankun] --> A\n H --> D\n H --> E\n H --> F\n```\n\n## 📋 Feature Comparison\n\n| Feature | Core API | React Binding | Vue Binding |\n|---------|----------|---------------|-------------|\n| **Loading States** | Manual | ✅ Automatic | ✅ Automatic |\n| **Error Handling** | Manual | ✅ Error Boundary | ✅ Error Boundary |\n| **Custom Loading** | Manual | ✅ Component | ✅ Slot |\n| **Custom Errors** | Manual | ✅ Component | ✅ Slot |\n| **TypeScript** | ✅ Full | ✅ Full | ✅ Full |\n| **Framework Integration** | Manual | ✅ Hooks | ✅ Composition API |\n\n## 🎨 Usage Patterns\n\n### 1. Simple Loading\n\n**React:**\n```tsx\n\n```\n\n**Vue:**\n```vue\n\n```\n\n### 2. Custom Loading & Error Handling\n\n**React:**\n```tsx\n loading ? : null}\n errorBoundary={(error) => }\n/>\n```\n\n**Vue:**\n```vue\n\n \n \n\n```\n\n### 3. Props Passing\n\n**React:**\n```tsx\n\n```\n\n**Vue:**\n```vue\n\n```\n\n## 🚀 Getting Started\n\n### Step 1: Choose Your Stack\n\n1. **React Main App** → Use `@qiankunjs/react`\n2. **Vue Main App** → Use `@qiankunjs/vue`\n3. **Other Framework** → Use core qiankun APIs\n\n### Step 2: Scaffold Your Project\n\n```bash\n# Create new project\nnpx create-qiankun my-app\n\n# Choose template:\n# - React main + React micro apps\n# - Vue main + Vue micro apps\n# - Umi main + multiple micro apps\n# - Custom configuration\n```\n\n### Step 3: Configure Micro Apps\n\nAdd webpack plugin to each micro application:\n\n```javascript\n// webpack.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunWebpackPlugin()\n ]\n};\n```\n\n### Step 4: Start Development\n\n```bash\n# Start main app\ncd main-app && npm start\n\n# Start micro app (in separate terminal)\ncd micro-app && npm start\n```\n\n## 🔧 Advanced Configuration\n\n### Environment-based Configuration\n\n```typescript\n// React main app\nconst MicroAppConfig = {\n development: {\n entry: '//localhost:8080',\n autoSetLoading: true,\n autoCaptureError: true,\n },\n production: {\n entry: '//your-domain.com/micro-app',\n autoSetLoading: false, // Custom loading\n autoCaptureError: true,\n }\n};\n\nconst config = MicroAppConfig[process.env.NODE_ENV];\n\nfunction App() {\n return ;\n}\n```\n\n### Multi-app Dashboard\n\n```tsx\n// React - Multiple micro apps\nfunction Dashboard() {\n return (\n
\n \n
\n \n
\n
\n \n
\n
\n );\n}\n```\n\n## 📚 Documentation Links\n\n- [React Bindings](/ecosystem/react) - Complete React integration guide\n- [Vue Bindings](/ecosystem/vue) - Complete Vue integration guide \n- [Webpack Plugin](/ecosystem/webpack-plugin) - Build tool configuration\n- [Create Qiankun](/ecosystem/create-qiankun) - Project scaffolding\n- [API Reference](/api/) - Core qiankun APIs\n\n## 🤝 Community\n\n- [GitHub Discussions](https://github.com/umijs/qiankun/discussions) - Ask questions and share ideas\n- [Issues](https://github.com/umijs/qiankun/issues) - Bug reports and feature requests\n- [Changelog](https://github.com/umijs/qiankun/releases) - Latest updates and releases\n\nChoose the tools that best fit your project needs and start building powerful micro-frontend applications! " }, { "path": "docs/ecosystem/react.md", "content": "# React Bindings\n\nThe official React bindings for qiankun provide a declarative way to integrate micro applications into your React main application. The `@qiankunjs/react` package offers a powerful `` component with built-in loading states, error handling, and TypeScript support.\n\n## 📦 Installation\n\n```bash\nnpm install @qiankunjs/react\n```\n\n**Requirements:**\n- React ≥ 16.9.0\n- qiankun ≥ 3.0.0\n\n## 🚀 Quick Start\n\n### Basic Usage\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n
\n

Main Application

\n \n
\n );\n}\n\nexport default App;\n```\n\n### With Loading State\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n### With Error Handling\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n## 🎯 Component API\n\n### Props\n\n| Prop | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|\n| `name` | `string` | ✅ | - | Unique name for the micro application |\n| `entry` | `string` | ✅ | - | Entry URL of the micro application |\n| `autoSetLoading` | `boolean` | ❌ | `false` | Automatically manage loading state |\n| `autoCaptureError` | `boolean` | ❌ | `false` | Automatically handle errors |\n| `loader` | `(loading: boolean) => React.ReactNode` | ❌ | `undefined` | Custom loading component |\n| `errorBoundary` | `(error: any) => React.ReactNode` | ❌ | `undefined` | Custom error component |\n| `className` | `string` | ❌ | `undefined` | CSS class for the micro app container |\n| `wrapperClassName` | `string` | ❌ | `undefined` | CSS class for the wrapper (when using loader/errorBoundary) |\n| `settings` | `AppConfiguration` | ❌ | `{}` | qiankun configuration options |\n| `lifeCycles` | `LifeCycles` | ❌ | `undefined` | Lifecycle hooks |\n\n### Additional Props\n\nAny additional props passed to `` will be forwarded to the micro application as props:\n\n```tsx\n\n```\n\n## 🔄 Lifecycle Management\n\n### Using Ref to Access Micro App Instance\n\n```tsx\nimport React, { useRef, useEffect } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n const microAppRef = useRef();\n\n useEffect(() => {\n // Get micro app status\n console.log(microAppRef.current?.getStatus());\n }, []);\n\n const handleUnmount = () => {\n microAppRef.current?.unmount();\n };\n\n return (\n
\n \n \n
\n );\n}\n```\n\n### App Status\n\nThe micro app instance provides these status values:\n\n- `NOT_LOADED` - Initial state, not loaded yet\n- `LOADING_SOURCE_CODE` - Loading application resources\n- `NOT_BOOTSTRAPPED` - Resources loaded, not bootstrapped\n- `BOOTSTRAPPING` - Running bootstrap lifecycle\n- `NOT_MOUNTED` - Bootstrapped but not mounted\n- `MOUNTING` - Running mount lifecycle\n- `MOUNTED` - Successfully mounted and running\n- `UPDATING` - Running update lifecycle\n- `UNMOUNTING` - Running unmount lifecycle\n- `UNLOADING` - Cleaning up resources\n\n## 🎨 Customization\n\n### Custom Loading Component\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport { Spin, Alert } from 'antd';\n\nconst CustomLoader: React.FC<{ loading: boolean }> = ({ loading }) => {\n if (!loading) return null;\n \n return (\n
\n \n

Loading micro application...

\n
\n );\n};\n\nfunction App() {\n return (\n }\n />\n );\n}\n```\n\n### Custom Error Boundary\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport { Alert, Button } from 'antd';\n\nconst CustomErrorBoundary: React.FC<{ error: Error }> = ({ error }) => {\n const handleRetry = () => {\n window.location.reload();\n };\n\n return (\n
\n \n Retry\n \n }\n />\n
\n );\n};\n\nfunction App() {\n return (\n }\n />\n );\n}\n```\n\n### Styling\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport './MicroApp.css';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n```css\n/* MicroApp.css */\n.micro-app-wrapper {\n border: 1px solid #e8e8e8;\n border-radius: 6px;\n overflow: hidden;\n}\n\n.micro-app-container {\n min-height: 400px;\n background: #fafafa;\n}\n```\n\n## 🔧 Advanced Usage\n\n### Multiple Micro Apps\n\n```tsx\nimport React, { useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport { Tabs } from 'antd';\n\nconst { TabPane } = Tabs;\n\nfunction Dashboard() {\n const [activeTab, setActiveTab] = useState('dashboard');\n\n return (\n
\n \n \n \n \n \n \n \n \n \n \n \n
\n );\n}\n```\n\n### Conditional Loading\n\n```tsx\nimport React, { useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction ConditionalApp() {\n const [showMicroApp, setShowMicroApp] = useState(false);\n const [user, setUser] = useState(null);\n\n // Only load micro app when user is authenticated\n if (!user) {\n return
Please log in to continue
;\n }\n\n return (\n
\n \n \n {showMicroApp && (\n \n )}\n
\n );\n}\n```\n\n### Dynamic Entry URLs\n\n```tsx\nimport React, { useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction DynamicApp() {\n const [environment, setEnvironment] = useState('development');\n \n const entryUrls = {\n development: '//localhost:8080',\n staging: '//staging.example.com',\n production: '//app.example.com'\n };\n\n return (\n
\n \n \n \n
\n );\n}\n```\n\n## 🎮 State Management\n\n### Using Context to Share State\n\n```tsx\nimport React, { createContext, useContext, useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\n// Create a context for shared state\nconst AppContext = createContext();\n\nfunction MainApp() {\n const [sharedState, setSharedState] = useState({\n user: { id: 1, name: 'John' },\n theme: 'dark'\n });\n\n return (\n \n
\n \n \n
\n \n );\n}\n\nfunction MicroAppContainer() {\n const { sharedState } = useContext(AppContext);\n \n return (\n \n );\n}\n```\n\n### Communication Between Apps\n\n```tsx\nimport React, { useEffect, useRef } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction CommunicatingApps() {\n const microApp1Ref = useRef();\n const microApp2Ref = useRef();\n\n useEffect(() => {\n // Set up communication channel\n window.appCommunication = {\n sendMessage: (from, to, message) => {\n const event = new CustomEvent('microAppMessage', {\n detail: { from, to, message }\n });\n window.dispatchEvent(event);\n }\n };\n\n // Listen for messages\n const handleMessage = (event) => {\n console.log('Message received:', event.detail);\n };\n\n window.addEventListener('microAppMessage', handleMessage);\n\n return () => {\n window.removeEventListener('microAppMessage', handleMessage);\n delete window.appCommunication;\n };\n }, []);\n\n return (\n
\n
\n \n
\n
\n \n
\n
\n );\n}\n```\n\n## 🔒 TypeScript Support\n\n### Typed Props\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\ninterface UserProfileProps {\n userId: string;\n theme: 'light' | 'dark';\n permissions: string[];\n}\n\n// Type the additional props\nconst UserProfileApp: React.FC = () => {\n const user = getCurrentUser();\n \n return (\n \n );\n};\n```\n\n### Custom Hook for Micro App\n\n```tsx\nimport { useRef, useEffect, useState } from 'react';\nimport type { MicroApp as MicroAppType } from 'qiankun';\n\ninterface UseMicroAppOptions {\n onStatusChange?: (status: string) => void;\n onError?: (error: Error) => void;\n}\n\nexport function useMicroApp(options: UseMicroAppOptions = {}) {\n const microAppRef = useRef();\n const [status, setStatus] = useState('NOT_LOADED');\n const [error, setError] = useState(null);\n\n useEffect(() => {\n const checkStatus = () => {\n if (microAppRef.current) {\n const currentStatus = microAppRef.current.getStatus();\n if (currentStatus !== status) {\n setStatus(currentStatus);\n options.onStatusChange?.(currentStatus);\n }\n }\n };\n\n const interval = setInterval(checkStatus, 1000);\n return () => clearInterval(interval);\n }, [status, options]);\n\n const handleError = (err: Error) => {\n setError(err);\n options.onError?.(err);\n };\n\n return {\n microAppRef,\n status,\n error,\n handleError\n };\n}\n\n// Usage\nfunction App() {\n const { microAppRef, status, error } = useMicroApp({\n onStatusChange: (status) => console.log('Status changed:', status),\n onError: (error) => console.error('App error:', error)\n });\n\n return (\n
\n

Status: {status}

\n {error &&

Error: {error.message}

}\n \n
\n );\n}\n```\n\n## 🚀 Performance Optimization\n\n### Lazy Loading\n\n```tsx\nimport React, { Suspense, lazy } from 'react';\n\n// Lazy load the MicroApp component\nconst LazyMicroApp = lazy(() => \n import('@qiankunjs/react').then(module => ({ default: module.MicroApp }))\n);\n\nfunction App() {\n return (\n Loading...
}>\n \n \n );\n}\n```\n\n### Memoization\n\n```tsx\nimport React, { memo, useMemo } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nconst MemoizedMicroApp = memo(MicroApp);\n\nfunction OptimizedApp({ user, settings }) {\n const microAppProps = useMemo(() => ({\n userId: user.id,\n theme: settings.theme,\n language: settings.language\n }), [user.id, settings.theme, settings.language]);\n\n return (\n \n );\n}\n```\n\n## 🐛 Error Handling & Debugging\n\n### Development Mode Error Handling\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction DevMicroApp() {\n const isDevelopment = process.env.NODE_ENV === 'development';\n\n const handleError = (error: Error) => {\n console.error('Micro app error:', error);\n \n if (isDevelopment) {\n // Show detailed error in development\n return (\n
\n

Development Error

\n 
{error.stack}
\n \n
\n );\n }\n \n // Show user-friendly error in production\n return (\n
\n

Something went wrong. Please try again later.

\n
\n );\n };\n\n return (\n \n );\n}\n```\n\n## 📚 Best Practices\n\n### 1. Use Descriptive Names\n\n```tsx\n// ✅ Good: Descriptive names\n\n\n\n// ❌ Bad: Generic names\n\n\n```\n\n### 2. Always Handle Loading States\n\n```tsx\n// ✅ Good: Handle loading states\n }\n/>\n\n// ❌ Bad: No loading indication\n\n```\n\n### 3. Implement Error Boundaries\n\n```tsx\n// ✅ Good: Handle errors gracefully\n }\n/>\n```\n\n### 4. Use Environment-specific Configurations\n\n```tsx\n// ✅ Good: Environment-aware\nconst config = {\n development: { entry: '//localhost:8080', debug: true },\n production: { entry: '//app.example.com', debug: false }\n};\n\n\n```\n\n## 🔗 Related Documentation\n\n- [Vue Bindings](/ecosystem/vue) - Vue UI bindings\n- [Core APIs](/api/) - qiankun core APIs\n- [Configuration](/api/configuration) - Configuration options\n- [Lifecycles](/api/lifecycles) - Lifecycle hooks " }, { "path": "docs/ecosystem/vue.md", "content": "# Vue Bindings\n\nThe official Vue bindings for qiankun provide a declarative way to integrate micro applications into your Vue main application. The `@qiankunjs/vue` package offers a powerful `` component with Vue 2/3 compatibility, composition API support, and slot-based customization.\n\n## 📦 Installation\n\n```bash\nnpm install @qiankunjs/vue\n```\n\n**Requirements:**\n- Vue 2.0+ or Vue 3.0+ \n- qiankun ≥ 3.0.0\n- For Vue 2, you may need `@vue/composition-api`\n\n## 🚀 Quick Start\n\n### Vue 3 with Composition API\n\n```vue\n\n\n\n```\n\n### Vue 2 with Options API\n\n```vue\n\n\n\n```\n\n### With Loading State\n\n```vue\n\n\n\n```\n\n### With Error Handling\n\n```vue\n\n\n\n```\n\n## 🎯 Component API\n\n### Props\n\n| Prop | Type | Required | Default | Description |\n|------|------|----------|---------|-------------|\n| `name` | `string` | ✅ | - | Unique name for the micro application |\n| `entry` | `string` | ✅ | - | Entry URL of the micro application |\n| `autoSetLoading` | `boolean` | ❌ | `false` | Automatically manage loading state |\n| `autoCaptureError` | `boolean` | ❌ | `false` | Automatically handle errors |\n| `className` | `string` | ❌ | `undefined` | CSS class for the micro app container |\n| `wrapperClassName` | `string` | ❌ | `undefined` | CSS class for the wrapper (when using slots) |\n| `appProps` | `Record` | ❌ | `undefined` | Props passed to the micro application |\n| `settings` | `AppConfiguration` | ❌ | `{}` | qiankun configuration options |\n| `lifeCycles` | `LifeCycles` | ❌ | `undefined` | Lifecycle hooks |\n\n### Slots\n\n| Slot | Description | Parameters |\n|------|-------------|------------|\n| `loader` | Custom loading component | `{ loading: boolean }` |\n| `errorBoundary` | Custom error component | `{ error: Error }` |\n\n## 🎨 Customization\n\n### Custom Loading with Slots\n\n```vue\n\n\n\n\n\n```\n\n### Custom Error Boundary\n\n```vue\n\n\n\n\n\n```\n\n### Styling\n\n```vue\n\n\n\n```\n\n## 🔧 Advanced Usage\n\n### Multiple Micro Apps with Tabs\n\n```vue\n\n\n\n\n\n```\n\n### Conditional Loading\n\n```vue\n\n\n\n```\n\n### Dynamic Entry URLs\n\n```vue\n\n\n\n```\n\n## 🎮 State Management\n\n### Using Pinia for State Sharing\n\n```vue\n\n\n\n\n```\n\n```typescript\n// stores/app.ts\nimport { defineStore } from 'pinia';\n\nexport const useAppStore = defineStore('app', {\n state: () => ({\n user: null,\n theme: 'dark',\n language: 'en'\n }),\n \n actions: {\n setUser(user) {\n this.user = user;\n },\n \n setTheme(theme) {\n this.theme = theme;\n }\n }\n});\n```\n\n```vue\n\n\n\n\n```\n\n### Communication Between Apps\n\n```vue\n\n\n\n\n\n```\n\n## 🔒 TypeScript Support\n\n### Typed Props with Vue 3\n\n```vue\n\n\n\n```\n\n### Custom Composable for Micro App\n\n```typescript\n// composables/useMicroApp.ts\nimport { ref, onMounted, onUnmounted, type Ref } from 'vue';\nimport type { MicroApp as MicroAppType } from 'qiankun';\n\ninterface UseMicroAppOptions {\n onStatusChange?: (status: string) => void;\n onError?: (error: Error) => void;\n}\n\nexport function useMicroApp(options: UseMicroAppOptions = {}) {\n const microAppRef: Ref = ref();\n const status = ref('NOT_LOADED');\n const error = ref(null);\n\n const checkStatus = () => {\n if (microAppRef.value?.microApp) {\n const currentStatus = microAppRef.value.microApp.getStatus();\n if (currentStatus !== status.value) {\n status.value = currentStatus;\n options.onStatusChange?.(currentStatus);\n }\n }\n };\n\n const handleError = (err: Error) => {\n error.value = err;\n options.onError?.(err);\n };\n\n let interval: number;\n\n onMounted(() => {\n interval = window.setInterval(checkStatus, 1000);\n });\n\n onUnmounted(() => {\n if (interval) {\n clearInterval(interval);\n }\n });\n\n return {\n microAppRef,\n status,\n error,\n handleError\n };\n}\n```\n\n```vue\n\n\n\n```\n\n## 🚀 Performance Optimization\n\n### Lazy Loading with Suspense\n\n```vue\n\n\n\n```\n\n### Memoization with computed\n\n```vue\n\n\n\n```\n\n### Keep-alive for Route-based Micro Apps\n\n```vue\n\n\n\n```\n\n```vue\n\n\n\n\n```\n\n## 🐛 Error Handling & Debugging\n\n### Development Mode Error Handling\n\n```vue\n\n\n\n```\n\n```vue\n\n\n\n\n\n\n```\n\n## 📚 Vue 2 Compatibility\n\n### Using with Vue 2\n\n```vue\n\n\n\n```\n\n### With Composition API in Vue 2\n\n```vue\n\n\n\n```\n\n## 📚 Best Practices\n\n### 1. Use Descriptive Names\n\n```vue\n\n\n\n\n\n\n\n```\n\n### 2. Always Handle Loading States\n\n```vue\n\n\n \n\n\n\n\n```\n\n### 3. Implement Error Boundaries\n\n```vue\n\n\n \n\n```\n\n### 4. Use Reactive Props\n\n```vue\n\n\n\n\n```\n\n### 5. Environment-specific Configurations\n\n```vue\n\n\n\n\n```\n\n## 🔗 Related Documentation\n\n- [React Bindings](/ecosystem/react) - React UI bindings\n- [Core APIs](/api/) - qiankun core APIs\n- [Configuration](/api/configuration) - Configuration options\n- [Lifecycles](/api/lifecycles) - Lifecycle hooks " }, { "path": "docs/faq/index.md", "content": "# Frequently Asked Questions\n\nThis FAQ covers the most common questions and issues encountered when working with qiankun. If you can't find the answer you're looking for, please check our [GitHub Issues](https://github.com/umijs/qiankun/issues) or join our community discussions.\n\n## 🚀 Getting Started\n\n### Q: What is qiankun and when should I use it?\n\n**A:** qiankun is a micro-frontend framework based on single-spa that enables you to build large-scale frontend applications by composing multiple smaller, independent applications. You should consider qiankun when:\n\n- Your team is growing and you need to scale development across multiple teams\n- You have legacy applications that need to coexist with new features\n- You want to use different frameworks (React, Vue, Angular) in one application\n- You need independent deployment capabilities for different parts of your app\n\n### Q: How does qiankun differ from other micro-frontend solutions?\n\n**A:** qiankun provides several key advantages:\n\n- **Production-ready**: Built and tested by Ant Financial (now Ant Group) in large-scale applications\n- **Framework agnostic**: Works with React, Vue, Angular, and vanilla JavaScript\n- **Powerful sandboxing**: JavaScript and CSS isolation out of the box\n- **HTML entry**: Simple configuration using HTML files as entry points\n- **Rich ecosystem**: UI bindings, CLI tools, and webpack plugins\n\n### Q: Can I use qiankun with existing applications?\n\n**A:** Yes! qiankun is designed to work with existing applications. You can:\n\n1. **Wrap existing apps**: Turn your current app into a qiankun main application\n2. **Incremental migration**: Gradually extract features into micro applications\n3. **Legacy integration**: Run legacy apps alongside new micro apps\n4. **Framework migration**: Migrate from one framework to another progressively\n\n## 🔧 Installation and Setup\n\n### Q: I'm getting CORS errors when loading micro applications. How do I fix this?\n\n**A:** CORS errors are common in development. Here are solutions:\n\n**For webpack dev server:**\n```javascript\n// webpack.config.js or vue.config.js\nmodule.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',\n 'Access-Control-Allow-Headers': 'X-Requested-With, content-type, Authorization'\n }\n }\n};\n```\n\n**For Create React App (using CRACO):**\n```javascript\n// craco.config.js\nmodule.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n};\n```\n\n**For production, configure your server:**\n```nginx\n# nginx.conf\nlocation / {\n add_header Access-Control-Allow-Origin *;\n add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';\n add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';\n}\n```\n\n### Q: My micro application won't load. What should I check?\n\n**A:** Follow this troubleshooting checklist:\n\n1. **Check the network tab**: Are there 404 errors for your micro app resources?\n2. **Verify CORS**: Are there CORS errors in the console?\n3. **Check the entry point**: Is your HTML entry file accessible?\n4. **Validate the export**: Does your micro app export the required lifecycle methods?\n5. **Check the container**: Is the container element present in the DOM?\n\n**Example of correct micro app export:**\n```javascript\n// Micro app entry file\nexport async function bootstrap() {\n console.log('micro app bootstrapped');\n}\n\nexport async function mount(props) {\n console.log('micro app mounted', props);\n // Your app mounting logic\n}\n\nexport async function unmount(props) {\n console.log('micro app unmounted', props);\n // Your app cleanup logic\n}\n```\n\n### Q: How do I handle different base paths for my micro applications?\n\n**A:** Configure the public path in your micro applications:\n\n**For webpack:**\n```javascript\n// webpack.config.js\nmodule.exports = {\n output: {\n publicPath: process.env.NODE_ENV === 'production' \n ? 'https://mycdn.com/micro-app/' \n : 'http://localhost:8080/'\n }\n};\n```\n\n**For runtime configuration:**\n```javascript\n// public-path.js in your micro app\nif (window.__POWERED_BY_QIANKUN__) {\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n}\n```\n\n## 🏗️ Architecture and Design\n\n### Q: How should I structure my micro-frontend architecture?\n\n**A:** Follow these architectural principles:\n\n**1. Domain-driven design:**\n```\nMain App (Shell)\n├── User Management (HR Domain)\n├── Product Catalog (Commerce Domain)\n├── Analytics Dashboard (BI Domain)\n└── Settings (System Domain)\n```\n\n**2. Shared vs. Independent:**\n- **Shared**: Authentication, navigation, design system\n- **Independent**: Business logic, data fetching, internal state\n\n**3. Communication patterns:**\n```javascript\n// Event-driven communication\nwindow.dispatchEvent(new CustomEvent('user-updated', { \n detail: { userId: 123 } \n}));\n\n// Props-based communication\nregisterMicroApps([{\n name: 'user-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/users',\n props: { \n userPermissions: currentUser.permissions,\n onUserUpdate: handleUserUpdate\n }\n}]);\n```\n\n### Q: How do I share dependencies between micro applications?\n\n**A:** Several approaches work well:\n\n**1. External dependencies (recommended):**\n```javascript\n// webpack.config.js\nmodule.exports = {\n externals: {\n 'react': 'React',\n 'react-dom': 'ReactDOM',\n 'lodash': '_'\n }\n};\n```\n\n**2. Module Federation:**\n```javascript\n// Main app webpack config\nnew ModuleFederationPlugin({\n name: 'shell',\n shared: {\n react: { singleton: true },\n 'react-dom': { singleton: true }\n }\n});\n```\n\n**3. CDN approach:**\n```html\n\n\n\n```\n\n### Q: Can micro applications communicate with each other?\n\n**A:** Yes, here are the recommended patterns:\n\n**1. Event-driven communication:**\n```javascript\n// Micro app A\nconst notifyOtherApps = (data) => {\n window.dispatchEvent(new CustomEvent('app-a-event', { detail: data }));\n};\n\n// Micro app B\nwindow.addEventListener('app-a-event', (event) => {\n console.log('Received from app A:', event.detail);\n});\n```\n\n**2. Shared state management:**\n```javascript\n// Global store\nwindow.__SHARED_STORE__ = {\n user: null,\n subscribe: [],\n updateUser: (user) => {\n window.__SHARED_STORE__.user = user;\n window.__SHARED_STORE__.subscribers.forEach(callback => callback(user));\n }\n};\n```\n\n**3. Props from main app:**\n```javascript\n// Main app coordinates communication\nconst handleDataChange = (data) => {\n // Update props for all relevant micro apps\n updateMicroAppProps('app-a', { sharedData: data });\n updateMicroAppProps('app-b', { sharedData: data });\n};\n```\n\n## 🎨 Styling and CSS\n\n### Q: My CSS styles are conflicting between micro applications. How do I fix this?\n\n**A:** Use qiankun's built-in style isolation:\n\n**1. Strict style isolation (Shadow DOM):**\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n sandbox: {\n strictStyleIsolation: true\n }\n});\n```\n\n**2. Experimental style isolation (CSS scoping):**\n```javascript\nstart({\n sandbox: {\n experimentalStyleIsolation: true\n }\n});\n```\n\n**3. Manual CSS scoping:**\n```css\n/* Prefix all your styles */\n.my-micro-app .button {\n background: blue;\n}\n\n.my-micro-app .container {\n padding: 20px;\n}\n```\n\nSee our [Style Isolation Guide](/cookbook/style-isolation) for comprehensive solutions.\n\n### Q: Can I use CSS-in-JS libraries with qiankun?\n\n**A:** Absolutely! CSS-in-JS libraries work great with qiankun:\n\n**Styled Components:**\n```jsx\nimport styled from 'styled-components';\n\nconst Button = styled.button`\n background: blue;\n color: white;\n`;\n```\n\n**Emotion:**\n```jsx\n/** @jsxImportSource @emotion/react */\nimport { css } from '@emotion/react';\n\nconst buttonStyle = css`\n background: blue;\n color: white;\n`;\n```\n\nCSS-in-JS provides natural isolation since styles are scoped to components.\n\n## 🔄 Routing and Navigation\n\n### Q: How do I handle routing in a micro-frontend setup?\n\n**A:** qiankun supports multiple routing strategies:\n\n**1. Route-based micro apps (recommended):**\n```javascript\nregisterMicroApps([\n {\n name: 'user-management',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/users' // Loads when route starts with /users\n },\n {\n name: 'product-catalog',\n entry: '//localhost:8081', \n container: '#container',\n activeRule: ['/products', '/categories'] // Multiple routes\n }\n]);\n```\n\n**2. Programmatic routing:**\n```javascript\n// Navigate between micro apps\nimport { navigateToUrl } from 'single-spa';\n\nconst navigateToUsers = () => {\n navigateToUrl('/users');\n};\n```\n\n**3. Hash routing:**\n```javascript\nregisterMicroApps([\n {\n name: 'hash-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '#/app' // Hash-based routing\n }\n]);\n```\n\n### Q: Can micro applications have their own internal routing?\n\n**A:** Yes! Each micro application can have its own internal router:\n\n**React Router example:**\n```jsx\n// In your micro app\nimport { BrowserRouter, Routes, Route } from 'react-router-dom';\n\nfunction App() {\n const basename = window.__POWERED_BY_QIANKUN__ ? '/users' : '/';\n \n return (\n \n \n } />\n } />\n } />\n \n \n );\n}\n```\n\n## 🚀 Performance\n\n### Q: My micro-frontend app is loading slowly. How can I improve performance?\n\n**A:** Follow these optimization strategies:\n\n**1. Enable prefetching:**\n```javascript\nstart({\n prefetch: true // or 'all' or specific app names\n});\n```\n\n**2. Use code splitting:**\n```javascript\n// Dynamic imports in micro apps\nconst HeavyComponent = React.lazy(() => import('./HeavyComponent'));\n```\n\n**3. Optimize bundle sizes:**\n```javascript\n// webpack.config.js\nmodule.exports = {\n optimization: {\n splitChunks: {\n chunks: 'all'\n }\n }\n};\n```\n\nSee our [Performance Optimization Guide](/cookbook/performance) for detailed strategies.\n\n### Q: How do I prevent memory leaks in micro applications?\n\n**A:** Implement proper cleanup:\n\n```javascript\n// Micro app lifecycle\nexport async function unmount() {\n // Clear timers\n clearInterval(myInterval);\n \n // Remove event listeners\n window.removeEventListener('resize', handleResize);\n \n // Clean up subscriptions\n subscription.unsubscribe();\n \n // Clear caches\n cache.clear();\n}\n```\n\n## 🛠️ Development and Debugging\n\n### Q: How do I debug micro applications in development?\n\n**A:** Use these debugging strategies:\n\n**1. Enable source maps:**\n```javascript\n// webpack.config.js\nmodule.exports = {\n devtool: 'source-map'\n};\n```\n\n**2. Use browser dev tools:**\n- Network tab: Check resource loading\n- Console: View error messages\n- Elements: Inspect DOM structure\n- Sources: Debug JavaScript with breakpoints\n\n**3. qiankun debugging:**\n```javascript\n// Enable detailed logging\nlocalStorage.setItem('qiankun:debug', true);\n```\n\n### Q: Can I use hot reload with micro applications?\n\n**A:** Yes, with some configuration:\n\n**For webpack dev server:**\n```javascript\n// webpack.config.js\nmodule.exports = {\n devServer: {\n hot: true,\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n};\n```\n\n**Note**: Hot reload works within each micro app, but changes to the main app may require a full refresh.\n\n## 🔒 Security\n\n### Q: How do I handle authentication across micro applications?\n\n**A:** Centralize authentication in the main application:\n\n**1. Token-based authentication:**\n```javascript\n// Main app handles auth\nconst userToken = await authenticate(credentials);\nlocalStorage.setItem('token', userToken);\n\n// Pass token to micro apps\nregisterMicroApps([{\n name: 'secure-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/secure',\n props: {\n token: userToken,\n user: currentUser\n }\n}]);\n```\n\n**2. Shared authentication state:**\n```javascript\n// Global auth state\nwindow.__AUTH_STATE__ = {\n user: currentUser,\n token: userToken,\n isAuthenticated: true\n};\n```\n\n### Q: Are there security concerns with micro-frontends?\n\n**A:** Be aware of these security considerations:\n\n**1. Content Security Policy (CSP):**\n```html\n\n```\n\n**2. CORS configuration:**\n- Only allow trusted origins\n- Validate requests properly\n- Use HTTPS in production\n\n**3. Dependency security:**\n- Regularly audit dependencies\n- Use tools like `npm audit`\n- Keep dependencies updated\n\n## 📱 Mobile and Browser Support\n\n### Q: Does qiankun work on mobile devices?\n\n**A:** Yes, qiankun works on mobile with considerations:\n\n**1. Touch event optimization:**\n```javascript\n// Use passive listeners\nelement.addEventListener('touchstart', handler, { passive: true });\n```\n\n**2. Viewport management:**\n```html\n\n```\n\n**3. Performance optimization:**\n- Reduce bundle sizes\n- Use lazy loading\n- Optimize images and assets\n\n### Q: Which browsers does qiankun support?\n\n**A:** qiankun supports modern browsers:\n\n- **Chrome**: 49+\n- **Firefox**: 45+\n- **Safari**: 10+\n- **Edge**: 79+\n- **IE**: Not supported\n\nFor older browsers, consider polyfills:\n```html\n\n```\n\n## 🚢 Deployment\n\n### Q: How do I deploy micro-frontend applications?\n\n**A:** Use independent deployment strategy:\n\n**1. Separate builds:**\n```bash\n# Build each app independently\ncd main-app && npm run build\ncd micro-app-1 && npm run build \ncd micro-app-2 && npm run build\n```\n\n**2. CDN deployment:**\n```javascript\n// Configure different CDNs for each app\nconst microApps = [\n {\n name: 'app-1',\n entry: 'https://cdn1.example.com/app-1/',\n container: '#container',\n activeRule: '/app-1'\n },\n {\n name: 'app-2', \n entry: 'https://cdn2.example.com/app-2/',\n container: '#container',\n activeRule: '/app-2'\n }\n];\n```\n\n### Q: How do I handle versioning and updates?\n\n**A:** Implement version management:\n\n**1. Semantic versioning:**\n```javascript\n// Package.json for each micro app\n{\n \"name\": \"user-management-app\",\n \"version\": \"1.2.3\"\n}\n```\n\n**2. Runtime version checking:**\n```javascript\nconst requiredVersion = '1.2.0';\nconst currentVersion = window.__MICRO_APP_VERSION__;\n\nif (!semver.gte(currentVersion, requiredVersion)) {\n console.warn('Micro app version compatibility issue');\n}\n```\n\n## 🔗 Integration\n\n### Q: Can I use qiankun with Server-Side Rendering (SSR)?\n\n**A:** SSR with micro-frontends is complex but possible:\n\n**1. Static rendering:**\n- Render micro apps on the server\n- Hydrate on the client\n\n**2. Considerations:**\n- Each micro app needs SSR support\n- Coordination between apps is challenging\n- Performance implications\n\n**Alternative approaches:**\n- Use edge-side includes (ESI)\n- Implement micro-frontends at the page level\n- Consider client-side rendering with fast initial loads\n\n### Q: How do I integrate qiankun with existing build tools?\n\n**A:** qiankun works with various build tools:\n\n**Webpack:** Use `@qiankunjs/webpack-plugin`\n**Vite:** Use `vite-plugin-qiankun`\n**Rollup:** Manual configuration\n**Parcel:** Manual configuration\n\nSee our [Ecosystem](/ecosystem/) section for specific integrations.\n\n## 🤝 Community and Support\n\n### Q: Where can I get help if I'm stuck?\n\n**A:** Multiple support channels are available:\n\n1. **GitHub Issues**: [umijs/qiankun](https://github.com/umijs/qiankun/issues)\n2. **Discussions**: GitHub Discussions for questions\n3. **Stack Overflow**: Tag questions with `qiankun`\n4. **Discord/Slack**: Community chat rooms\n\n### Q: How can I contribute to qiankun?\n\n**A:** We welcome contributions:\n\n1. **Bug reports**: Submit detailed issue reports\n2. **Feature requests**: Propose new features\n3. **Code contributions**: Submit pull requests\n4. **Documentation**: Improve docs and examples\n5. **Community**: Help answer questions\n\nSee our [Contributing Guide](https://github.com/umijs/qiankun/blob/master/CONTRIBUTING.md) for details.\n\n---\n\n## 📚 Additional Resources\n\n- [Complete API Reference](/api/)\n- [Best Practices Guide](/cookbook/)\n- [Ecosystem Tools](/ecosystem/)\n- [GitHub Repository](https://github.com/umijs/qiankun)\n- [Example Applications](https://github.com/umijs/qiankun/tree/master/examples)\n\n**Can't find what you're looking for?** Please [open an issue](https://github.com/umijs/qiankun/issues/new) or start a [discussion](https://github.com/umijs/qiankun/discussions) - we're here to help! " }, { "path": "docs/guide/index.md", "content": "# What is qiankun?\n\nqiankun is a micro-frontend implementation library based on [single-spa](https://github.com/single-spa/single-spa), designed to help you build a production-ready micro-frontend architecture system more simply and painlessly.\n\nqiankun hatched from Ant Financial's unified front-end platform for cloud products based on micro-frontends architecture. After full testing and polishing of a number of online applications, we extracted its micro-frontends kernel and open sourced it. We hope to help the systems who has the same requirement more convenient to build its own micro-frontends application in the community. At the same time, with the help of community, qiankun will be polished and improved.\n\nAt present qiankun has served more than 2000 online applications inside Ant, and it is definitely trustworthy in terms of ease of use and completeness.\n\n## 💡 What Are Micro FrontEnds?\n\n> Techniques, strategies and recipes for building a **modern web app** with **multiple teams** that can **ship features independently**. -- Micro Frontends\n\nMicro Frontends architecture has the following core values:\n\n- **Technology Agnostic** - The main framework does not restrict access to the technology stack of the application, and the sub-applications have full autonomy.\n- **Independent Development and Deployment** - The sub application repo is independent, and the frontend and backend can be independently developed. After deployment, the main framework can be updated automatically.\n- **Incremental Upgrade** - In the face of various complex scenarios, it is often difficult for us to upgrade or refactor the entire technology stack of an existing system. Micro frontends is a very good method and strategy for implementing progressive refactoring.\n- **Isolated Runtime** - State is isolated between each subapplication and no shared runtime state.\n\nThe micro-frontends architecture is designed to solve the application of a single application in a relatively long time span. As a result of the increase in the number of people and teams involved, it has evolved from a common application to a Frontend Monolith then becomes unmaintainable. Such a problem is especially common in enterprise web applications.\n\n### Problems with Traditional Monolithic Applications\n\n```bash\n┌─────────────────────────────────────┐\n│ Monolithic Frontend │\n│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │\n│ │Mod A│ │Mod B│ │Mod C│ │Mod D│ │\n│ └─────┘ └─────┘ └─────┘ └─────┘ │\n│ Tightly coupled, hard to │\n│ maintain │\n└─────────────────────────────────────┘\n```\n\n### Micro-Frontend Architecture\n\n```bash\n┌─────────────────────────────────────┐\n│ Main Application │\n│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │\n│ │App A│ │App B│ │App C│ │App D│ │\n│ └─────┘ └─────┘ └─────┘ └─────┘ │\n│ Independent development, deploy, │\n│ technology agnostic │\n└─────────────────────────────────────┘\n```\n\n## 🎯 Core Philosophy\n\nThe core design philosophy of qiankun is **decentralized runtime**, which means:\n\n- **🥄 Simple** - Since the main application sub-applications can be independent of the technology stack, qiankun is just a jQuery-like library for users. You need to call several qiankun APIs to complete the micro frontends transformation of your application. At the same time, due to the design of qiankun's HTML entry and sandbox, accessing sub-applications is as simple as using an iframe.\n\n- **🍡 Decoupling/Technology Agnostic** - As the core goal of the micro frontends is to disassemble the monolithic application into a number of loosely coupled micro applications that can be autonomous, all the designs of qiankun are follow this principle, such as HTML Entry, sandbox, and communicating mechanism between applications. Only in this way can we ensure that sub-applications truly have the ability to develop and run independently.\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TD\n A[Main App] --> B[qiankun]\n B --> C[Micro App A]\n B --> D[Micro App B]\n B --> E[Micro App C]\n \n F[Routing] --> A\n G[Resource Loading] --> B\n H[Lifecycle] --> B\n I[Sandbox Isolation] --> B\n```\n\nqiankun is based on the following core capabilities:\n\n### 🔄 Lifecycle Management\nEach micro application has a complete lifecycle:\n- **bootstrap** - Application initialization\n- **mount** - Application mounting\n- **unmount** - Application unmounting\n- **update** - Application update (optional)\n\n### 🛡️ Sandbox Isolation\n- **JS Isolation** - Provides multiple sandbox solutions to ensure JS between applications do not affect each other\n- **CSS Isolation** - Achieves style isolation through style scoping or Shadow DOM\n\n### 📡 Resource Loading\n- **HTML Entry** - Load micro applications through HTML as entry\n- **Preloading** - Supports application resource preloading to improve user experience\n- **Caching** - Intelligent resource caching strategy\n\n## 🤔 Why Not Iframe?\n\nWhile iframe is the most natural solution for implementing micro frontends, it has some serious limitations:\n\n- **URL synchronization issues** - The URL of the iframe and the main application cannot be synchronized\n- **UI inconsistencies** - The iframe is in a completely isolated context, which makes it difficult to maintain consistent UI styling\n- **Performance issues** - Each iframe creates a new context, consuming more memory and CPU resources\n- **SEO unfriendly** - Search engines cannot properly index iframe content\n- **Security restrictions** - Cross-origin iframe communication has security limitations\n- **User experience problems** - Issues with browser history, refresh, and bookmarking\n\nqiankun solves these problems by providing a complete micro-frontend solution that maintains the isolation benefits of iframe while avoiding its limitations.\n\n## ✨ Features\n\nqiankun provides the following key features:\n\n- **📦 Based On single-spa** - Provides more out-of-box APIs based on single-spa\n- **📱 Technology Agnostic** - Any JavaScript framework can use/integrate, whether React/Vue/Angular/jQuery or others\n- **💪 HTML Entry Access Mode** - Allows you to access sub-applications as simply as using an iframe\n- **🛡️ Style Isolation** - Ensures styles don't interfere with each other between applications\n- **🧳 JS Sandbox** - Ensures that global variables/events do not conflict between sub-applications\n- **⚡ Prefetch Assets** - Prefetch unopened sub-application assets during browser idle time to speed up sub-application opening\n- **🔌 Umi Plugin** - @umijs/plugin-qiankun is provided for umi applications to switch to a micro frontends architecture system with one line of code\n\n## 🎯 Use Cases\n\nqiankun is particularly suitable for the following scenarios:\n\n- **Large Enterprise Applications** - Multi-team collaborative development\n- **Technology Stack Migration** - Progressive upgrade of legacy systems\n- **Feature Modularization** - Independent development and deployment of feature modules\n- **Third-party Integration** - Integration of external applications or services\n\n## 🚀 Get Started\n\nReady to start using qiankun? Check out our [Quick Start](/guide/quick-start) guide to build your first micro-frontend application in minutes!\n\n## 📚 Learn More\n\n- [Tutorial](/guide/tutorial) - Step-by-step tutorial from scratch\n- [Core Concepts](/guide/concepts) - Understand qiankun's design principles\n- [Main Application](/guide/main-app) - How to configure the main application\n- [Micro Application](/guide/micro-app) - How to transform existing applications " }, { "path": "docs/guide/quick-start.md", "content": "# Quick Start\n\nThis guide will help you set up a basic qiankun micro-frontend application in 5 minutes.\n\n## Prerequisites\n\n- Node.js 16+\n- Basic JavaScript/TypeScript knowledge\n- Understanding of React, Vue or other frontend frameworks\n\n## 🚀 Step 1: Install qiankun\n\n::: code-group\n\n```bash [npm]\nnpm install qiankun\n```\n\n```bash [yarn]\nyarn add qiankun\n```\n\n```bash [pnpm]\npnpm add qiankun\n```\n\n:::\n\n## 🏠 Step 2: Main Application Configuration\n\n### 2.1 Create Main Application\n\n```bash\n# Create main application using your favorite framework\nnpx create-react-app main-app\ncd main-app\nnpm install qiankun\n```\n\n### 2.2 Register Micro Applications\n\nRegister micro applications in the main application's entry file:\n\n```typescript\n// src/index.js\nimport { registerMicroApps, start } from 'qiankun';\n\n// register micro applications\nregisterMicroApps([\n {\n name: 'vue-app', // micro app name, unique\n entry: '//localhost:8080', // micro app entry\n container: '#subapp-viewport', // micro app mount node\n activeRule: '/vue', // micro app activation rule\n },\n {\n name: 'react-app',\n entry: '//localhost:3001',\n container: '#subapp-viewport',\n activeRule: '/react',\n },\n]);\n\n// start qiankun\nstart();\n\n// render main application normally\nReactDOM.render(, document.getElementById('root'));\n```\n\n### 2.3 Create Micro Application Container\n\nReserve mount nodes for micro applications in the main application:\n\n```jsx\n// src/App.js\nimport React from 'react';\nimport { BrowserRouter as Router, Link } from 'react-router-dom';\n\nfunction App() {\n return (\n \n
\n
\n

qiankun Main Application

\n \n
\n {/* micro application mount point */}\n
\n
\n \n );\n}\n\nexport default App;\n```\n\n## 📦 Step 3: Micro Application Configuration\n\n### 3.1 Create Vue Micro Application\n\n```bash\nnpm install -g @vue/cli\nvue create vue-micro-app\ncd vue-micro-app\n```\n\n### 3.2 Export Lifecycle\n\nModify `src/main.js`:\n\n```javascript\nimport { createApp } from 'vue';\nimport { createRouter, createWebHistory } from 'vue-router';\nimport App from './App.vue';\nimport routes from './router';\n\nlet instance = null;\nlet router = null;\n\n/**\n * Render function\n * Two scenarios: called by main app lifecycle / micro app runs independently\n */\nfunction render(props = {}) {\n const { container } = props;\n \n router = createRouter({\n history: createWebHistory(window.__POWERED_BY_QIANKUN__ ? '/vue' : '/'),\n routes,\n });\n\n instance = createApp(App);\n instance.use(router);\n instance.mount(container ? container.querySelector('#app') : '#app');\n}\n\n// run independently\nif (!window.__POWERED_BY_QIANKUN__) {\n render();\n}\n\nexport async function bootstrap() {\n console.log('[vue] vue app bootstraped');\n}\n\nexport async function mount(props) {\n console.log('[vue] props from main framework', props);\n render(props);\n}\n\nexport async function unmount() {\n instance.unmount();\n instance._container.innerHTML = '';\n instance = null;\n router = null;\n}\n```\n\n### 3.3 Configure Webpack\n\nModify `vue.config.js`:\n\n```javascript\nconst { defineConfig } = require('@vue/cli-service');\nconst packageName = require('./package.json').name;\n\nmodule.exports = defineConfig({\n transpileDependencies: true,\n devServer: {\n port: 8080,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n configureWebpack: {\n output: {\n library: `${packageName}-[name]`,\n libraryTarget: 'umd',\n chunkLoadingGlobal: `webpackJsonp_${packageName}`,\n },\n },\n});\n```\n\n### 3.4 Create React Micro Application\n\n```bash\nnpx create-react-app react-micro-app\ncd react-micro-app\nnpm install react-app-rewired --save-dev\n```\n\n修改 `src/index.js`：\n\n```javascript\nimport React from 'react';\nimport ReactDOM from 'react-dom';\nimport './index.css';\nimport App from './App';\n\nfunction render(props) {\n const { container } = props;\n ReactDOM.render(\n , \n container ? container.querySelector('#root') : document.querySelector('#root')\n );\n}\n\nif (!window.__POWERED_BY_QIANKUN__) {\n render({});\n}\n\nexport async function bootstrap() {\n console.log('[react16] react app bootstraped');\n}\n\nexport async function mount(props) {\n console.log('[react16] props from main framework', props);\n render(props);\n}\n\nexport async function unmount(props) {\n const { container } = props;\n ReactDOM.unmountComponentAtNode(\n container ? container.querySelector('#root') : document.querySelector('#root')\n );\n}\n```\n\n创建 `config-overrides.js`：\n\n```javascript\nconst { name } = require('./package');\n\nmodule.exports = {\n webpack: (config) => {\n config.output.library = `${name}-[name]`;\n config.output.libraryTarget = 'umd';\n config.output.chunkLoadingGlobal = `webpackJsonp_${name}`;\n return config;\n },\n\n devServer: function (configFunction) {\n return function(proxy, allowedHost) {\n const config = configFunction(proxy, allowedHost);\n config.port = 3001;\n config.headers = {\n 'Access-Control-Allow-Origin': '*',\n };\n return config;\n };\n },\n};\n```\n\nModify scripts in `package.json`:\n\n```json\n{\n \"scripts\": {\n \"start\": \"react-app-rewired start\",\n \"build\": \"react-app-rewired build\",\n \"test\": \"react-app-rewired test\",\n \"eject\": \"react-scripts eject\"\n }\n}\n```\n\n## 🎉 Step 4: Start Applications\n\n### 4.1 Start All Applications\n\n```bash\n# Terminal 1: Start main application\ncd main-app\nnpm start\n\n# Terminal 2: Start Vue micro application\ncd vue-micro-app \nnpm run serve\n\n# Terminal 3: Start React micro application\ncd react-micro-app\nnpm start\n```\n\n### 4.2 Access Applications\n\n- Main application: http://localhost:3000\n- Click navigation to switch to different micro applications\n\n## ✅ Verify Integration\n\nIf everything is configured correctly, you should see:\n\n1. ✅ Main application loads normally\n2. ✅ Clicking navigation links switches to corresponding micro applications\n3. ✅ Micro applications can be accessed independently (http://localhost:8080, http://localhost:3001)\n4. ✅ Browser console shows lifecycle logs\n\n## 🎯 Common Issues\n\n::: warning CORS Issues\nMake sure your micro application's webpack devServer is configured with CORS headers:\n```javascript\nheaders: {\n 'Access-Control-Allow-Origin': '*',\n}\n```\n:::\n\n::: warning Routing Conflicts\nIn integration mode, micro application routing needs to add corresponding prefixes:\n```javascript\n// Vue Router\nhistory: createWebHistory(window.__POWERED_BY_QIANKUN__ ? '/vue' : '/')\n\n// React Router\n\n```\n:::\n\n## 🚀 Next Steps\n\nCongratulations! You have successfully built your first qiankun micro-frontend application. Next you can:\n\n- [Core Concepts](/guide/concepts) - Deeply understand qiankun's design principles\n- [Main Application](/guide/main-app) - Learn more main application configuration options\n- [Micro Application](/guide/micro-app) - Learn how to transform existing applications\n- [Best Practices](/cookbook/) - Learn production environment best practices " }, { "path": "docs/guide/tutorial.md", "content": "# Tutorial\n\nThis tutorial is suitable for people who are new to `qiankun`, and introduces how to build a `qiankun` project from scratch.\n\n## Main Application\n\nThe main application is not limited to any specific technical framework, it only needs to provide a container DOM, then register the micro applications and start qiankun.\n\nInstall `qiankun` first:\n\n```shell\n$ yarn add qiankun # or npm i qiankun -S\n```\n\nRegister the micro applications and start:\n\n```js\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'angularApp',\n entry: '//localhost:4200',\n container: '#container',\n activeRule: '/app-angular',\n },\n {\n name: 'reactApp',\n entry: '//localhost:3000',\n container: '#container',\n activeRule: '/app-react',\n },\n {\n name: 'vueApp',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/app-vue',\n },\n]);\n// start qiankun\nstart();\n```\n\n## Micro Applications\n\nMicro applications are divided into projects with `webpack` and without `webpack`. The things that need to be done for micro applications with `webpack` (mainly refers to Vue, React, Angular) are:\n\n1. Add `public-path.js` file, used to modify the runtime `publicPath`. [What is publicPath at runtime?](https://webpack.js.org/guides/public-path/#on-the-fly).\n\n::: warning\nNote: `publicPath` at runtime and `publicPath` at build time are different, and the two cannot be equivalently substituted.\n:::\n\n2. It is recommended to use the route of the `history` mode for the micro application. The route `base` needs to be set, and the value is the same as its `activeRule`.\n3. Import `public-path.js` at the top of the entry file, modify and export three `lifecycle` functions.\n4. Modify the `webpack` configuration to allow cross-domain in development environments and bundle with `umd`.\n\nThe main modifications are the above four, which may change according to different situations of the project. For example, if your project is deployed separately from all other files of `index.html`, it means that you have set the `publicPath` at build time to the full path, so you don't need to modify the `publicPath` at runtime (the first step can be omitted).\n\nFor micro applications built without `webpack`, just mount `lifecycle` functions to `window`.\n\n### React Micro Application\n\nTake the `react 16` project generated by `create react app` as an example, with `react-router-dom` 5.x.\n\n1. Add `public-path.js` in the `src` directory:\n\n ```js\n if (window.__POWERED_BY_QIANKUN__) {\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n }\n ```\n\n2. Set the `base` of `history` mode routing:\n\n ```html\n \n ```\n\n3. The entry file `index.js` is modified. In order to avoid the root id `#root` from conflicting with other DOMs, the search scope needs to be limited.\n\n ```js\n import './public-path';\n import React from 'react';\n import ReactDOM from 'react-dom';\n import App from './App';\n\n function render(props) {\n const { container } = props;\n ReactDOM.render(, container ? container.querySelector('#root') : document.querySelector('#root'));\n }\n\n if (!window.__POWERED_BY_QIANKUN__) {\n render({});\n }\n\n export async function bootstrap() {\n console.log('[react16] react app bootstraped');\n }\n\n export async function mount(props) {\n console.log('[react16] props from main framework', props);\n render(props);\n }\n\n export async function unmount(props) {\n const { container } = props;\n ReactDOM.unmountComponentAtNode(container ? container.querySelector('#root') : document.querySelector('#root'));\n }\n ```\n\n::: tip\nIt's important: When mount a sub-application through ReactDOM.render, need to ensure each sub-application load with a new router instance.\n:::\n\n4. Modify `webpack` configuration\n\n Install the plugin `@rescripts/cli`, of course, you can also choose other plugins, such as `react-app-rewired`.\n\n ```bash\n npm i -D @rescripts/cli\n ```\n\n Add `.rescriptsrc.js` to the root directory:\n\n ```js\n const { name } = require('./package');\n\n module.exports = {\n webpack: (config) => {\n config.output.library = `${name}-[name]`;\n config.output.libraryTarget = 'umd';\n config.output.jsonpFunction = `webpackJsonp_${name}`;\n config.output.globalObject = 'window';\n\n return config;\n },\n\n devServer: (_) => {\n const config = _;\n\n config.headers = {\n 'Access-Control-Allow-Origin': '*',\n };\n config.historyApiFallback = true;\n config.hot = false;\n config.watchContentBase = false;\n config.liveReload = false;\n\n return config;\n },\n };\n ```\n\n Modify `package.json`:\n\n ```diff\n - \"start\": \"react-scripts start\",\n + \"start\": \"rescripts start\",\n - \"build\": \"react-scripts build\",\n + \"build\": \"rescripts build\",\n - \"test\": \"react-scripts test\",\n + \"test\": \"rescripts test\",\n - \"eject\": \"react-scripts eject\"\n ```\n\n### React MicroApp Component\n\n1. Install\n\n```bash\nnpm i qiankun\nnpm i @qiankunjs/react\n```\n\n2. Usage\n\nLoad (or unload) child applications directly through the `` component, which provides loading and error catching-related capabilities:\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\n### Vue Micro Application\n\nTake the `vue 2.x` project generated by `vue-cli 3+` as an example, and add it after the `vue 3` version becomes stable.\n\n1. Add `public-path.js` in the `src` directory:\n\n ```js\n if (window.__POWERED_BY_QIANKUN__) {\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n }\n ```\n\n2. The entry file `main.js` is modified. In order to avoid the root id `#app` from conflicting with other DOMs, the search scope needs to be limited.\n\n ```js\n import './public-path';\n import Vue from 'vue';\n import VueRouter from 'vue-router';\n import App from './App.vue';\n import routes from './router';\n import store from './store';\n\n Vue.config.productionTip = false;\n\n let router = null;\n let instance = null;\n function render(props = {}) {\n const { container } = props;\n router = new VueRouter({\n base: window.__POWERED_BY_QIANKUN__ ? '/app-vue/' : '/',\n mode: 'history',\n routes,\n });\n\n instance = new Vue({\n router,\n store,\n render: (h) => h(App),\n }).$mount(container ? container.querySelector('#app') : '#app');\n }\n\n // when run independently\n if (!window.__POWERED_BY_QIANKUN__) {\n render();\n }\n\n export async function bootstrap() {\n console.log('[vue] vue app bootstraped');\n }\n export async function mount(props) {\n console.log('[vue] props from main framework', props);\n render(props);\n }\n export async function unmount() {\n instance.$destroy();\n instance.$el.innerHTML = '';\n instance = null;\n router = null;\n }\n ```\n\n3. Modify `webpack` configuration（`vue.config.js`）:\n\n ```js\n const { name } = require('./package');\n module.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n configureWebpack: {\n output: {\n library: `${name}-[name]`,\n libraryTarget: 'umd', // bundle the micro app into umd library format\n jsonpFunction: `webpackJsonp_${name}`,\n },\n },\n };\n ```\n\n### Vue MicroApp Component\n1. Install\n\n```bash\nnpm i qiankun\nnpm i @qiankunjs/vue\n```\n\n2. Usage\n\nLoad (or unload) child apps directly through the `` component, which provides loading and error catching-related capabilities:\n\n```vue\n\n\n\n```\n\n### Angular micro app\n\nTake the `angular 9` project generated by `Angular-cli 9` as an example, other versions of `angular` will be added later.\n\n1. Add the file `public-path.js` in the `src` directory with the content:\n\n ```js\n if (window.__POWERED_BY_QIANKUN__) {\n // eslint-disable-next-line no-undef\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n }\n ```\n\n2. Set the `base` of `history` mode routing, `src/app/app-routing.module.ts` file:\n\n ```diff\n + import { APP_BASE_HREF } from '@angular/common';\n\n @NgModule({\n imports: [RouterModule.forRoot(routes)],\n exports: [RouterModule],\n // @ts-ignore\n + providers: [{ provide: APP_BASE_HREF, useValue: window.__POWERED_BY_QIANKUN__ ? '/app-angular' : '/' }]\n })\n ```\n\n3. Modify the entry file, `src/main.ts` file:\n\n ```ts\n import './public-path';\n import { enableProdMode, NgModuleRef } from '@angular/core';\n import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';\n import { AppModule } from './app/app.module';\n import { environment } from './environments/environment';\n\n if (environment.production) {\n enableProdMode();\n }\n\n let app: void | NgModuleRef;\n async function render() {\n app = await platformBrowserDynamic()\n .bootstrapModule(AppModule)\n .catch((err) => console.error(err));\n }\n if (!(window as any).__POWERED_BY_QIANKUN__) {\n render();\n }\n\n export async function bootstrap(props: Object) {\n console.log(props);\n }\n\n export async function mount(props: Object) {\n render();\n }\n\n export async function unmount(props: Object) {\n console.log(props);\n // @ts-ignore\n app.destroy();\n }\n ```\n\n4. Modify `webpack` bundling configuration\n\n First install the `@angular-builders/custom-webpack` plugin. **Note: `Angular 9` project can only install `9.x` version, `angular 10` project can install the latest version**.\n\n ```bash\n npm i @angular-builders/custom-webpack@9.2.0 -D\n ```\n\n Add `custom-webpack.config.js` to the root directory with the content:\n\n ```js\n const appName = require('./package.json').name;\n module.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n output: {\n library: `${appName}-[name]`,\n libraryTarget: 'umd',\n jsonpFunction: `webpackJsonp_${appName}`,\n },\n };\n ```\n\n Modify `angular.json`, change the values of `[packageName]> architect> build> builder` and `[packageName]> architect> serve> builder` to the plugins we installed, and add our webpack's configuration file to `[ packageName]> architect> build> options`.\n\n ```diff\n - \"builder\": \"@angular-devkit/build-angular:browser\",\n + \"builder\": \"@angular-builders/custom-webpack:browser\",\n \"options\": {\n + \"customWebpackConfig\": {\n + \"path\": \"./custom-webpack.config.js\"\n + }\n }\n ```\n\n ```diff\n - \"builder\": \"@angular-devkit/build-angular:dev-server\",\n + \"builder\": \"@angular-builders/dev-server:generic\",\n ```\n\n5. Solve the problem of `zone.js`\n\n Import `zone.js` in **main app**, it needs to be imported before `import qiankun`.\n\n Delete the code of import `zone.js` in the `src/polyfills.ts` of the micro app.\n\n ```diff\n - import 'zone.js/dist/zone';\n ```\n\n Add the following content to the `` tag in the `src/index.html` of the micro app, which is used when the micro app is accessed independently.\n\n ```html\n \n \n ```\n\n6. Fix `ng build` comand's error report, modify `tsconfig.json` file, reference[issues/431](https://github.com/umijs/qiankun/issues/431).\n\n ```diff\n - \"target\": \"es2015\",\n + \"target\": \"es5\",\n + \"typeRoots\": [\n + \"node_modules/@types\"\n + ],\n ```\n\n7. In order to prevent the conflict of `` when the main app or other micro apps are also `angular`, it is recommended to add a unique id to ``, such as Say the current app name.\n\n src/index.html :\n\n ```diff\n - \n + \n ```\n\n src/app/app.component.ts :\n\n ```diff\n - selector: 'app-root',\n + selector: '#angular9 app-root',\n ```\n\nOf course, you can also choose to use the `single-spa-angular` plugin, refer to[ single-spa-angular official website](https://single-spa.js.org/docs/ecosystem-angular) 和 [angular demo](https://github.com/umijs/qiankun/tree/master/examples/angular9)\n\n（**supplement**）The angular7 has the same steps as angular9 except for step 4. The steps for angular7 to modify the `webpack` configuration are as follows:\n\nIn addition to installing the 7.x version of `angular-builders/custom-webpack`, you also need to install `angular-builders/dev-server`.\n\n```bash\nnpm i @angular-builders/custom-webpack@7 -D\nnpm i @angular-builders/dev-server -D\n```\n\nAdd `custom-webpack.config.js` to the root directory, same as above.\n\nModify `angular.json`, `[packageName] > architect > build > builder` is the same as Angular9, and `[packageName] > architect > serve > builder` is different from Angular9.\n\n```diff\n- \"builder\": \"@angular-devkit/build-angular:browser\",\n+ \"builder\": \"@angular-builders/custom-webpack:browser\",\n \"options\": {\n \"customWebpackConfig\": {\n \"path\": \"./custom-webpack.config.js\"\n }\n }\n\n```\n\n```diff\n- \"builder\": \"@angular-devkit/build-angular:dev-server\",\n+ \"builder\": \"@angular-builders/dev-server:generic\",\n```\n\n### Micro app built without webpack\n\nSome apps that are not built by `webpack`, such as `jQuery` app, `jsp` app, can be handled according to this.\n\nBefore modify, please make sure that the resources such as pictures, audio and video in your project can be loaded normally. If the addresses of these resources are all full paths (for example, `https://qiankun.umijs.org/logo.png`), there is no problem. If they are all relative paths, you need to upload these resources to the server first and reference the full path.\n\nThe only change is that we need to declare a script tag, to export the `lifecycles`\n\nexample:\n\n1. declare entry script\n\n ```diff\n \n \n \n \n \n Purehtml Example\n \n \n
\n Purehtml Example\n
\n \n\n + \n \n ```\n\n2. export lifecycles in the entry\n\n ```javascript\n const render = ($) => {\n $('#purehtml-container').html('Hello, render with jQuery');\n return Promise.resolve();\n };\n\n ((global) => {\n global['purehtml'] = {\n bootstrap: () => {\n console.log('purehtml bootstrap');\n return Promise.resolve();\n },\n mount: () => {\n console.log('purehtml mount');\n return render($);\n },\n unmount: () => {\n console.log('purehtml unmount');\n return Promise.resolve();\n },\n };\n })(window);\n ```\n\nrefer to the [purehtml examples](https://github.com/umijs/qiankun/tree/master/examples/purehtml)\n\nAt the same time, [the subApp must support the CORS](/faq#must-a-sub-app-asset-support-cors)\n\n### umi-qiankun app\n\nFor the tutorial of `umi-qiankun`, please go to [umi official website](https://umijs.org/zh-CN/plugins/plugin-qiankun) and [umi-qiankun official demo](https://github.com/umijs/umi-plugin-qiankun/tree/master/examples)\n\n```\n" }, { "path": "docs/index.md", "content": "---\nlayout: home\n\nhero:\n name: Qiankun\n text: Micro-Frontend Solution\n tagline: Probably the most complete micro-frontends solution you ever met🧐\n image:\n src: /logo.png\n alt: Qiankun\n actions:\n - theme: brand\n text: Get Started\n link: /guide/quick-start\n - theme: alt\n text: View on GitHub\n link: https://github.com/umijs/qiankun\n\nfeatures:\n - icon: 🚀\n title: Simple\n details: Works with any javascript framework. Build your micro-frontend system just like using with iframe, but not iframe actually.\n - icon: 🛡️\n title: Complete\n details: Includes almost all the basic capabilities required to build a micro-frontend system, such as style isolation, js sandbox, preloading, and so on.\n - icon: 🔧\n title: Production-Ready\n details: Had been extensively tested and polished by a large number of online applications both inside and outside of Ant Financial, the robustness is trustworthy.\n - icon: ⚡\n title: High Performance\n details: Supports application preloading to optimize user experience and improve application switching speed.\n - icon: 🎯\n title: Technology Agnostic\n details: The main application does not limit the technology stack of accessing applications, and micro applications have complete autonomy.\n - icon: 🔄\n title: State Isolation\n details: Provides a complete JS sandbox mechanism to ensure that applications do not affect each other.\n---\n\n## 📦 Installation\n\n::: code-group\n\n```bash [npm]\nnpm install qiankun\n```\n\n```bash [yarn]\nyarn add qiankun\n```\n\n```bash [pnpm]\npnpm add qiankun\n```\n\n:::\n\n## 🔨 Quick Start\n\n### Main Application\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\n// register micro apps\nregisterMicroApps([\n {\n name: 'reactApp',\n entry: '//localhost:7100',\n container: '#yourContainer',\n activeRule: '/yourActiveRule',\n },\n {\n name: 'vueApp',\n entry: { scripts: ['//localhost:7100/main.js'] },\n container: '#yourContainer2',\n activeRule: '/yourActiveRule2',\n },\n]);\n\n// start qiankun\nstart();\n```\n\n### Micro Application\n\n```typescript\n/**\n * bootstrap will only be called once when the micro application is initialized\n * mount will be called every time the micro application enters\n * unmount will be called every time the micro application leaves\n */\nexport async function bootstrap() {\n console.log('react app bootstraped');\n}\n\nexport async function mount(props) {\n ReactDOM.render(, props.container ? props.container.querySelector('#root') : document.getElementById('root'));\n}\n\nexport async function unmount(props) {\n ReactDOM.unmountComponentAtNode(\n props.container ? props.container.querySelector('#root') : document.getElementById('root'),\n );\n}\n```\n\n## 🌟 Why qiankun?\n\n
\n
\n

🎯 Zero Intrusion

\n

Almost no intrusion to existing applications, only need to expose necessary lifecycle functions

\n
\n\n
\n

📱 All Scenarios

\n

Supports both route-based and manual loading of micro applications

\n
\n\n
\n

🔒 Secure Isolation

\n

Complete sandbox solution with JS isolation and CSS isolation

\n
\n\n
\n

⚡ High Performance

\n

Supports preloading, caching and other performance optimization solutions

\n
\n
\n\n## 👥 Community\n\n| GitHub Discussions | DingTalk Group | WeChat Group |\n| --- | --- | --- |\n| [qiankun discussions](https://github.com/umijs/qiankun/discussions) | \"DingTalk | [view group QR code](https://github.com/umijs/qiankun/discussions/2343) |\n\n \n" }, { "path": "docs/zh-CN/api/configuration.md", "content": "# Configuration\n\nqiankun 提供灵活的配置选项来自定义微前端应用的行为。本文档涵盖了不同用例的所有可用配置选项。\n\n## 📋 配置类型\n\n### AppConfiguration\n\n与 `loadMicroApp` 一起使用的单个微应用配置。\n\n```typescript\ntype AppConfiguration = {\n sandbox?: boolean;\n globalContext?: WindowProxy;\n fetch?: Function;\n streamTransformer?: Function;\n nodeTransformer?: Function;\n};\n```\n\n### StartOpts\n\n与 `start()` 一起使用的启动 qiankun 框架的配置。\n\n```typescript\ninterface StartOpts {\n prefetch?: boolean | 'all' | string[] | ((apps: RegistrableApp[]) => { criticalAppNames: string[]; minorAppsName: string[] });\n sandbox?: boolean | { strictStyleIsolation?: boolean; experimentalStyleIsolation?: boolean; };\n singular?: boolean;\n urlRerouteOnly?: boolean;\n // ... other single-spa options\n}\n```\n\n## ⚙️ 应用配置选项\n\n### sandbox\n\n**类型**: `boolean` \n**默认值**: `true` \n**描述**: 为微应用启用沙箱隔离。\n\n#### 基础用法\n\n```typescript\n// Enable sandbox (default)\nloadMicroApp({\n name: 'my-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n sandbox: true\n});\n\n// Disable sandbox (not recommended)\nloadMicroApp({\n name: 'legacy-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n sandbox: false\n});\n```\n\n#### 为什么使用沙箱？\n\n```typescript\n// With sandbox enabled, global variables are isolated\nloadMicroApp({\n name: 'app1',\n entry: '//localhost:8001',\n container: '#container1',\n}, {\n sandbox: true // app1 gets its own global scope\n});\n\nloadMicroApp({\n name: 'app2', \n entry: '//localhost:8002',\n container: '#container2',\n}, {\n sandbox: true // app2 gets its own isolated global scope\n});\n```\n\n### globalContext\n\n**类型**: `WindowProxy` \n**默认值**: `window` \n**描述**: 微应用的自定义全局上下文。\n\n```typescript\n// Create a custom global context\nconst customGlobal = new Proxy(window, {\n get(target, prop) {\n // Custom logic for property access\n if (prop === 'customAPI') {\n return { version: '1.0' };\n }\n return target[prop];\n }\n});\n\nloadMicroApp({\n name: 'custom-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n globalContext: customGlobal\n});\n```\n\n### fetch\n\n**类型**: `Function` \n**默认值**: `window.fetch` \n**描述**: 用于加载应用资源的自定义 fetch 函数。\n\n#### 自定义头部\n\n```typescript\nconst customFetch = async (url, options) => {\n return fetch(url, {\n ...options,\n headers: {\n ...options?.headers,\n 'Authorization': `Bearer ${getToken()}`,\n 'X-Custom-Header': 'custom-value'\n }\n });\n};\n\nloadMicroApp({\n name: 'authenticated-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n fetch: customFetch\n});\n```\n\n#### 请求转换\n\n```typescript\nconst transformFetch = async (url, options) => {\n // Transform URLs\n const transformedUrl = url.replace('//localhost', '//production-domain');\n \n // Add custom logic\n console.log(`Fetching: ${transformedUrl}`);\n \n const response = await fetch(transformedUrl, options);\n \n // Transform response\n if (!response.ok) {\n throw new Error(`Failed to fetch ${transformedUrl}: ${response.status}`);\n }\n \n return response;\n};\n```\n\n#### 缓存策略\n\n```typescript\nconst cache = new Map();\n\nconst cachingFetch = async (url, options) => {\n const cacheKey = `${url}${JSON.stringify(options)}`;\n \n if (cache.has(cacheKey)) {\n console.log(`Cache hit for ${url}`);\n return cache.get(cacheKey);\n }\n \n const response = await fetch(url, options);\n cache.set(cacheKey, response.clone());\n \n return response;\n};\n```\n\n### streamTransformer\n\n**类型**: `Function` \n**描述**: 在加载过程中转换流式 HTML 内容。\n\n```typescript\nconst customStreamTransformer = (stream) => {\n return stream.pipeThrough(new TransformStream({\n transform(chunk, controller) {\n // Transform HTML chunks\n const transformedChunk = chunk\n .replace(/old-api/g, 'new-api')\n .replace(/deprecated-feature/g, 'updated-feature');\n \n controller.enqueue(transformedChunk);\n }\n }));\n};\n\nloadMicroApp({\n name: 'streaming-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n streamTransformer: customStreamTransformer\n});\n```\n\n### nodeTransformer\n\n**类型**: `Function` \n**描述**: 在应用加载过程中转换 DOM 节点。\n\n```typescript\nconst customNodeTransformer = (node, options) => {\n // Transform script tags\n if (node.tagName === 'SCRIPT') {\n // Add custom attributes\n node.setAttribute('data-app', 'my-app');\n \n // Modify script source\n if (node.src) {\n node.src = node.src.replace('localhost', 'production-domain');\n }\n }\n \n // Transform style tags\n if (node.tagName === 'STYLE') {\n // Add CSS scope\n node.textContent = `.app-scope { ${node.textContent} }`;\n }\n \n return node;\n};\n\nloadMicroApp({\n name: 'transformed-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n nodeTransformer: customNodeTransformer\n});\n```\n\n## 🚀 启动配置选项\n\n### prefetch\n\n**类型**: `boolean | 'all' | string[] | Function` \n**默认值**: `true` \n**描述**: 用于提升性能的资源预取策略。\n\n#### 布尔值\n\n```typescript\n// Disable prefetch\nstart({ prefetch: false });\n\n// Enable default prefetch\nstart({ prefetch: true });\n```\n\n#### 预取所有\n\n```typescript\n// Prefetch all registered micro apps\nstart({ prefetch: 'all' });\n```\n\n#### 选择性预取\n\n```typescript\n// Prefetch specific apps\nstart({ \n prefetch: ['dashboard', 'user-profile', 'analytics'] \n});\n```\n\n#### 动态预取策略\n\n```typescript\nstart({\n prefetch: (apps) => {\n // Business logic to determine prefetch strategy\n const currentTime = new Date().getHours();\n const isBusinessHours = currentTime >= 9 && currentTime <= 17;\n \n if (isBusinessHours) {\n // Prefetch business-critical apps during business hours\n return {\n criticalAppNames: ['dashboard', 'crm', 'finance'],\n minorAppsName: ['reporting', 'settings']\n };\n } else {\n // Minimal prefetch during off-hours\n return {\n criticalAppNames: ['dashboard'],\n minorAppsName: []\n };\n }\n }\n});\n```\n\n#### 基于用户的预取\n\n```typescript\nstart({\n prefetch: (apps) => {\n const userRole = getCurrentUserRole();\n \n switch (userRole) {\n case 'admin':\n return {\n criticalAppNames: ['admin-panel', 'user-management', 'system-monitor'],\n minorAppsName: ['reports', 'settings']\n };\n case 'user':\n return {\n criticalAppNames: ['dashboard', 'profile'],\n minorAppsName: ['help', 'feedback']\n };\n default:\n return {\n criticalAppNames: ['dashboard'],\n minorAppsName: []\n };\n }\n }\n});\n```\n\n### sandbox\n\n**类型**: `boolean | SandboxConfig` \n**默认值**: `true` \n**描述**: 所有微应用的全局沙箱配置。\n\n#### 基础沙箱\n\n```typescript\n// Enable sandbox for all apps\nstart({ sandbox: true });\n\n// Disable sandbox for all apps (not recommended)\nstart({ sandbox: false });\n```\n\n#### 高级沙箱配置\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // Enable Shadow DOM style isolation\n experimentalStyleIsolation: true, // Enable scoped CSS style isolation\n }\n});\n```\n\n#### 样式隔离选项\n\n**strictStyleIsolation**: 使用 Shadow DOM 来完全隔离样式\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // Strongest isolation but may break some UI libraries\n }\n});\n```\n\n**experimentalStyleIsolation**: 使用作用域 CSS 来隔离样式\n```typescript\nstart({\n sandbox: {\n experimentalStyleIsolation: true, // Good balance of isolation and compatibility\n }\n});\n```\n\n#### 组合样式隔离\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: false, // Disable Shadow DOM\n experimentalStyleIsolation: true, // Enable scoped CSS\n }\n});\n```\n\n### singular\n\n**类型**: `boolean` \n**默认值**: `true` \n**描述**: 是否同时只能挂载一个微应用。\n\n```typescript\n// Only one app at a time (default)\nstart({ singular: true });\n\n// Allow multiple apps simultaneously\nstart({ \n singular: false // Useful for dashboard-style applications\n});\n```\n\n#### 多应用用例\n\n```typescript\n// Dashboard with multiple widgets\nstart({ \n singular: false,\n // Other configurations\n});\n\n// Register widget-style micro apps\nregisterMicroApps([\n { name: 'widget-weather', entry: '//localhost:8001', container: '#widget-1', activeRule: '/dashboard' },\n { name: 'widget-stocks', entry: '//localhost:8002', container: '#widget-2', activeRule: '/dashboard' },\n { name: 'widget-news', entry: '//localhost:8003', container: '#widget-3', activeRule: '/dashboard' },\n]);\n```\n\n### urlRerouteOnly\n\n**类型**: `boolean` \n**默认值**: `true` \n**描述**: 是否仅在 URL 变化时触发路由。\n\n```typescript\n// Only route on URL changes (default)\nstart({ urlRerouteOnly: true });\n\n// Route on both URL and programmatic changes\nstart({ \n urlRerouteOnly: false // More responsive but potentially more performance overhead\n});\n```\n\n## 🔧 基于环境的配置\n\n### 开发配置\n\n```typescript\nconst developmentConfig = {\n prefetch: false, // Faster rebuilds\n sandbox: {\n strictStyleIsolation: false, // Easier debugging\n experimentalStyleIsolation: true,\n },\n singular: false, // More flexible development\n urlRerouteOnly: false, // More responsive navigation\n};\n\nif (process.env.NODE_ENV === 'development') {\n start(developmentConfig);\n}\n```\n\n### 生产配置\n\n```typescript\nconst productionConfig = {\n prefetch: 'all', // Better user experience\n sandbox: {\n strictStyleIsolation: true, // Better isolation\n experimentalStyleIsolation: false,\n },\n singular: true, // Stable performance\n urlRerouteOnly: true, // Optimized routing\n};\n\nif (process.env.NODE_ENV === 'production') {\n start(productionConfig);\n}\n```\n\n### 移动端配置\n\n```typescript\nconst mobileConfig = {\n prefetch: (apps) => ({\n // Conservative prefetch on mobile\n criticalAppNames: ['home'],\n minorAppsName: []\n }),\n sandbox: {\n // Lighter sandbox for mobile performance\n strictStyleIsolation: false,\n experimentalStyleIsolation: true,\n },\n singular: true, // Better for mobile UX\n};\n\nconst isMobile = window.innerWidth < 768;\nif (isMobile) {\n start(mobileConfig);\n}\n```\n\n## 🎯 高级配置模式\n\n### 1. 特性标志集成\n\n```typescript\nconst getConfigWithFeatureFlags = async () => {\n const featureFlags = await getFeatureFlags();\n \n return {\n prefetch: featureFlags.enablePrefetch ? 'all' : false,\n sandbox: {\n strictStyleIsolation: featureFlags.strictIsolation,\n experimentalStyleIsolation: !featureFlags.strictIsolation,\n },\n singular: featureFlags.allowMultipleApps ? false : true,\n };\n};\n\ngetConfigWithFeatureFlags().then(config => start(config));\n```\n\n### 2. 基于性能的配置\n\n```typescript\nconst getPerformanceConfig = () => {\n const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;\n const isSlowConnection = connection?.effectiveType === '2g' || connection?.effectiveType === 'slow-2g';\n \n if (isSlowConnection) {\n return {\n prefetch: false, // No prefetch on slow connections\n sandbox: {\n strictStyleIsolation: false,\n experimentalStyleIsolation: true,\n },\n singular: true,\n };\n }\n \n return {\n prefetch: 'all',\n sandbox: {\n strictStyleIsolation: true,\n experimentalStyleIsolation: false,\n },\n singular: false,\n };\n};\n\nstart(getPerformanceConfig());\n```\n\n### 3. 基于用户角色的配置\n\n```typescript\nconst getRoleBasedConfig = (userRole) => {\n const baseConfig = {\n sandbox: true,\n singular: true,\n };\n \n switch (userRole) {\n case 'admin':\n return {\n ...baseConfig,\n prefetch: 'all', // Admins get all features\n singular: false, // Can use multiple admin tools\n };\n case 'poweruser':\n return {\n ...baseConfig,\n prefetch: ['dashboard', 'analytics', 'reports'],\n singular: false,\n };\n default:\n return {\n ...baseConfig,\n prefetch: ['dashboard'], // Basic users get minimal prefetch\n singular: true,\n };\n }\n};\n\nconst userRole = getCurrentUserRole();\nstart(getRoleBasedConfig(userRole));\n```\n\n## ⚠️ 重要注意事项\n\n### 1. 配置优先级\n\n```typescript\n// App-level configuration overrides global configuration\nstart({\n sandbox: true, // Global setting\n});\n\nloadMicroApp({\n name: 'special-app',\n entry: '//localhost:8080',\n container: '#container',\n}, {\n sandbox: false // This overrides the global setting for this app\n});\n```\n\n### 2. 性能考虑\n\n```typescript\n// ❌ 错误：影响性能的重配置\nstart({\n prefetch: 'all', // Might slow down initial load\n sandbox: {\n strictStyleIsolation: true, // More overhead\n },\n singular: false, // More memory usage\n urlRerouteOnly: false, // More frequent route checks\n});\n\n// ✅ 正确：平衡的配置\nstart({\n prefetch: ['critical-app'], // Only prefetch what's needed\n sandbox: {\n experimentalStyleIsolation: true, // Good balance\n },\n singular: true, // Stable performance\n urlRerouteOnly: true, // Optimized routing\n});\n```\n\n### 3. 调试配置\n\n```typescript\nconst debugConfig = {\n sandbox: {\n strictStyleIsolation: false, // Easier to inspect styles\n experimentalStyleIsolation: true,\n },\n // Custom fetch for logging\n fetch: async (url, options) => {\n console.log(`[DEBUG] Fetching: ${url}`);\n const response = await fetch(url, options);\n console.log(`[DEBUG] Response: ${response.status}`);\n return response;\n },\n // Custom node transformer for debugging\n nodeTransformer: (node, options) => {\n if (node.tagName === 'SCRIPT') {\n console.log(`[DEBUG] Processing script: ${node.src || 'inline'}`);\n }\n return node;\n }\n};\n```\n\n## 🔗 相关 API\n\n- [start](/zh-CN/api/start) - 使用配置启动 qiankun\n- [loadMicroApp](/zh-CN/api/load-micro-app) - 使用配置加载应用\n- [registerMicroApps](/zh-CN/api/register-micro-apps) - 注册应用 " }, { "path": "docs/zh-CN/api/index.md", "content": "# API 参考\n\nqiankun 提供了简洁而强大的 API 来构建微前端应用。所有 API 都提供了完整的 TypeScript 类型定义，确保开发体验和类型安全。\n\n## 📚 核心 API\n\n### 应用注册与启动\n\n| API | 描述 | 类型 |\n|-----|------|------|\n| [`registerMicroApps`](/zh-CN/api/register-micro-apps) | 注册微应用 | `(apps: RegistrableApp[], lifeCycles?: LifeCycles) => void` |\n| [`start`](/zh-CN/api/start) | 启动 qiankun 框架 | `(opts?: StartOpts) => void` |\n| [`loadMicroApp`](/zh-CN/api/load-micro-app) | 手动加载微应用 | `(app: LoadableApp, configuration?: AppConfiguration, lifeCycles?: LifeCycles) => MicroApp` |\n\n### 工具 API\n\n| API | 描述 | 类型 |\n|-----|------|------|\n| [`isRuntimeCompatible`](/zh-CN/api/is-runtime-compatible) | 检查运行时兼容性 | `() => boolean` |\n\n## 🎯 快速导航\n\n### 按使用场景\n\n**路由模式**\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\n// 1. 注册微应用\nregisterMicroApps([...]);\n\n// 2. 启动框架\nstart();\n```\n\n**手动加载模式**\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\n// 手动加载微应用\nconst microApp = loadMicroApp({...});\n```\n\n**兼容性检查**\n```typescript\nimport { isRuntimeCompatible } from 'qiankun';\n\nif (isRuntimeCompatible()) {\n // 启动微前端应用\n}\n```\n\n### 按功能分类\n\n| 分类 | 相关 API | 描述 |\n|------|----------|------|\n| **应用管理** | `registerMicroApps`, `loadMicroApp` | 注册和加载微应用 |\n| **框架控制** | `start` | 框架启动和配置 |\n| **工具函数** | `isRuntimeCompatible` | 辅助工具方法 |\n\n## 🔧 类型定义\n\nqiankun 提供了完整的 TypeScript 类型定义：\n\n```typescript\nimport type {\n RegistrableApp,\n LoadableApp,\n MicroApp,\n LifeCycles,\n AppConfiguration,\n} from 'qiankun';\n```\n\n详细信息请参考 [类型定义](/zh-CN/api/types)。\n\n## 📖 详细文档\n\n### 核心 API\n- [registerMicroApps](/zh-CN/api/register-micro-apps) - 注册微应用\n- [start](/zh-CN/api/start) - 启动 qiankun 框架\n- [loadMicroApp](/zh-CN/api/load-micro-app) - 手动加载微应用\n- [isRuntimeCompatible](/zh-CN/api/is-runtime-compatible) - 运行时兼容性检查\n\n### 参考文档\n- [生命周期](/zh-CN/api/lifecycles) - 应用生命周期钩子\n- [配置选项](/zh-CN/api/configuration) - 框架配置选项\n- [类型定义](/zh-CN/api/types) - TypeScript 类型定义\n\n## 💡 使用建议\n\n### 推荐的 API 使用模式\n\n1. **标准路由模式**（推荐）\n ```typescript\n registerMicroApps([...]) → start()\n ```\n\n2. **动态加载模式**\n ```typescript\n loadMicroApp({...}) \n ```\n\n3. **混合模式**\n ```typescript\n registerMicroApps([...]) → start() + loadMicroApp({...})\n ```\n\n### 最佳实践\n\n- ✅ 使用 TypeScript 获得完整的类型支持\n- ✅ 在启动框架前注册所有微应用\n- ✅ 适当使用生命周期钩子进行状态管理\n- ✅ 配置适当的错误处理\n\n- ❌ 避免注册重复的应用名称\n- ❌ 避免在微应用中调用主应用 API\n- ❌ 避免在生命周期钩子中执行耗时操作 " }, { "path": "docs/zh-CN/api/is-runtime-compatible.md", "content": "# isRuntimeCompatible\n\n检查当前浏览器环境是否与 qiankun 运行时特性兼容。\n\n## 🎯 函数签名\n\n```typescript\nfunction isRuntimeCompatible(): boolean\n```\n\n## 📋 参数\n\n此函数不接受任何参数。\n\n## 🔄 返回值\n\n- **类型**: `boolean`\n- **描述**: 如果当前环境支持 qiankun 特性则返回 `true`，否则返回 `false`。\n\n## 💡 使用示例\n\n### 基础兼容性检查\n\n```typescript\nimport { isRuntimeCompatible, registerMicroApps, start } from 'qiankun';\n\nif (isRuntimeCompatible()) {\n // Environment supports qiankun\n registerMicroApps([...]);\n start();\n} else {\n // Fallback for unsupported browsers\n console.warn('Current browser does not support qiankun');\n initFallbackRouting();\n}\n```\n\n### 带优雅降级\n\n```typescript\nfunction initApplication() {\n if (isRuntimeCompatible()) {\n // Use qiankun micro-frontend architecture\n initMicroFrontend();\n } else {\n // Fall back to traditional SPA\n initTraditionalSPA();\n }\n}\n\nfunction initMicroFrontend() {\n registerMicroApps([\n {\n name: 'module-a',\n entry: '//localhost:8001',\n container: '#container',\n activeRule: '/module-a',\n }\n ]);\n start();\n}\n\nfunction initTraditionalSPA() {\n // Traditional routing setup\n import('./traditional-router').then(router => {\n router.init();\n });\n}\n```\n\n## 🔍 检查内容\n\n`isRuntimeCompatible` 函数检查以下浏览器特性：\n\n### 必需特性\n\n1. **Proxy 支持**：用于 JavaScript 沙箱隔离\n2. **Window.Proxy**：创建隔离执行上下文的必要条件\n3. **Import Maps**（使用时）：用于动态模块加载\n4. **Dynamic Import**：用于加载微应用\n\n### 浏览器兼容性\n\n| 浏览器 | 最低版本 | 支持程度 |\n|---------|---------|---------|\n| Chrome | 61+ | ✅ 完全支持 |\n| Firefox | 60+ | ✅ 完全支持 |\n| Safari | 11+ | ✅ 完全支持 |\n| Edge | 79+ | ✅ 完全支持 |\n| IE | 任何版本 | ❌ 不支持 |\n\n## 🚀 最佳实践\n\n### 1. 早期检测\n\n```typescript\n// Check compatibility before any qiankun setup\nfunction bootstrap() {\n if (!isRuntimeCompatible()) {\n showUnsupportedBrowserMessage();\n return;\n }\n\n // Safe to proceed with qiankun\n setupMicroFrontend();\n}\n```\n\n### 2. 渐进增强\n\n```typescript\nclass ApplicationBootstrap {\n private isQiankunSupported = isRuntimeCompatible();\n\n init() {\n if (this.isQiankunSupported) {\n this.initWithMicroFrontend();\n } else {\n this.initWithoutMicroFrontend();\n }\n }\n\n private initWithMicroFrontend() {\n // Full micro-frontend experience\n registerMicroApps([...]);\n start();\n }\n\n private initWithoutMicroFrontend() {\n // Simplified experience for unsupported browsers\n this.loadAllModulesDirectly();\n }\n}\n```\n\n### 3. 用户沟通\n\n```typescript\nif (!isRuntimeCompatible()) {\n // Show user-friendly message\n const banner = document.createElement('div');\n banner.innerHTML = `\n
\n Browser Compatibility Notice:\n For the best experience, please use a modern browser like Chrome, Firefox, or Safari.\n Some features may be limited in your current browser.\n
\n `;\n document.body.insertBefore(banner, document.body.firstChild);\n}\n```\n\n## 🔧 集成模式\n\n### 1. 带特性标志\n\n```typescript\nconst featureFlags = {\n useMicroFrontend: isRuntimeCompatible() && process.env.ENABLE_MICRO_FRONTEND,\n useAdvancedFeatures: isRuntimeCompatible(),\n};\n\nif (featureFlags.useMicroFrontend) {\n // Full micro-frontend setup\n registerMicroApps([...]);\n start();\n} else {\n // Traditional setup\n initTraditionalApp();\n}\n```\n\n### 2. 带分析统计\n\n```typescript\n// Track browser compatibility for analytics\nconst compatible = isRuntimeCompatible();\n\n// Send analytics event\nanalytics.track('browser_compatibility_check', {\n compatible,\n userAgent: navigator.userAgent,\n timestamp: Date.now(),\n});\n\nif (compatible) {\n initQiankunApp();\n} else {\n initFallbackApp();\n}\n```\n\n### 3. 带动态加载\n\n```typescript\nasync function loadApplicationFramework() {\n if (isRuntimeCompatible()) {\n // Load qiankun and micro-frontend modules\n const [qiankun, microApps] = await Promise.all([\n import('qiankun'),\n import('./micro-apps-config'),\n ]);\n \n qiankun.registerMicroApps(microApps.default);\n qiankun.start();\n } else {\n // Load traditional SPA modules\n const traditionalApp = await import('./traditional-app');\n traditionalApp.init();\n }\n}\n```\n\n## ⚠️ 重要注意事项\n\n### 1. 性能考虑\n\n```typescript\n// ✅ 正确：检查一次并缓存结果\nconst QIANKUN_COMPATIBLE = isRuntimeCompatible();\n\nfunction someFunction() {\n if (QIANKUN_COMPATIBLE) {\n // Use cached result\n }\n}\n\n// ❌ 错误：多次检查\nfunction someFunction() {\n if (isRuntimeCompatible()) { // Redundant check\n // ...\n }\n}\n```\n\n### 2. SSR 考虑\n\n```typescript\n// In SSR environments, check if window is available\nfunction safeCompatibilityCheck() {\n if (typeof window === 'undefined') {\n // SSR environment - assume compatible\n return true;\n }\n \n return isRuntimeCompatible();\n}\n```\n\n### 3. 测试环境\n\n```typescript\n// For testing, you might want to mock the compatibility\nif (process.env.NODE_ENV === 'test') {\n // Mock for testing\n global.mockQiankunCompatible = true;\n}\n\nfunction checkCompatibility() {\n if (process.env.NODE_ENV === 'test' && global.mockQiankunCompatible !== undefined) {\n return global.mockQiankunCompatible;\n }\n \n return isRuntimeCompatible();\n}\n```\n\n## 🎯 常见场景\n\n### 1. 企业环境\n\n```typescript\n// Corporate environments might have older browsers\nfunction initCorporateApp() {\n const compatible = isRuntimeCompatible();\n \n if (!compatible) {\n // Inform IT department about browser requirements\n logToAdminConsole('User browser incompatible with micro-frontend features');\n }\n \n return compatible ? initMicroFrontend() : initLegacyApp();\n}\n```\n\n### 2. 公共网站\n\n```typescript\n// Public websites need to support a wider range of browsers\nfunction initPublicSite() {\n if (isRuntimeCompatible()) {\n // Enhanced experience with micro-frontends\n loadAdvancedFeatures();\n } else {\n // Basic experience that works everywhere\n loadBasicFeatures();\n }\n}\n```\n\n### 3. 移动应用 WebView\n\n```typescript\n// Mobile WebViews might have different compatibility\nfunction initMobileWebView() {\n const compatible = isRuntimeCompatible();\n \n // Log for mobile app developers\n if (window.ReactNativeWebView) {\n window.ReactNativeWebView.postMessage(JSON.stringify({\n type: 'qiankun_compatibility',\n compatible,\n }));\n }\n \n return compatible ? initMicroFrontend() : initSimplifiedView();\n}\n```\n\n## 🔗 相关 API\n\n- [start](/zh-CN/api/start) - 启动 qiankun（应在兼容性检查后调用）\n- [registerMicroApps](/zh-CN/api/register-micro-apps) - 注册微应用\n- [loadMicroApp](/zh-CN/api/load-micro-app) - 手动加载微应用 " }, { "path": "docs/zh-CN/api/lifecycles.md", "content": "# Lifecycles\n\n生命周期钩子允许您在微应用生命周期的不同阶段执行自定义逻辑。这些钩子在应用加载、挂载和卸载过程中由 qiankun 自动执行。\n\n## 🎯 类型定义\n\n```typescript\nexport type LifeCycleFn = (\n app: LoadableApp, \n global: WindowProxy\n) => Promise;\n\nexport type LifeCycles = {\n beforeLoad?: LifeCycleFn | Array>;\n beforeMount?: LifeCycleFn | Array>;\n afterMount?: LifeCycleFn | Array>;\n beforeUnmount?: LifeCycleFn | Array>;\n afterUnmount?: LifeCycleFn | Array>;\n};\n```\n\n## 📋 可用的生命周期钩子\n\n### beforeLoad\n\n**时机**: 在微应用开始加载之前调用。\n\n**目的**: 在获取和解析应用代码之前执行设置任务。\n\n```typescript\nbeforeLoad: async (app, global) => {\n console.log(`About to load ${app.name}`);\n // Setup global configurations\n global.__INITIAL_CONFIG__ = getInitialConfig();\n}\n```\n\n### beforeMount\n\n**时机**: 在应用加载完成后但在挂载到 DOM 之前调用。\n\n**目的**: 在应用激活之前执行最终设置。\n\n```typescript\nbeforeMount: async (app, global) => {\n console.log(`About to mount ${app.name}`);\n // Initialize services\n await initializeServices();\n // Set loading state\n setLoadingState(false);\n}\n```\n\n### afterMount\n\n**时机**: 在微应用成功挂载后调用。\n\n**目的**: 执行挂载后操作，如分析、功能初始化等。\n\n```typescript\nafterMount: async (app, global) => {\n console.log(`${app.name} mounted successfully`);\n // Track analytics\n analytics.track('micro_app_mounted', { appName: app.name });\n // Initialize features that depend on DOM\n initializeDOMDependentFeatures();\n}\n```\n\n### beforeUnmount\n\n**时机**: 在微应用开始卸载之前调用。\n\n**目的**: 在应用被移除之前执行清理操作。\n\n```typescript\nbeforeUnmount: async (app, global) => {\n console.log(`About to unmount ${app.name}`);\n // Save application state\n saveApplicationState(app.name);\n // Cleanup event listeners\n cleanupEventListeners();\n}\n```\n\n### afterUnmount\n\n**时机**: 在微应用完全卸载后调用。\n\n**目的**: 最终清理和资源释放。\n\n```typescript\nafterUnmount: async (app, global) => {\n console.log(`${app.name} unmounted`);\n // Clear caches\n clearApplicationCache(app.name);\n // Reset global state\n resetGlobalState();\n}\n```\n\n## 🔄 生命周期流程\n\n```mermaid\ngraph TD\n A[Start Loading] --> B[beforeLoad]\n B --> C[Load Application Code]\n C --> D[beforeMount]\n D --> E[Mount Application]\n E --> F[afterMount]\n F --> G[Application Running]\n G --> H[beforeUnmount]\n H --> I[Unmount Application]\n I --> J[afterUnmount]\n J --> K[Application Cleaned Up]\n```\n\n## 💡 使用示例\n\n### 与 registerMicroApps 一起使用\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'react-app',\n entry: '//localhost:7100',\n container: '#subapp-viewport',\n activeRule: '/react',\n }\n], {\n beforeLoad: async (app) => {\n console.log('Loading app:', app.name);\n },\n afterMount: async (app) => {\n console.log('App mounted:', app.name);\n },\n beforeUnmount: async (app) => {\n console.log('Unmounting app:', app.name);\n }\n});\n\nstart();\n```\n\n### 与 loadMicroApp 一起使用\n\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst microApp = loadMicroApp({\n name: 'dashboard',\n entry: '//localhost:8080',\n container: '#dashboard-container',\n}, undefined, {\n beforeLoad: async (app, global) => {\n // Setup dashboard-specific configurations\n global.DASHBOARD_CONFIG = getDashboardConfig();\n },\n afterMount: async (app) => {\n // Initialize dashboard widgets\n initializeDashboardWidgets();\n }\n});\n```\n\n### 多个钩子\n\n```typescript\n// You can provide multiple hooks as an array\nconst lifecycles = {\n beforeMount: [\n async (app) => {\n await setupDatabase();\n },\n async (app) => {\n await setupAnalytics();\n },\n async (app) => {\n await setupFeatureFlags();\n }\n ],\n afterMount: [\n async (app) => {\n trackPageView(app.name);\n },\n async (app) => {\n initializeUserTracking();\n }\n ]\n};\n```\n\n## 🔧 高级模式\n\n### 1. 状态管理集成\n\n```typescript\nimport { store } from './store';\n\nconst lifecycles = {\n beforeLoad: async (app) => {\n // Set loading state\n store.dispatch({ type: 'SET_APP_LOADING', payload: { appName: app.name, loading: true } });\n },\n \n afterMount: async (app) => {\n // Update mounted apps list\n store.dispatch({ type: 'ADD_MOUNTED_APP', payload: app.name });\n store.dispatch({ type: 'SET_APP_LOADING', payload: { appName: app.name, loading: false } });\n },\n \n beforeUnmount: async (app) => {\n // Save app state before unmounting\n const appState = getAppState(app.name);\n store.dispatch({ type: 'SAVE_APP_STATE', payload: { appName: app.name, state: appState } });\n },\n \n afterUnmount: async (app) => {\n // Remove from mounted apps list\n store.dispatch({ type: 'REMOVE_MOUNTED_APP', payload: app.name });\n }\n};\n```\n\n### 2. 错误处理\n\n```typescript\nconst lifecycles = {\n beforeLoad: async (app) => {\n try {\n await performPreLoadChecks(app);\n } catch (error) {\n console.error(`Pre-load checks failed for ${app.name}:`, error);\n // Optionally prevent loading by throwing\n throw new Error(`Failed to initialize ${app.name}`);\n }\n },\n \n afterMount: async (app) => {\n try {\n await performPostMountTasks(app);\n } catch (error) {\n console.error(`Post-mount tasks failed for ${app.name}:`, error);\n // Log error but don't prevent the app from running\n reportError(error, { context: 'afterMount', appName: app.name });\n }\n }\n};\n```\n\n### 3. 性能监控\n\n```typescript\nconst performanceTracker = new Map();\n\nconst lifecycles = {\n beforeLoad: async (app) => {\n performanceTracker.set(app.name, {\n loadStart: performance.now()\n });\n },\n \n beforeMount: async (app) => {\n const timing = performanceTracker.get(app.name);\n timing.loadEnd = performance.now();\n timing.mountStart = performance.now();\n },\n \n afterMount: async (app) => {\n const timing = performanceTracker.get(app.name);\n timing.mountEnd = performance.now();\n \n // Calculate and report metrics\n const loadTime = timing.loadEnd - timing.loadStart;\n const mountTime = timing.mountEnd - timing.mountStart;\n \n analytics.track('micro_app_performance', {\n appName: app.name,\n loadTime,\n mountTime,\n totalTime: loadTime + mountTime\n });\n }\n};\n```\n\n### 4. 资源管理\n\n```typescript\nconst resourceMap = new Map();\n\nconst lifecycles = {\n beforeMount: async (app) => {\n // Allocate resources\n const resources = await allocateResources(app.name);\n resourceMap.set(app.name, resources);\n },\n \n beforeUnmount: async (app) => {\n // Save critical data\n const resources = resourceMap.get(app.name);\n if (resources) {\n await saveCriticalData(app.name, resources);\n }\n },\n \n afterUnmount: async (app) => {\n // Release resources\n const resources = resourceMap.get(app.name);\n if (resources) {\n await releaseResources(resources);\n resourceMap.delete(app.name);\n }\n }\n};\n```\n\n## 🎯 常见用例\n\n### 1. 加载状态\n\n```typescript\nconst loadingManager = {\n show: (appName) => {\n const loader = document.createElement('div');\n loader.id = `loader-${appName}`;\n loader.innerHTML = '
Loading...
';\n document.body.appendChild(loader);\n },\n \n hide: (appName) => {\n const loader = document.getElementById(`loader-${appName}`);\n if (loader) loader.remove();\n }\n};\n\nconst lifecycles = {\n beforeLoad: async (app) => {\n loadingManager.show(app.name);\n },\n \n afterMount: async (app) => {\n loadingManager.hide(app.name);\n }\n};\n```\n\n### 2. 身份验证检查\n\n```typescript\nconst lifecycles = {\n beforeLoad: async (app) => {\n const isAuthenticated = await checkAuthentication();\n if (!isAuthenticated) {\n throw new Error('User not authenticated');\n }\n },\n \n beforeMount: async (app, global) => {\n // Inject user context\n const userContext = await getUserContext();\n global.__USER_CONTEXT__ = userContext;\n }\n};\n```\n\n### 3. 主题同步\n\n```typescript\nconst lifecycles = {\n beforeMount: async (app, global) => {\n // Sync theme with micro app\n const currentTheme = getCurrentTheme();\n global.__THEME__ = currentTheme;\n \n // Apply theme-specific styles\n applyThemeStyles(currentTheme);\n },\n \n afterUnmount: async (app) => {\n // Clean up theme styles\n removeThemeStyles(app.name);\n }\n};\n```\n\n### 4. 特性标志管理\n\n```typescript\nconst lifecycles = {\n beforeLoad: async (app, global) => {\n // Load feature flags for the specific app\n const featureFlags = await getFeatureFlags(app.name);\n global.__FEATURE_FLAGS__ = featureFlags;\n },\n \n afterMount: async (app) => {\n // Track which features are enabled\n trackEnabledFeatures(app.name);\n }\n};\n```\n\n## ⚠️ 重要注意事项\n\n### 1. 钩子执行顺序\n\n```typescript\n// Hooks are executed in this order:\n// 1. beforeLoad (before app code is loaded)\n// 2. beforeMount (after load, before DOM mount)\n// 3. afterMount (after DOM mount)\n// ... app is running ...\n// 4. beforeUnmount (before DOM unmount)\n// 5. afterUnmount (after DOM unmount)\n```\n\n### 2. 错误处理\n\n```typescript\n// ❌ 错误：未处理的错误可能破坏生命周期\nbeforeLoad: async (app) => {\n riskyOperation(); // This could throw\n}\n\n// ✅ 正确：始终处理潜在错误\nbeforeLoad: async (app) => {\n try {\n await riskyOperation();\n } catch (error) {\n console.error('Error in beforeLoad:', error);\n // Decide whether to throw or handle gracefully\n }\n}\n```\n\n### 3. 异步操作\n\n```typescript\n// ✅ 正确：所有生命周期钩子都是异步的\nbeforeMount: async (app) => {\n await setupDatabase();\n await loadUserPreferences();\n}\n\n// ❌ 错误：不要忘记异步操作的 await\nbeforeMount: async (app) => {\n setupDatabase(); // Missing await!\n loadUserPreferences(); // Missing await!\n}\n```\n\n### 4. 全局上下文\n\n```typescript\n// ✅ 正确：使用提供的全局上下文\nbeforeMount: async (app, global) => {\n global.MY_CONFIG = getConfig(); // Set on the isolated global\n}\n\n// ❌ 错误：不要直接使用 window\nbeforeMount: async (app, global) => {\n window.MY_CONFIG = getConfig(); // Might affect other apps\n}\n```\n\n## 🚀 最佳实践\n\n### 1. 保持钩子轻量\n\n```typescript\n// ✅ 正确：快速操作\nbeforeMount: async (app) => {\n setAppTheme(app.name);\n updateNavigationState();\n}\n\n// ❌ 错误：重操作\nbeforeMount: async (app) => {\n await downloadLargeDataset(); // This will block mounting\n await processHeavyCalculations();\n}\n```\n\n### 2. 使用钩子数组进行组织\n\n```typescript\nconst lifecycles = {\n beforeMount: [\n setupAuthentication,\n setupTheme,\n setupAnalytics,\n setupFeatureFlags\n ],\n afterMount: [\n trackPageView,\n initializeWidgets,\n preloadCriticalData\n ]\n};\n```\n\n### 3. 一致的错误日志记录\n\n```typescript\nconst createSafeHook = (hookName, hookFn) => async (app, global) => {\n try {\n await hookFn(app, global);\n } catch (error) {\n console.error(`Error in ${hookName} for ${app.name}:`, error);\n // Report to error tracking service\n errorTracker.report(error, { hook: hookName, app: app.name });\n }\n};\n\nconst lifecycles = {\n beforeLoad: createSafeHook('beforeLoad', async (app) => {\n // Your beforeLoad logic\n }),\n afterMount: createSafeHook('afterMount', async (app) => {\n // Your afterMount logic\n })\n};\n```\n\n### 4. 资源清理\n\n```typescript\n// Track resources in a way that survives app reloads\nconst globalResourceMap = window.__QIANKUN_RESOURCES__ || new Map();\nwindow.__QIANKUN_RESOURCES__ = globalResourceMap;\n\nconst lifecycles = {\n beforeMount: async (app) => {\n const resources = await allocateResources();\n globalResourceMap.set(app.name, resources);\n },\n \n afterUnmount: async (app) => {\n const resources = globalResourceMap.get(app.name);\n if (resources) {\n await cleanupResources(resources);\n globalResourceMap.delete(app.name);\n }\n }\n};\n```\n\n## 🔗 相关 API\n\n- [registerMicroApps](/zh-CN/api/register-micro-apps) - 与已注册应用一起使用生命周期\n- [loadMicroApp](/zh-CN/api/load-micro-app) - 与手动加载的应用一起使用生命周期\n- [start](/zh-CN/api/start) - 框架启动配置 " }, { "path": "docs/zh-CN/api/load-micro-app.md", "content": "# loadMicroApp\n\n手动加载微应用。这对于动态加载微应用或当微应用不与路由关联时很有用。\n\n## 🎯 函数签名\n\n```typescript\nfunction loadMicroApp(\n app: LoadableApp,\n configuration?: AppConfiguration,\n lifeCycles?: LifeCycles\n): MicroApp\n```\n\n## 📋 参数\n\n### app\n\n- **类型**: `LoadableApp`\n- **必填**: ✅\n- **描述**: 微应用配置\n\n#### LoadableApp 结构\n\n```typescript\ninterface LoadableApp {\n name: string; // Micro app name, globally unique\n entry: string | EntryOpts; // Micro app entry\n container: string | HTMLElement; // Container for the micro app\n props?: T; // Custom data passed to micro app\n}\n```\n\n| 属性 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `name` | `string` | ✅ | 微应用名称，作为唯一标识符 |\n| `entry` | `string \\| EntryOpts` | ✅ | 微应用入口，可以是 URL 或资源配置 |\n| `container` | `string \\| HTMLElement` | ✅ | 容器节点选择器或 DOM 元素 |\n| `props` | `T` | ❌ | 传递给微应用的自定义数据 |\n\n### configuration\n\n- **类型**: `AppConfiguration`\n- **必填**: ❌\n- **描述**: 高级配置选项\n\n```typescript\ninterface AppConfiguration {\n sandbox?: boolean; // Enable sandbox isolation\n globalContext?: WindowProxy; // Global context for the micro app\n fetch?: Function; // Custom fetch function\n streamTransformer?: Function; // Stream transformer\n nodeTransformer?: Function; // Node transformer\n}\n```\n\n### lifeCycles\n\n- **类型**: `LifeCycles`\n- **必填**: ❌\n- **描述**: 此特定微应用的生命周期钩子\n\n## 🔄 返回值\n\n返回一个具有以下方法的 `MicroApp` 实例：\n\n```typescript\ninterface MicroApp {\n mount(): Promise; // Mount the micro app\n unmount(): Promise; // Unmount the micro app\n update(props: any): Promise; // Update micro app props\n getStatus(): string; // Get current status\n loadPromise: Promise; // Loading promise\n mountPromise: Promise; // Mounting promise\n unmountPromise: Promise; // Unmounting promise\n}\n```\n\n## 💡 使用示例\n\n### 基础用法\n\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst microApp = loadMicroApp({\n name: 'manual-app',\n entry: '//localhost:8080',\n container: '#manual-container',\n});\n\n// The micro app will be automatically mounted\n```\n\n### 带自定义 Props\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'dashboard',\n entry: '//localhost:8080',\n container: '#dashboard-container',\n props: {\n token: localStorage.getItem('token'),\n userId: getCurrentUserId(),\n theme: 'dark'\n }\n});\n```\n\n### 带配置\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'third-party-app',\n entry: '//external.example.com',\n container: '#external-container',\n}, {\n sandbox: false, // Disable sandbox for legacy apps\n fetch: customFetch, // Use custom fetch\n});\n```\n\n### 带生命周期钩子\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'monitored-app',\n entry: '//localhost:8080',\n container: '#monitored-container',\n}, undefined, {\n beforeMount: (app) => {\n console.log('About to mount:', app.name);\n showLoadingSpinner();\n },\n afterMount: (app) => {\n console.log('Mounted successfully:', app.name);\n hideLoadingSpinner();\n },\n beforeUnmount: (app) => {\n console.log('About to unmount:', app.name);\n saveUserState();\n }\n});\n```\n\n## 🔧 高级用法\n\n### 条件动态加载\n\n```typescript\nasync function loadAppConditionally(condition: boolean) {\n if (condition) {\n const microApp = loadMicroApp({\n name: 'conditional-app',\n entry: '//localhost:8080',\n container: '#conditional-container',\n });\n \n return microApp;\n }\n return null;\n}\n```\n\n### 加载多个应用\n\n```typescript\nfunction loadMultipleApps() {\n const apps = [\n { name: 'app1', entry: '//localhost:8001', container: '#container1' },\n { name: 'app2', entry: '//localhost:8002', container: '#container2' },\n { name: 'app3', entry: '//localhost:8003', container: '#container3' },\n ];\n\n const microApps = apps.map(app => loadMicroApp(app));\n return microApps;\n}\n```\n\n### 手动控制\n\n```typescript\nconst microApp = loadMicroApp({\n name: 'controlled-app',\n entry: '//localhost:8080',\n container: '#controlled-container',\n});\n\n// Manual unmount\nawait microApp.unmount();\n\n// Update props\nawait microApp.update({ newData: 'updated' });\n\n// Check status\nconsole.log(microApp.getStatus()); // 'MOUNTED', 'UNMOUNTED', etc.\n```\n\n## 🎭 用例场景\n\n### 1. 模态框/对话框应用\n\n```typescript\nfunction openAppModal() {\n const modal = document.createElement('div');\n modal.id = 'app-modal';\n document.body.appendChild(modal);\n\n const microApp = loadMicroApp({\n name: 'modal-app',\n entry: '//localhost:8080',\n container: modal,\n props: { \n onClose: () => {\n microApp.unmount().then(() => {\n document.body.removeChild(modal);\n });\n }\n }\n });\n\n return microApp;\n}\n```\n\n### 2. 基于标签页的应用\n\n```typescript\nclass TabManager {\n private activeTabs = new Map();\n\n async switchTab(tabName: string, config: LoadableApp) {\n // Unmount current active tab\n const currentApp = this.activeTabs.get('active');\n if (currentApp) {\n await currentApp.unmount();\n }\n\n // Load new tab\n const newApp = loadMicroApp({\n ...config,\n container: '#tab-content'\n });\n\n this.activeTabs.set('active', newApp);\n this.activeTabs.set(tabName, newApp);\n }\n}\n```\n\n### 3. 组件系统\n\n```typescript\nclass WidgetSystem {\n loadWidget(widgetConfig: any) {\n return loadMicroApp({\n name: `widget-${widgetConfig.id}`,\n entry: widgetConfig.url,\n container: `#widget-${widgetConfig.id}`,\n props: widgetConfig.props\n }, {\n sandbox: true // Isolate widgets\n });\n }\n}\n```\n\n## ⚠️ 重要注意事项\n\n### 容器管理\n\n```typescript\n// ❌ 错误：在没有适当清理的情况下重用容器\nloadMicroApp({ name: 'app1', entry: '//localhost:8001', container: '#shared' });\nloadMicroApp({ name: 'app2', entry: '//localhost:8002', container: '#shared' }); // Conflict!\n\n// ✅ 正确：使用唯一容器或适当清理\nconst app1 = loadMicroApp({ name: 'app1', entry: '//localhost:8001', container: '#container1' });\nconst app2 = loadMicroApp({ name: 'app2', entry: '//localhost:8002', container: '#container2' });\n```\n\n### 内存管理\n\n```typescript\n// ✅ 正确：适当清理\nconst microApp = loadMicroApp({...});\n\n// When done, always unmount\nwindow.addEventListener('beforeunload', () => {\n microApp.unmount();\n});\n```\n\n### 错误处理\n\n```typescript\ntry {\n const microApp = loadMicroApp({\n name: 'potentially-failing-app',\n entry: '//unreliable-server.com',\n container: '#container',\n });\n\n // Wait for load\n await microApp.loadPromise;\n console.log('App loaded successfully');\n} catch (error) {\n console.error('Failed to load micro app:', error);\n // Handle error - show fallback UI, retry, etc.\n}\n```\n\n## 🆚 对比 registerMicroApps\n\n| 特性 | `loadMicroApp` | `registerMicroApps` |\n|------|----------------|---------------------|\n| **加载方式** | 手动，立即 | 自动，基于路由 |\n| **用例** | 动态加载、组件、模态框 | 主导航、SPA 路由 |\n| **生命周期** | 手动控制 | 路由自动控制 |\n| **性能** | 按需加载 | 可以预加载 |\n\n## 🚀 最佳实践\n\n### 1. 资源管理\n\n```typescript\nclass MicroAppManager {\n private apps = new Map();\n\n async loadApp(config: LoadableApp) {\n // Check if already loaded\n if (this.apps.has(config.name)) {\n return this.apps.get(config.name);\n }\n\n const app = loadMicroApp(config);\n this.apps.set(config.name, app);\n \n // Auto cleanup on unmount\n app.unmountPromise.then(() => {\n this.apps.delete(config.name);\n });\n\n return app;\n }\n}\n```\n\n### 2. Props 管理\n\n```typescript\n// ✅ 正确：响应式 props\nfunction createReactiveMicroApp(baseConfig: LoadableApp) {\n let currentApp: MicroApp;\n\n return {\n async updateProps(newProps: any) {\n if (currentApp) {\n await currentApp.update(newProps);\n }\n },\n \n async reload(newConfig: LoadableApp) {\n if (currentApp) {\n await currentApp.unmount();\n }\n currentApp = loadMicroApp({\n ...baseConfig,\n ...newConfig\n });\n }\n };\n}\n```\n\n### 3. 错误边界\n\n```typescript\nfunction loadMicroAppWithFallback(config: LoadableApp, fallbackHTML: string) {\n const microApp = loadMicroApp(config);\n \n microApp.loadPromise.catch((error) => {\n console.error('Micro app failed to load:', error);\n // Show fallback content\n const container = typeof config.container === 'string' \n ? document.querySelector(config.container)\n : config.container;\n \n if (container) {\n container.innerHTML = fallbackHTML;\n }\n });\n\n return microApp;\n}\n```\n\n## 🔗 相关 API\n\n- [registerMicroApps](/zh-CN/api/register-micro-apps) - 基于路由的微应用加载\n- [start](/zh-CN/api/start) - 启动 qiankun 框架\n- [生命周期](/zh-CN/api/lifecycles) - 详细的生命周期文档 " }, { "path": "docs/zh-CN/api/register-micro-apps.md", "content": "# registerMicroApps\n\n注册微应用到 qiankun 中，这是构建微前端应用的核心 API。\n\n## 🎯 函数签名\n\n```typescript\nfunction registerMicroApps(\n apps: Array>, \n lifeCycles?: LifeCycles\n): void\n```\n\n## 📋 参数\n\n### apps\n\n- **类型**: `Array>`\n- **必填**: ✅\n- **描述**: 微应用注册信息数组\n\n#### RegistrableApp 结构\n\n```typescript\ninterface RegistrableApp {\n name: string; // 微应用名称，全局唯一\n entry: string | { scripts?: string[], styles?: string[] }; // 微应用入口\n container: string | HTMLElement; // 微应用容器节点\n activeRule: string | (location: Location) => boolean; // 激活规则\n props?: T; // 传递给微应用的数据\n loader?: (loading: boolean) => void; // 加载状态回调\n}\n```\n\n| 属性 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `name` | `string` | ✅ | 微应用名称，作为微应用的唯一标识 |\n| `entry` | `string \\| EntryOpts` | ✅ | 微应用的入口，可以是 URL 或资源配置对象 |\n| `container` | `string \\| HTMLElement` | ✅ | 微应用的容器节点选择器或 DOM 节点 |\n| `activeRule` | `string \\| Function` | ✅ | 微应用的激活规则 |\n| `props` | `T` | ❌ | 传递给微应用的自定义数据 |\n| `loader` | `Function` | ❌ | 微应用加载状态改变时的回调函数 |\n\n### lifeCycles\n\n- **类型**: `LifeCycles`\n- **必填**: ❌\n- **描述**: 全局生命周期钩子\n\n```typescript\ninterface LifeCycles {\n beforeLoad?: LifeCycleFn | Array>;\n beforeMount?: LifeCycleFn | Array>;\n afterMount?: LifeCycleFn | Array>;\n beforeUnmount?: LifeCycleFn | Array>;\n afterUnmount?: LifeCycleFn | Array>;\n}\n```\n\n## 💡 使用示例\n\n### 基础用法\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'react16App',\n entry: '//localhost:7100',\n container: '#subapp-viewport',\n activeRule: '/react16',\n },\n {\n name: 'vue3App', \n entry: '//localhost:7101',\n container: '#subapp-viewport',\n activeRule: '/vue3',\n }\n]);\n\nstart();\n```\n\n### 高级配置\n\n```typescript\nregisterMicroApps([\n {\n name: 'dashboard',\n entry: {\n scripts: [\n '//localhost:7100/static/js/main.js'\n ],\n styles: [\n '//localhost:7100/static/css/main.css'\n ]\n },\n container: '#dashboard-container',\n activeRule: (location) => location.pathname.startsWith('/dashboard'),\n props: {\n token: 'your-auth-token',\n userId: 123,\n theme: 'dark'\n },\n loader: (loading) => {\n console.log('Dashboard app loading:', loading);\n // 显示/隐藏 loading 状态\n }\n }\n], {\n beforeLoad: [\n app => console.log('Before load:', app.name),\n app => trackEvent('micro-app-loading', { name: app.name })\n ],\n beforeMount: app => console.log('Before mount:', app.name),\n afterMount: app => console.log('After mount:', app.name),\n beforeUnmount: app => console.log('Before unmount:', app.name),\n afterUnmount: app => console.log('After unmount:', app.name),\n});\n```\n\n## ⚙️ Entry 配置详解\n\n### URL 字符串\n\n最简单的配置方式，qiankun 会通过这个 URL 获取微应用的 HTML：\n\n```typescript\n{\n name: 'app1',\n entry: '//localhost:8080',\n // ...\n}\n```\n\n### 资源对象\n\n精确控制微应用的资源加载：\n\n```typescript\n{\n name: 'app2',\n entry: {\n scripts: [\n '//localhost:8080/static/js/chunk.js',\n '//localhost:8080/static/js/main.js'\n ],\n styles: [\n '//localhost:8080/static/css/main.css'\n ]\n },\n // ...\n}\n```\n\n## 🎯 ActiveRule 配置\n\n### 字符串路径\n\n```typescript\n{\n activeRule: '/react16' // 匹配 /react16/xxx 路径\n}\n```\n\n### 函数判断\n\n```typescript\n{\n activeRule: (location) => {\n // 自定义激活逻辑\n return location.pathname.startsWith('/admin') && \n location.search.includes('module=dashboard');\n }\n}\n```\n\n### 常见模式\n\n```typescript\n// 1. 精确匹配\nactiveRule: (location) => location.pathname === '/exact-path'\n\n// 2. 多路径匹配\nactiveRule: (location) => ['/path1', '/path2'].some(path => \n location.pathname.startsWith(path)\n)\n\n// 3. 带参数匹配\nactiveRule: (location) => /^\\/user\\/\\d+/.test(location.pathname)\n\n// 4. 查询参数匹配\nactiveRule: (location) => new URLSearchParams(location.search).get('app') === 'module1'\n```\n\n## 🔧 Container 配置\n\n### CSS 选择器\n\n```typescript\n{\n container: '#micro-app-container'\n}\n```\n\n### DOM 节点\n\n```typescript\n{\n container: document.querySelector('#container')\n}\n```\n\n## 📨 Props 数据传递\n\n微应用可以通过 props 参数接收主应用传递的数据：\n\n```typescript\n// 主应用\nregisterMicroApps([{\n name: 'child-app',\n // ...\n props: {\n data: { user: 'john' },\n methods: {\n onGlobalStateChange: (state) => console.log(state),\n setGlobalState: (state) => updateGlobalState(state)\n }\n }\n}]);\n```\n\n```typescript\n// 微应用\nexport async function mount(props) {\n console.log(props.data); // { user: 'john' }\n console.log(props.methods); // { onGlobalStateChange, setGlobalState }\n}\n```\n\n## ⚠️ 注意事项\n\n### 应用名称唯一性\n\n```typescript\n// ❌ 错误：重复的应用名称\nregisterMicroApps([\n { name: 'app1', entry: '//localhost:8080', /*...*/ },\n { name: 'app1', entry: '//localhost:8081', /*...*/ }, // 重复！\n]);\n\n// ✅ 正确：唯一的应用名称\nregisterMicroApps([\n { name: 'app1', entry: '//localhost:8080', /*...*/ },\n { name: 'app2', entry: '//localhost:8081', /*...*/ },\n]);\n```\n\n### 容器节点存在性\n\n```typescript\n// ❌ 错误：容器节点不存在\nregisterMicroApps([{\n container: '#non-existent-container', // DOM 中不存在\n // ...\n}]);\n\n// ✅ 正确：确保容器节点存在\nregisterMicroApps([{\n container: '#app-container', // 确保 DOM 中存在\n // ...\n}]);\n```\n\n### 重复注册\n\n```typescript\n// ❌ 错误：重复注册会导致应用重复加载\nregisterMicroApps([...]);\nregisterMicroApps([...]); // 重复注册\n\n// ✅ 正确：只注册一次\nregisterMicroApps([...]);\n```\n\n## 🚀 最佳实践\n\n### 1. 应用配置管理\n\n```typescript\n// 推荐：将应用配置抽取为单独文件\nconst microApps = [\n {\n name: 'order-management',\n entry: getAppEntry('order'),\n container: '#subapp-container',\n activeRule: '/order',\n props: getAppProps('order')\n },\n // ...\n];\n\nregisterMicroApps(microApps, {\n beforeLoad: [initLoadingUI],\n afterMount: [removeLoadingUI],\n});\n```\n\n### 2. 环境配置\n\n```typescript\nconst getAppEntry = (name: string) => {\n const entries = {\n development: {\n order: '//localhost:8001',\n user: '//localhost:8002'\n },\n production: {\n order: '//order.example.com',\n user: '//user.example.com'\n }\n };\n \n return entries[process.env.NODE_ENV][name];\n};\n```\n\n### 3. 统一错误处理\n\n```typescript\nregisterMicroApps(microApps, {\n beforeLoad: (app) => {\n console.log(`Loading ${app.name}...`);\n },\n afterMount: (app) => {\n console.log(`${app.name} mounted successfully`);\n },\n beforeUnmount: (app) => {\n // 清理全局状态\n cleanupGlobalState(app.name);\n }\n});\n```\n\n## 🔗 相关 API\n\n- [start](/zh-CN/api/start) - 启动 qiankun\n- [loadMicroApp](/zh-CN/api/load-micro-app) - 手动加载微应用\n- [生命周期](/zh-CN/api/lifecycles) - 详细的生命周期说明 " }, { "path": "docs/zh-CN/api/start.md", "content": "# start\n\n启动 qiankun 框架。此函数初始化微前端系统并启用基于路由的微应用自动加载。\n\n## 🎯 函数签名\n\n```typescript\nfunction start(opts?: StartOpts): void\n```\n\n## 📋 参数\n\n### opts\n\n- **类型**: `StartOpts`\n- **必填**: ❌\n- **描述**: 启动配置选项\n\n```typescript\ninterface StartOpts {\n prefetch?: boolean | 'all' | string[] | ((apps: RegistrableApp[]) => { criticalAppNames: string[]; minorAppsName: string[] });\n sandbox?: boolean | { strictStyleIsolation?: boolean; experimentalStyleIsolation?: boolean; };\n singular?: boolean;\n urlRerouteOnly?: boolean;\n // ... 其他 single-spa 启动选项\n}\n```\n\n| 选项 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `prefetch` | `boolean \\| 'all' \\| string[] \\| Function` | `true` | 资源预取策略 |\n| `sandbox` | `boolean \\| SandboxOpts` | `true` | 沙箱隔离配置 |\n| `singular` | `boolean` | `true` | 是否同时只能挂载一个微应用 |\n| `urlRerouteOnly` | `boolean` | `true` | 是否仅在 URL 变化时触发路由 |\n\n## 💡 使用示例\n\n### 基础用法\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\n// 先注册微应用\nregisterMicroApps([\n {\n name: 'react-app',\n entry: '//localhost:7100',\n container: '#subapp-viewport',\n activeRule: '/react',\n },\n {\n name: 'vue-app',\n entry: '//localhost:7101',\n container: '#subapp-viewport',\n activeRule: '/vue',\n },\n]);\n\n// 启动 qiankun\nstart();\n```\n\n### 带配置的用法\n\n```typescript\nstart({\n prefetch: false, // 禁用预取\n sandbox: true, // 启用沙箱\n singular: true, // 同时只能有一个应用\n urlRerouteOnly: true, // 仅在 URL 变化时路由\n});\n```\n\n### 高级沙箱配置\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // 启用严格样式隔离\n experimentalStyleIsolation: true, // 启用实验性样式隔离\n }\n});\n```\n\n### 自定义预取策略\n\n```typescript\nstart({\n prefetch: 'all', // 预取所有微应用\n});\n\n// 或者预取指定应用\nstart({\n prefetch: ['react-app', 'vue-app'], // 只预取这些应用\n});\n\n// 或者自定义预取函数\nstart({\n prefetch: (apps) => ({\n criticalAppNames: ['dashboard', 'user-center'], // 关键应用立即预取\n minorAppsName: ['analytics', 'settings'], // 次要应用稍后预取\n })\n});\n```\n\n## ⚙️ 配置选项\n\n### 预取策略\n\n#### 1. 布尔值\n\n```typescript\n// 完全禁用预取\nstart({ prefetch: false });\n\n// 启用默认预取行为\nstart({ prefetch: true });\n```\n\n#### 2. 预取所有\n\n```typescript\n// 预取所有已注册的微应用\nstart({ prefetch: 'all' });\n```\n\n#### 3. 选择性预取\n\n```typescript\n// 只预取指定的应用\nstart({ \n prefetch: ['critical-app1', 'critical-app2'] \n});\n```\n\n#### 4. 动态预取策略\n\n```typescript\nstart({\n prefetch: (apps) => {\n // 自定义逻辑决定预取哪些应用\n const criticalApps = apps\n .filter(app => app.name.includes('critical'))\n .map(app => app.name);\n \n const minorApps = apps\n .filter(app => !app.name.includes('critical'))\n .map(app => app.name);\n\n return {\n criticalAppNames: criticalApps, // 立即预取\n minorAppsName: minorApps, // 空闲时预取\n };\n }\n});\n```\n\n### 沙箱配置\n\n#### 1. 布尔型沙箱\n\n```typescript\n// 启用基础沙箱\nstart({ sandbox: true });\n\n// 禁用沙箱（不推荐）\nstart({ sandbox: false });\n```\n\n#### 2. 高级沙箱\n\n```typescript\nstart({\n sandbox: {\n strictStyleIsolation: true, // 基于 Shadow DOM 的样式隔离\n experimentalStyleIsolation: true, // 基于作用域 CSS 的样式隔离\n }\n});\n```\n\n### 性能选项\n\n```typescript\nstart({\n singular: false, // 允许多个应用同时挂载\n urlRerouteOnly: false, // 在 URL 和编程式变化时都触发路由\n});\n```\n\n## 🚀 最佳实践\n\n### 1. 在注册后调用\n\n```typescript\n// ✅ 正确的顺序\nregisterMicroApps([...]);\nstart();\n\n// ❌ 错误的顺序\nstart();\nregisterMicroApps([...]); // 这样不会正常工作\n```\n\n### 2. 基于环境的配置\n\n```typescript\nconst startOpts = {\n prefetch: process.env.NODE_ENV === 'production' ? 'all' : false,\n sandbox: {\n strictStyleIsolation: process.env.NODE_ENV === 'production',\n },\n};\n\nstart(startOpts);\n```\n\n### 3. 性能优化\n\n```typescript\n// 在生产环境中获得更好的性能\nstart({\n prefetch: (apps) => ({\n criticalAppNames: ['dashboard'], // 只预取关键应用\n minorAppsName: [], // 不预取次要应用\n }),\n singular: true, // 防止内存问题\n sandbox: {\n strictStyleIsolation: false, // 使用轻量级样式隔离\n experimentalStyleIsolation: true,\n },\n});\n```\n\n### 4. 开发环境 vs 生产环境\n\n```typescript\nif (process.env.NODE_ENV === 'development') {\n start({\n prefetch: false, // 更快的开发重载\n sandbox: false, // 更容易调试\n singular: false, // 更灵活的开发\n });\n} else {\n start({\n prefetch: 'all', // 更好的用户体验\n sandbox: true, // 更好的隔离\n singular: true, // 稳定的性能\n });\n}\n```\n\n## 🔧 集成模式\n\n### 1. 带加载状态\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\nlet isQiankunStarted = false;\n\nfunction startQiankunWithLoading() {\n if (isQiankunStarted) return;\n\n showGlobalLoading();\n\n registerMicroApps([...], {\n beforeLoad: (app) => {\n console.log(`Loading ${app.name}...`);\n },\n afterMount: (app) => {\n console.log(`${app.name} mounted`);\n hideGlobalLoading();\n },\n });\n\n start({\n prefetch: 'all',\n sandbox: true,\n });\n\n isQiankunStarted = true;\n}\n```\n\n### 2. 带错误处理\n\n```typescript\nfunction startQiankunSafely() {\n try {\n registerMicroApps([...]);\n \n start({\n prefetch: 'all',\n sandbox: true,\n });\n\n console.log('Qiankun started successfully');\n } catch (error) {\n console.error('Failed to start qiankun:', error);\n // 回退到传统路由或显示错误页面\n window.location.href = '/fallback';\n }\n}\n```\n\n### 3. 带特性检测\n\n```typescript\nimport { isRuntimeCompatible } from 'qiankun';\n\nif (isRuntimeCompatible()) {\n registerMicroApps([...]);\n start();\n} else {\n console.warn('Browser not compatible with qiankun');\n // 回退实现\n initTraditionalRouting();\n}\n```\n\n## ⚠️ 重要注意事项\n\n### 1. 只调用一次\n\n```typescript\n// ❌ 错误：多次调用\nstart();\nstart(); // 这个调用会被忽略\n\n// ✅ 正确：单次调用\nstart();\n```\n\n### 2. 顺序很重要\n\n```typescript\n// ✅ 正确顺序\nregisterMicroApps([...]); // 1. 先注册应用\nstart(); // 2. 然后启动\n\n// ❌ 错误顺序 - 应用不会被正确注册\nstart();\nregisterMicroApps([...]);\n```\n\n### 3. 预取注意事项\n\n```typescript\n// ⚠️ 在大型应用中要小心使用 'all'\nstart({ prefetch: 'all' }); // 可能影响初始加载性能\n\n// ✅ 更好：选择性预取\nstart({ \n prefetch: ['critical-app1', 'critical-app2'] \n});\n```\n\n## 🎯 常见用例\n\n### 1. 电商平台\n\n```typescript\nregisterMicroApps([\n { name: 'product-catalog', entry: '//catalog.example.com', activeRule: '/products' },\n { name: 'shopping-cart', entry: '//cart.example.com', activeRule: '/cart' },\n { name: 'user-account', entry: '//account.example.com', activeRule: '/account' },\n]);\n\nstart({\n prefetch: (apps) => ({\n criticalAppNames: ['shopping-cart'], // 总是预取购物车\n minorAppsName: ['user-account'], // 空闲时预取账户\n }),\n sandbox: true,\n singular: true,\n});\n```\n\n### 2. 管理后台\n\n```typescript\nstart({\n prefetch: false, // 不预取 - 管理工具按需使用\n sandbox: {\n strictStyleIsolation: true, // 防止管理工具间的样式冲突\n },\n singular: false, // 允许多个管理工具同时打开\n});\n```\n\n### 3. 多租户平台\n\n```typescript\nconst tenantId = getCurrentTenantId();\n\nstart({\n prefetch: [`tenant-${tenantId}-dashboard`], // 只预取当前租户的应用\n sandbox: true, // 隔离租户数据\n singular: true,\n});\n```\n\n## 🔗 相关 API\n\n- [registerMicroApps](/zh-CN/api/register-micro-apps) - 注册微应用\n- [loadMicroApp](/zh-CN/api/load-micro-app) - 手动加载微应用\n- [isRuntimeCompatible](/zh-CN/api/is-runtime-compatible) - 检查浏览器兼容性 " }, { "path": "docs/zh-CN/api/types.md", "content": "# TypeScript 类型\n\nqiankun 提供了全面的 TypeScript 类型定义，确保类型安全和出色的开发者体验。本文档涵盖了所有可用的类型和接口。\n\n## 📋 核心类型\n\n### ObjectType\n\n**描述**：通用对象结构的基础类型。\n\n```typescript\nexport type ObjectType = Record;\n```\n\n**用法**：\n```typescript\n// 用作泛型类型的约束\nfunction processApp(props: T): void {\n // T 可以是任何对象类型\n}\n```\n\n### HTMLEntry\n\n**描述**：微应用入口点的类型。\n\n```typescript\nexport type HTMLEntry = string;\n```\n\n**用法**：\n```typescript\nconst appEntry: HTMLEntry = '//localhost:8080';\nconst appEntryWithPath: HTMLEntry = '//localhost:8080/micro-app';\n```\n\n## 🏗️ 应用类型\n\n### AppMetadata\n\n**描述**：微应用的基础元数据。\n\n```typescript\ntype AppMetadata = {\n name: string; // 唯一的应用名称\n entry: HTMLEntry; // 应用入口 URL\n};\n```\n\n### LoadableApp\\\n\n**描述**：手动加载微应用的配置。\n\n```typescript\nexport type LoadableApp = AppMetadata & {\n container: HTMLElement; // DOM 容器元素\n props?: T; // 传递给应用的自定义属性\n};\n```\n\n**用法**：\n```typescript\n// 基础用法\nconst app: LoadableApp<{}> = {\n name: 'my-app',\n entry: '//localhost:8080',\n container: document.getElementById('app-container')!,\n};\n\n// 带自定义属性\ninterface MyAppProps {\n theme: 'light' | 'dark';\n userId: string;\n}\n\nconst appWithProps: LoadableApp = {\n name: 'themed-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n theme: 'dark',\n userId: '123'\n }\n};\n```\n\n### RegistrableApp\\\n\n**描述**：基于路由的微应用配置。\n\n```typescript\nexport type RegistrableApp = LoadableApp & {\n loader?: (loading: boolean) => void; // 加载状态回调\n activeRule: RegisterApplicationConfig['activeWhen']; // 路由激活规则\n};\n```\n\n**用法**：\n```typescript\nimport { registerMicroApps } from 'qiankun';\n\ninterface UserAppProps {\n currentUser: { id: string; name: string };\n}\n\nconst apps: RegistrableApp[] = [\n {\n name: 'user-dashboard',\n entry: '//localhost:8001',\n container: '#subapp-viewport',\n activeRule: '/dashboard',\n props: {\n currentUser: { id: '123', name: 'John' }\n },\n loader: (loading) => {\n if (loading) {\n showLoadingSpinner();\n } else {\n hideLoadingSpinner();\n }\n }\n }\n];\n\nregisterMicroApps(apps);\n```\n\n## ⚙️ 配置类型\n\n### AppConfiguration\n\n**描述**：单个微应用的配置选项。\n\n```typescript\nexport type AppConfiguration = Partial> & {\n sandbox?: boolean; // 启用沙箱隔离\n globalContext?: WindowProxy; // 自定义全局上下文\n};\n```\n\n**用法**：\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst customConfig: AppConfiguration = {\n sandbox: true,\n globalContext: window,\n fetch: async (url, options) => {\n // 自定义 fetch 实现\n return fetch(url, {\n ...options,\n headers: {\n ...options?.headers,\n 'Authorization': 'Bearer token'\n }\n });\n },\n nodeTransformer: (node, opts) => {\n // 转换 DOM 节点\n if (node.tagName === 'SCRIPT') {\n node.setAttribute('data-app', 'my-app');\n }\n return node;\n }\n};\n\nloadMicroApp({\n name: 'configured-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!\n}, customConfig);\n```\n\n## 🔄 生命周期类型\n\n### LifeCycleFn\\\n\n**描述**：生命周期钩子函数的类型。\n\n```typescript\nexport type LifeCycleFn = (\n app: LoadableApp, \n global: WindowProxy\n) => Promise;\n```\n\n**用法**：\n```typescript\nconst beforeLoadHook: LifeCycleFn<{ theme: string }> = async (app, global) => {\n console.log(`正在加载应用: ${app.name}`);\n global.__APP_THEME__ = app.props?.theme || 'default';\n};\n\nconst afterMountHook: LifeCycleFn = async (app, global) => {\n console.log(`应用 ${app.name} 挂载成功`);\n // 跟踪分析\n analytics.track('app_mounted', { appName: app.name });\n};\n```\n\n### LifeCycles\\\n\n**描述**：完整的生命周期钩子配置。\n\n```typescript\nexport type LifeCycles = {\n beforeLoad?: LifeCycleFn | Array>;\n beforeMount?: LifeCycleFn | Array>;\n afterMount?: LifeCycleFn | Array>;\n beforeUnmount?: LifeCycleFn | Array>;\n afterUnmount?: LifeCycleFn | Array>;\n};\n```\n\n**用法**：\n```typescript\ninterface AppProps {\n userId: string;\n permissions: string[];\n}\n\nconst lifecycles: LifeCycles = {\n beforeLoad: async (app, global) => {\n // 加载前设置\n global.__USER_ID__ = app.props?.userId;\n },\n \n beforeMount: [\n async (app, global) => {\n // 多个钩子作为数组\n await setupAuthentication(app.props?.userId);\n },\n async (app, global) => {\n await loadUserPermissions(app.props?.permissions);\n }\n ],\n \n afterMount: async (app) => {\n console.log(`${app.name} 已准备就绪`);\n },\n \n beforeUnmount: async (app) => {\n // 卸载前清理\n await saveUserState(app.name);\n },\n \n afterUnmount: async (app) => {\n // 最终清理\n await clearUserData(app.name);\n }\n};\n```\n\n## 🎯 微应用类型\n\n### MicroApp\n\n**描述**：已加载微应用的实例。\n\n```typescript\nexport type MicroApp = Parcel;\n```\n\n`MicroApp` 类型扩展了 single-spa 的 `Parcel` 接口，包含以下方法：\n\n```typescript\ninterface MicroApp {\n mount(): Promise; // 挂载应用\n unmount(): Promise; // 卸载应用\n update(props: any): Promise; // 更新应用属性\n getStatus(): string; // 获取当前状态\n loadPromise: Promise; // 加载完成时解析的 Promise\n mountPromise: Promise; // 挂载完成时解析的 Promise\n unmountPromise: Promise; // 卸载完成时解析的 Promise\n}\n```\n\n**用法**：\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\nconst microApp: MicroApp = loadMicroApp({\n name: 'my-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!\n});\n\n// 检查状态\nconsole.log(microApp.getStatus()); // 'LOADING', 'MOUNTED', 'UNMOUNTED', 等\n\n// 等待挂载\nawait microApp.mountPromise;\nconsole.log('应用已挂载');\n\n// 更新属性\nawait microApp.update({ newTheme: 'dark' });\n\n// 完成后卸载\nawait microApp.unmount();\n```\n\n### MicroAppLifeCycles\n\n**描述**：qiankun 使用的内部生命周期类型。\n\n```typescript\nexport type MicroAppLifeCycles = FlattenArrayValue>;\n```\n\n这个类型主要用于内部使用，表示微应用必须导出的扁平化生命周期函数。\n\n## 🌐 全局类型\n\n### Window 扩展\n\nqiankun 为全局 `Window` 接口添加了特殊属性：\n\n```typescript\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean; // 指示应用运行在 qiankun 中\n __INJECTED_PUBLIC_PATH_BY_QIANKUN__?: string; // 注入的公共路径\n __QIANKUN_DEVELOPMENT__?: boolean; // 开发模式标志\n Zone?: CallableFunction; // Zone.js 兼容性\n __zone_symbol__setTimeout?: Window['setTimeout']; // Zone.js 超时\n }\n}\n```\n\n**在微应用中的用法**：\n```typescript\n// 检查是否在 qiankun 中运行\nif (window.__POWERED_BY_QIANKUN__) {\n console.log('作为微应用运行');\n \n // 使用注入的公共路径\n const publicPath = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__ || '/';\n \n // 相应地配置你的应用\n setupApp({ publicPath });\n} else {\n console.log('独立运行');\n setupApp({ publicPath: '/' });\n}\n```\n\n## 🎨 工具类型\n\n### 自定义类型守卫\n\n为更好的类型安全创建类型守卫：\n\n```typescript\n// LoadableApp 的类型守卫\nfunction isLoadableApp(\n app: any\n): app is LoadableApp {\n return (\n typeof app === 'object' &&\n typeof app.name === 'string' &&\n typeof app.entry === 'string' &&\n app.container instanceof HTMLElement\n );\n}\n\n// RegistrableApp 的类型守卫\nfunction isRegistrableApp(\n app: any\n): app is RegistrableApp {\n return (\n isLoadableApp(app) &&\n (typeof app.activeRule === 'string' || typeof app.activeRule === 'function')\n );\n}\n\n// 用法\nfunction processApp(app: unknown) {\n if (isRegistrableApp(app)) {\n // TypeScript 在这里知道 app 是 RegistrableApp\n console.log(`注册应用: ${app.name}，规则: ${app.activeRule}`);\n } else if (isLoadableApp(app)) {\n // TypeScript 在这里知道 app 是 LoadableApp\n console.log(`加载应用: ${app.name}`);\n }\n}\n```\n\n### 通用辅助类型\n\n为常见模式创建可重用的泛型类型：\n\n```typescript\n// 支持主题的属性\ntype ThemedProps = T & {\n theme?: 'light' | 'dark';\n};\n\n// 带用户上下文的属性\ntype UserAwareProps = T & {\n currentUser?: {\n id: string;\n name: string;\n role: string;\n };\n};\n\n// 组合属性\ntype AppProps = ThemedProps>;\n\n// 用法\nconst app: LoadableApp> = {\n name: 'themed-user-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n theme: 'dark',\n currentUser: { id: '123', name: 'John', role: 'admin' },\n customData: '自定义值'\n }\n};\n```\n\n## 📖 高级类型模式\n\n### 基于配置的条件类型\n\n```typescript\n// 基于环境的配置\ntype EnvironmentConfig = T extends 'development'\n ? {\n sandbox: false;\n prefetch: false;\n strictStyleIsolation: false;\n }\n : {\n sandbox: true;\n prefetch: 'all';\n strictStyleIsolation: true;\n };\n\n// 与环境检测一起使用\ndeclare const NODE_ENV: 'development' | 'production';\ntype CurrentConfig = EnvironmentConfig;\n```\n\n### 应用名称的品牌类型\n\n```typescript\n// 为应用名称创建品牌类型以防止混淆\ntype AppName = string & { readonly __brand: unique symbol };\n\nfunction createAppName(name: string): AppName {\n return name as AppName;\n}\n\n// 带品牌名称的增强 LoadableApp\ntype SafeLoadableApp = Omit, 'name'> & {\n name: AppName;\n};\n\n// 用法\nconst appName = createAppName('my-secure-app');\nconst app: SafeLoadableApp<{}> = {\n name: appName, // 类型安全的应用名称\n entry: '//localhost:8080',\n container: document.getElementById('container')!\n};\n```\n\n### 生命周期事件类型\n\n```typescript\n// 带事件数据的增强生命周期\ntype LifeCycleEvent = {\n app: LoadableApp;\n global: WindowProxy;\n timestamp: number;\n phase: 'beforeLoad' | 'beforeMount' | 'afterMount' | 'beforeUnmount' | 'afterUnmount';\n};\n\ntype EnhancedLifeCycleFn = (event: LifeCycleEvent) => Promise;\n\n// 用法\nconst enhancedHook: EnhancedLifeCycleFn<{ userId: string }> = async (event) => {\n console.log(`阶段: ${event.phase}，应用: ${event.app.name}，时间: ${event.timestamp}`);\n \n if (event.phase === 'beforeMount') {\n // 设置用户上下文\n event.global.__USER_ID__ = event.app.props?.userId;\n }\n};\n```\n\n## 🔍 类型推断示例\n\n### 自动属性类型推断\n\n```typescript\n// 带自动类型推断的辅助函数\nfunction createTypedApp(\n config: {\n name: string;\n entry: string;\n container: HTMLElement;\n props: T;\n }\n): LoadableApp {\n return config; // TypeScript 推断正确的类型\n}\n\n// 用法 - TypeScript 自动推断属性类型\nconst app = createTypedApp({\n name: 'inferred-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n theme: 'dark',\n userId: '123',\n features: ['feature1', 'feature2']\n }\n // TypeScript 知道 props 类型是 { theme: string; userId: string; features: string[] }\n});\n```\n\n### 生命周期类型推断\n\n```typescript\n// 创建类型化生命周期的辅助函数\nfunction createLifecycles(\n lifecycles: LifeCycles\n): LifeCycles {\n return lifecycles;\n}\n\n// 带推断的用法\nconst typedLifecycles = createLifecycles({\n beforeMount: async (app) => {\n // TypeScript 根据用法推断 app.props 类型\n console.log(app.props?.theme); // TypeScript 知道这可能是 undefined\n }\n});\n```\n\n## ⚡ 最佳实践\n\n### 1. 使用严格类型\n\n```typescript\n// ✅ 好：严格类型\ninterface StrictAppProps {\n readonly userId: string;\n readonly theme: 'light' | 'dark';\n readonly permissions: readonly string[];\n}\n\nconst app: LoadableApp = {\n name: 'strict-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: {\n userId: '123',\n theme: 'dark',\n permissions: ['read', 'write']\n }\n};\n\n// ❌ 坏：松散类型\nconst looseApp: LoadableApp = {\n name: 'loose-app',\n entry: '//localhost:8080',\n container: document.getElementById('container')!,\n props: { anything: 'goes' } // 没有类型安全\n};\n```\n\n### 2. 创建领域特定类型\n\n```typescript\n// 为你的领域创建特定类型\ninterface ECommerceAppProps {\n cartId: string;\n currency: 'USD' | 'EUR' | 'GBP';\n customerSegment: 'premium' | 'standard';\n features: {\n wishlist: boolean;\n recommendations: boolean;\n reviews: boolean;\n };\n}\n\ntype ECommerceApp = LoadableApp;\ntype ECommerceLifecycles = LifeCycles;\n```\n\n### 3. 使用泛型约束\n\n```typescript\n// 为更好的类型安全约束泛型类型\ninterface BaseAppProps {\n version: string;\n environment: 'development' | 'staging' | 'production';\n}\n\nfunction createApp(\n config: Omit, 'container'> & {\n containerId: string;\n }\n): LoadableApp {\n const container = document.getElementById(config.containerId);\n if (!container) {\n throw new Error(`容器 ${config.containerId} 未找到`);\n }\n \n return {\n ...config,\n container\n };\n}\n```\n\n## 🔗 相关文档\n\n- [API 参考](/zh-CN/api/) - 主要 API 文档\n- [生命周期](/zh-CN/api/lifecycles) - 详细的生命周期文档\n- [配置选项](/zh-CN/api/configuration) - 配置选项 " }, { "path": "docs/zh-CN/cookbook/error-handling.md", "content": "# 错误处理\n\n在同一上下文中运行多个独立应用的微前端应用程序中，健壮的错误处理至关重要。本指南涵盖了处理错误、实现优雅降级以及在基于 qiankun 的微前端系统中维护应用程序稳定性的综合策略。\n\n## 🎯 微前端中的错误类型\n\n### 常见错误类别\n\n微前端应用面临独特的错误场景：\n\n- **加载错误**：无法获取或解析微应用资源\n- **运行时错误**：微应用内的 JavaScript 错误\n- **通信错误**：应用间通信失败\n- **网络错误**：API 调用和资源加载失败\n- **沙箱错误**：JavaScript 和 CSS 隔离问题\n- **生命周期错误**：mount/unmount 过程中的问题\n- **版本冲突**：依赖版本不匹配\n\n### 错误影响评估\n\n```javascript\n// 微前端应用的错误严重程度级别\nconst ERROR_LEVELS = {\n CRITICAL: 'critical', // 主应用或核心功能受影响\n HIGH: 'high', // 主要微应用功能丢失\n MEDIUM: 'medium', // 部分微应用功能受影响\n LOW: 'low', // 轻微功能或视觉问题\n INFO: 'info' // 非阻塞性信息问题\n};\n\nconst ErrorClassifier = {\n classify(error, appName, context) {\n // 严重：主应用崩溃或核心导航失败\n if (appName === 'main' || context.includes('navigation')) {\n return ERROR_LEVELS.CRITICAL;\n }\n \n // 高：用户无法完成主要工作流程\n if (context.includes('checkout') || context.includes('auth')) {\n return ERROR_LEVELS.HIGH;\n }\n \n // 中等：功能降级但应用仍可使用\n if (error.name === 'ChunkLoadError' || error.name === 'TypeError') {\n return ERROR_LEVELS.MEDIUM;\n }\n \n // 其他错误默认为低级别\n return ERROR_LEVELS.LOW;\n }\n};\n```\n\n## 🛡️ qiankun 错误边界\n\n### 全局错误处理\n\n为整个微前端生态系统设置全局错误处理器：\n\n```javascript\nimport { addGlobalUncaughtErrorHandler, removeGlobalUncaughtErrorHandler } from 'qiankun';\n\n// 所有微应用的全局错误处理器\nconst globalErrorHandler = (event) => {\n const { error, appName, lifecycleName } = event;\n \n console.error(`微应用 \"${appName}\" 在 \"${lifecycleName}\" 阶段发生错误:`, error);\n \n // 上报到错误跟踪服务\n reportError({\n error,\n appName,\n lifecycle: lifecycleName,\n timestamp: Date.now(),\n userAgent: navigator.userAgent,\n url: window.location.href\n });\n \n // 实施恢复策略\n handleMicroAppError(appName, error, lifecycleName);\n};\n\n// 注册全局错误处理器\naddGlobalUncaughtErrorHandler(globalErrorHandler);\n\n// 清理时移除（例如在应用卸载时）\n// removeGlobalUncaughtErrorHandler(globalErrorHandler);\n```\n\n### 生命周期特定错误处理\n\n```javascript\n// 生命周期钩子中的错误处理\nconst errorHandlingLifecycles = {\n async beforeLoad(app) {\n try {\n // 预加载检查\n const healthCheck = await fetch(`${app.entry}/health`);\n if (!healthCheck.ok) {\n throw new Error(`${app.name} 健康检查失败`);\n }\n } catch (error) {\n console.warn(`${app.name} 预加载健康检查失败:`, error);\n // 继续加载但标记为可能不稳定\n markAppAsUnstable(app.name);\n }\n },\n\n async beforeMount(app) {\n try {\n // 验证应用要求\n validateAppRequirements(app);\n } catch (error) {\n // 尝试修复常见问题\n await attemptAutoFix(app, error);\n }\n },\n\n async afterMount(app) {\n // 验证挂载成功\n setTimeout(() => {\n const container = document.querySelector(app.container);\n if (!container || container.children.length === 0) {\n console.error(`${app.name} 挂载验证失败`);\n showFallbackContent(app.container, app.name);\n }\n }, 1000);\n },\n\n async beforeUnmount(app) {\n try {\n // 清理资源\n cleanupAppResources(app.name);\n } catch (error) {\n console.warn(`${app.name} 清理错误:`, error);\n // 强制清理\n forceCleanup(app.name);\n }\n }\n};\n```\n\n## 🚨 框架特定错误边界\n\n### React 错误边界\n\n```jsx\n// React 微应用错误边界\nimport React from 'react';\n\nclass MicroAppErrorBoundary extends React.Component {\n constructor(props) {\n super(props);\n this.state = {\n hasError: false,\n error: null,\n errorInfo: null,\n retryCount: 0,\n lastRetry: null\n };\n }\n\n static getDerivedStateFromError(error) {\n return { hasError: true };\n }\n\n componentDidCatch(error, errorInfo) {\n this.setState({\n error,\n errorInfo\n });\n\n // 上报错误\n this.reportError(error, errorInfo);\n\n // 尝试自动恢复\n this.attemptRecovery(error);\n }\n\n reportError = (error, errorInfo) => {\n const errorReport = {\n error: {\n name: error.name,\n message: error.message,\n stack: error.stack\n },\n errorInfo,\n appName: this.props.appName,\n timestamp: Date.now(),\n url: window.location.href,\n userAgent: navigator.userAgent,\n retryCount: this.state.retryCount\n };\n\n // 发送到错误跟踪服务\n fetch('/api/errors', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(errorReport)\n }).catch(err => console.error('上报错误失败:', err));\n };\n\n attemptRecovery = (error) => {\n const { retryCount, lastRetry } = this.state;\n const now = Date.now();\n \n // 防止过于频繁的重试\n if (lastRetry && now - lastRetry < 5000) {\n return;\n }\n \n // 限制重试次数\n if (retryCount >= 3) {\n console.error(`${this.props.appName} 已达到最大重试次数`);\n return;\n }\n\n setTimeout(() => {\n this.setState({\n hasError: false,\n error: null,\n errorInfo: null,\n retryCount: retryCount + 1,\n lastRetry: now\n });\n }, 2000 * Math.pow(2, retryCount)); // 指数退避\n };\n\n render() {\n if (this.state.hasError) {\n const { appName, fallbackComponent: FallbackComponent } = this.props;\n \n if (FallbackComponent) {\n return (\n this.attemptRecovery(this.state.error)}\n />\n );\n }\n\n return (\n
\n

应用错误

\n

{appName} 应用遇到了错误。

\n \n
\n 错误详情\n 
{this.state.error?.stack}
\n
\n
\n );\n }\n\n return this.props.children;\n }\n}\n\n// 微应用使用示例\nfunction MicroAppContainer({ appName, entry }) {\n return (\n \n
\n \n );\n}\n```\n\n### Vue 错误处理\n\n```javascript\n// Vue 微应用全局错误处理器\nconst app = createApp(MainApp);\n\napp.config.errorHandler = (err, instance, info) => {\n const appName = instance?.$root?.$options?.name || 'unknown';\n \n console.error(`Vue 错误在 ${appName}:`, err, info);\n \n // 上报错误\n reportVueError({\n error: err,\n appName,\n info,\n timestamp: Date.now()\n });\n \n // 尝试恢复\n if (instance && typeof instance.$forceUpdate === 'function') {\n instance.$forceUpdate();\n }\n};\n\n// Vue 2 错误边界组件\nVue.component('ErrorBoundary', {\n data() {\n return {\n hasError: false,\n error: null\n };\n },\n \n errorCaptured(err, instance, info) {\n this.hasError = true;\n this.error = err;\n \n // 上报错误\n this.reportError(err, info);\n \n // 阻止错误继续传播\n return false;\n },\n \n methods: {\n reportError(error, info) {\n // 错误上报逻辑\n },\n \n retry() {\n this.hasError = false;\n this.error = null;\n this.$forceUpdate();\n }\n },\n \n render(h) {\n if (this.hasError) {\n return h('div', { class: 'error-boundary' }, [\n h('h3', '出现了错误'),\n h('button', { on: { click: this.retry } }, '重试'),\n h('pre', this.error?.message)\n ]);\n }\n \n return this.$slots.default;\n }\n});\n```\n\n## 🔄 优雅降级策略\n\n### 渐进式增强\n\n```javascript\n// 带回退的渐进式功能加载\nclass FeatureLoader {\n constructor() {\n this.features = new Map();\n this.fallbacks = new Map();\n }\n \n register(featureName, loader, fallback) {\n this.features.set(featureName, loader);\n this.fallbacks.set(featureName, fallback);\n }\n \n async load(featureName) {\n try {\n const loader = this.features.get(featureName);\n if (!loader) {\n throw new Error(`功能 \"${featureName}\" 未注册`);\n }\n \n const feature = await loader();\n return feature;\n \n } catch (error) {\n console.warn(`加载功能 \"${featureName}\" 失败:`, error);\n \n const fallback = this.fallbacks.get(featureName);\n if (fallback) {\n return await fallback();\n }\n \n throw error;\n }\n }\n}\n\n// 使用示例\nconst featureLoader = new FeatureLoader();\n\n// 注册高级仪表板和回退\nfeatureLoader.register(\n 'advanced-dashboard',\n () => import('./AdvancedDashboard'),\n () => import('./BasicDashboard')\n);\n\n// 注册图表组件和静态回退\nfeatureLoader.register(\n 'interactive-charts',\n () => import('./InteractiveCharts'),\n () => Promise.resolve(() => '
图表不可用
')\n);\n```\n\n### 回退 UI 组件\n\n```jsx\n// 综合回退组件\nconst ErrorFallbacks = {\n // 网络错误回退\n NetworkError: ({ onRetry, appName }) => (\n
\n
🌐
\n

连接问题

\n

无法加载 {appName}。请检查您的网络连接。

\n
\n \n \n
\n
\n ),\n\n // JavaScript 错误回退\n JavaScriptError: ({ error, appName, onRetry }) => (\n
\n
⚠️
\n

应用错误

\n

{appName} 应用遇到技术问题。

\n
\n \n \n
\n {process.env.NODE_ENV === 'development' && (\n
\n 技术详情\n 
{error.stack}
\n
\n )}\n
\n ),\n\n // 加载超时回退\n LoadingTimeout: ({ appName, onRetry }) => (\n
\n
⏱️
\n

加载超时

\n

{appName} 加载时间超出预期。

\n
\n \n \n
\n
\n ),\n\n // 通用回退\n Generic: ({ error, appName, onRetry }) => (\n
\n
🔧
\n

临时问题

\n

我们正在处理 {appName} 的技术困难。

\n
\n \n
\n
\n )\n};\n```\n\n### 熔断器模式\n\n```javascript\n// 微应用加载的熔断器\nclass CircuitBreaker {\n constructor(threshold = 5, timeout = 60000, monitor = 30000) {\n this.failureThreshold = threshold;\n this.timeout = timeout;\n this.monitoringPeriod = monitor;\n this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN\n this.failureCount = 0;\n this.lastFailureTime = null;\n this.nextAttemptTime = null;\n }\n\n async execute(operation, appName) {\n if (this.state === 'OPEN') {\n if (Date.now() < this.nextAttemptTime) {\n throw new Error(`${appName} 的熔断器是 OPEN 状态`);\n }\n this.state = 'HALF_OPEN';\n }\n\n try {\n const result = await operation();\n this.onSuccess();\n return result;\n } catch (error) {\n this.onFailure();\n throw error;\n }\n }\n\n onSuccess() {\n this.failureCount = 0;\n this.state = 'CLOSED';\n }\n\n onFailure() {\n this.failureCount++;\n this.lastFailureTime = Date.now();\n\n if (this.failureCount >= this.failureThreshold) {\n this.state = 'OPEN';\n this.nextAttemptTime = Date.now() + this.timeout;\n }\n }\n\n getState() {\n return this.state;\n }\n}\n\n// 使用熔断器加载微应用\nconst circuitBreakers = new Map();\n\nconst loadMicroAppWithCircuitBreaker = async (appConfig) => {\n const { name } = appConfig;\n \n if (!circuitBreakers.has(name)) {\n circuitBreakers.set(name, new CircuitBreaker());\n }\n \n const breaker = circuitBreakers.get(name);\n \n try {\n return await breaker.execute(() => loadMicroApp(appConfig), name);\n } catch (error) {\n console.error(`熔断器阻止了 ${name} 的加载:`, error);\n throw error;\n }\n};\n```\n\n## 📊 错误监控和上报\n\n### 综合错误跟踪\n\n```javascript\n// 高级错误跟踪系统\nclass ErrorTracker {\n constructor(config) {\n this.config = {\n endpoint: '/api/errors',\n batchSize: 10,\n batchTimeout: 5000,\n maxRetries: 3,\n ...config\n };\n \n this.errorQueue = [];\n this.batchTimeout = null;\n this.retryCount = new Map();\n }\n\n track(error, context = {}) {\n const errorData = this.serializeError(error, context);\n \n // 添加到队列\n this.errorQueue.push(errorData);\n \n // 如果队列已满则处理批次\n if (this.errorQueue.length >= this.config.batchSize) {\n this.processBatch();\n } else {\n // 设置批次处理超时\n this.scheduleBatchProcessing();\n }\n }\n\n serializeError(error, context) {\n return {\n id: this.generateErrorId(),\n timestamp: Date.now(),\n error: {\n name: error.name,\n message: error.message,\n stack: error.stack,\n fileName: error.fileName,\n lineNumber: error.lineNumber,\n columnNumber: error.columnNumber\n },\n context: {\n appName: context.appName || 'unknown',\n userId: context.userId,\n sessionId: this.getSessionId(),\n url: window.location.href,\n userAgent: navigator.userAgent,\n viewport: {\n width: window.innerWidth,\n height: window.innerHeight\n },\n ...context\n },\n environment: {\n isDevelopment: process.env.NODE_ENV === 'development',\n timestamp: Date.now(),\n timezone: Intl.DateTimeFormat().resolvedOptions().timeZone\n }\n };\n }\n\n scheduleBatchProcessing() {\n if (this.batchTimeout) {\n clearTimeout(this.batchTimeout);\n }\n \n this.batchTimeout = setTimeout(() => {\n this.processBatch();\n }, this.config.batchTimeout);\n }\n\n async processBatch() {\n if (this.errorQueue.length === 0) return;\n \n const batch = this.errorQueue.splice(0, this.config.batchSize);\n \n try {\n await this.sendErrors(batch);\n \n // 成功时清除重试计数\n batch.forEach(error => {\n this.retryCount.delete(error.id);\n });\n \n } catch (error) {\n console.error('发送错误批次失败:', error);\n \n // 重试逻辑\n batch.forEach(errorData => {\n const retries = this.retryCount.get(errorData.id) || 0;\n if (retries < this.config.maxRetries) {\n this.retryCount.set(errorData.id, retries + 1);\n this.errorQueue.unshift(errorData); // 添加回队列前端\n }\n });\n }\n }\n\n async sendErrors(errors) {\n const response = await fetch(this.config.endpoint, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ errors })\n });\n\n if (!response.ok) {\n throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n }\n\n return response.json();\n }\n\n generateErrorId() {\n return `error_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;\n }\n\n getSessionId() {\n // 获取/生成会话ID的实现\n return sessionStorage.getItem('sessionId') || 'anonymous';\n }\n}\n\n// 初始化全局错误跟踪器\nconst errorTracker = new ErrorTracker();\n\n// 跟踪未处理的错误\nwindow.addEventListener('error', (event) => {\n errorTracker.track(event.error, {\n type: 'unhandled_error',\n source: 'window.onerror'\n });\n});\n\n// 跟踪未处理的 Promise 拒绝\nwindow.addEventListener('unhandledrejection', (event) => {\n errorTracker.track(event.reason, {\n type: 'unhandled_rejection',\n source: 'unhandledrejection'\n });\n});\n```\n\n### 性能影响监控\n\n```javascript\n// 监控错误对性能的影响\nclass ErrorImpactMonitor {\n constructor() {\n this.errorImpacts = new Map();\n this.performanceBaseline = this.measureBaseline();\n }\n\n measureBaseline() {\n return {\n loadTime: performance.now(),\n memoryUsage: performance.memory ? performance.memory.usedJSHeapSize : 0,\n timing: performance.timing\n };\n }\n\n recordErrorImpact(errorId, appName) {\n const impact = {\n errorId,\n appName,\n timestamp: Date.now(),\n performance: {\n loadTime: performance.now(),\n memoryUsage: performance.memory ? performance.memory.usedJSHeapSize : 0,\n timing: performance.timing\n },\n userExperience: {\n pageVisible: !document.hidden,\n userActive: this.isUserActive(),\n scrollPosition: window.scrollY\n }\n };\n\n this.errorImpacts.set(errorId, impact);\n this.analyzeImpact(impact);\n }\n\n analyzeImpact(impact) {\n const { performance: current } = impact;\n const baseline = this.performanceBaseline;\n\n const memoryIncrease = current.memoryUsage - baseline.memoryUsage;\n const loadTimeIncrease = current.loadTime - baseline.loadTime;\n\n if (memoryIncrease > 50 * 1024 * 1024) { // 50MB\n console.warn('错误后检测到高内存影响:', impact);\n }\n\n if (loadTimeIncrease > 5000) { // 5秒\n console.warn('错误后性能显著降级:', impact);\n }\n }\n\n isUserActive() {\n // 简单用户活动检测\n return Date.now() - this.lastUserActivity < 30000;\n }\n}\n```\n\n## 🔧 恢复机制\n\n### 自动恢复策略\n\n```javascript\n// 综合恢复系统\nclass RecoveryManager {\n constructor() {\n this.recoveryStrategies = new Map();\n this.setupDefaultStrategies();\n }\n\n setupDefaultStrategies() {\n // 网络错误恢复\n this.register('NetworkError', async (error, context) => {\n await this.waitForConnection();\n return this.reloadMicroApp(context.appName);\n });\n\n // 块加载错误恢复\n this.register('ChunkLoadError', async (error, context) => {\n // 清除 webpack 缓存\n if (window.__webpack_require__ && window.__webpack_require__.cache) {\n delete window.__webpack_require__.cache[error.request];\n }\n \n // 使用缓存破坏重新加载\n return this.reloadWithCacheBust(context.appName);\n });\n\n // 脚本错误恢复\n this.register('TypeError', async (error, context) => {\n // 尝试重新加载依赖\n await this.reloadDependencies(context.appName);\n return this.remountMicroApp(context.appName);\n });\n\n // 内存错误恢复\n this.register('RangeError', async (error, context) => {\n // 强制垃圾回收\n if (window.gc) window.gc();\n \n // 减少内存占用\n await this.reducememoryFootprint(context.appName);\n return this.reloadMicroApp(context.appName);\n });\n }\n\n register(errorType, strategy) {\n this.recoveryStrategies.set(errorType, strategy);\n }\n\n async recover(error, context) {\n const strategy = this.recoveryStrategies.get(error.name);\n \n if (strategy) {\n try {\n console.log(`尝试恢复 ${context.appName} 中的 ${error.name}`);\n const result = await strategy(error, context);\n console.log(`${context.appName} 恢复成功`);\n return result;\n } catch (recoveryError) {\n console.error(`${context.appName} 恢复失败:`, recoveryError);\n return this.fallbackRecovery(context);\n }\n }\n \n return this.fallbackRecovery(context);\n }\n\n async waitForConnection() {\n return new Promise((resolve) => {\n if (navigator.onLine) {\n resolve();\n } else {\n const handleOnline = () => {\n window.removeEventListener('online', handleOnline);\n resolve();\n };\n window.addEventListener('online', handleOnline);\n }\n });\n }\n\n async reloadMicroApp(appName) {\n // 卸载当前实例\n try {\n await unmountMicroApp(appName);\n } catch (error) {\n console.warn(`卸载 ${appName} 失败:`, error);\n }\n\n // 重新加载微应用\n const appConfig = getAppConfig(appName);\n return loadMicroApp(appConfig);\n }\n\n async reloadWithCacheBust(appName) {\n const appConfig = getAppConfig(appName);\n const cacheBustEntry = `${appConfig.entry}?t=${Date.now()}`;\n \n return loadMicroApp({\n ...appConfig,\n entry: cacheBustEntry\n });\n }\n\n async fallbackRecovery(context) {\n console.log(`使用 ${context.appName} 的回退恢复`);\n \n // 显示回退 UI\n showFallbackUI(context.appName);\n \n // 报告恢复失败\n reportRecoveryFailure(context);\n \n return null;\n }\n}\n```\n\n### 用户发起的恢复\n\n```jsx\n// 用户控制的恢复界面\nconst RecoveryPanel = ({ appName, error, onRecover, onDismiss }) => {\n const [recovering, setRecovering] = useState(false);\n const [lastAttempt, setLastAttempt] = useState(null);\n\n const handleRecover = async (strategy) => {\n setRecovering(true);\n setLastAttempt(Date.now());\n \n try {\n await onRecover(strategy);\n } catch (error) {\n console.error('用户发起的恢复失败:', error);\n } finally {\n setRecovering(false);\n }\n };\n\n const recoveryOptions = [\n {\n key: 'reload',\n label: '重新加载应用',\n description: '从头重启应用',\n action: () => handleRecover('reload')\n },\n {\n key: 'reset',\n label: '重置为默认',\n description: '清除所有数据并重新加载',\n action: () => handleRecover('reset')\n },\n {\n key: 'safe-mode',\n label: '安全模式',\n description: '以最小功能加载',\n action: () => handleRecover('safe-mode')\n }\n ];\n\n return (\n
\n
\n

{appName} 的恢复选项

\n \n
\n \n
\n

错误: {error.message}

\n {lastAttempt && (\n

上次尝试: {new Date(lastAttempt).toLocaleTimeString()}

\n )}\n
\n \n
\n {recoveryOptions.map(option => (\n \n
{option.label}
\n
{option.description}
\n \n ))}\n
\n \n {recovering && (\n
\n
\n 正在尝试恢复...\n
\n )}\n
\n );\n};\n```\n\n## 🎯 最佳实践总结\n\n### ✅ 错误处理要做的\n\n1. **实施全局错误处理器**进行全面覆盖\n2. **在每个微应用中使用错误边界**\n3. **为用户提供有意义的错误消息**\n4. **实施带回退 UI 的优雅降级**\n5. **系统性地监控和跟踪错误**\n6. **在开发过程中测试错误场景**\n7. **在可能的地方实施自动恢复**\n8. **在报告中清除错误上下文**\n9. **优雅地处理网络故障**\n10. **提供用户恢复选项**\n\n### ❌ 错误处理不要做的\n\n1. **不要忽略错误**或静默失败\n2. **不要向最终用户显示技术细节**\n3. **不要无限制地重试**\n4. **不要因为一个微应用错误阻塞整个应用**\n5. **不要忘记在错误后清理**\n6. **不要完全依赖自动恢复**\n7. **不要用错误消息让用户不知所措**\n8. **不要忘记错误场景中的内存泄漏**\n9. **不要跳过生产环境类似环境的错误测试**\n10. **不要忽略用户关于错误的反馈**\n\n### 🔄 错误恢复检查清单\n\n```javascript\n// 综合错误处理检查清单\nconst errorHandlingChecklist = {\n prevention: {\n validation: '✓ 已实施输入验证',\n typeChecking: '✓ 使用 TypeScript 或 PropTypes',\n testing: '✓ 已测试错误场景',\n monitoring: '✓ 健康检查已就位'\n },\n \n detection: {\n globalHandlers: '✓ 已设置全局错误处理器',\n boundaries: '✓ 已实施错误边界',\n logging: '✓ 全面错误日志记录',\n alerting: '✓ 实时错误警报'\n },\n \n recovery: {\n gracefulDegradation: '✓ 已实施回退 UI',\n automaticRecovery: '✓ 自动恢复策略',\n userRecovery: '✓ 用户发起的恢复选项',\n resourceCleanup: '✓ 错误时适当清理'\n },\n \n learning: {\n errorTracking: '✓ 错误分析已就位',\n trendAnalysis: '✓ 错误趋势监控',\n rootCauseAnalysis: '✓ RCA 流程已定义',\n continuousImprovement: '✓ 定期错误审查会议'\n }\n};\n```\n\n## 🔗 相关文档\n\n- [性能优化](/cookbook/performance) - 错误对性能的影响\n- [调试](/cookbook/debugging) - 错误调试技术\n- [样式隔离](/cookbook/style-isolation) - CSS 错误处理\n- [配置](/api/configuration) - 错误相关配置 " }, { "path": "docs/zh-CN/cookbook/index.md", "content": "# 最佳实践\n\n本节包含使用 qiankun 构建生产级微前端应用的实用指南和最佳实践。这些指南基于真实世界的经验和实施微前端架构时面临的常见挑战。\n\n## 🎯 概述\n\n构建微前端需要仔细考虑各个方面，包括架构设计、性能优化、开发工作流和部署策略。这些指南将帮助你避免常见陷阱并实施稳健的解决方案。\n\n## 📚 可用指南\n\n### 🎨 [样式隔离](/zh-CN/cookbook/style-isolation)\n\n学习如何防止微应用之间的 CSS 冲突并实施有效的样式隔离策略。\n\n**你将学到：**\n- CSS 隔离技术\n- Shadow DOM 实现\n- CSS 作用域策略\n- 运行时样式冲突解决\n- 组件库最佳实践\n\n### ⚡ [性能优化](/zh-CN/cookbook/performance)\n\n优化你的微前端应用以获得更好的加载时间和运行时性能。\n\n**你将学到：**\n- 资源加载优化\n- 包拆分策略\n- 缓存机制\n- 懒加载技术\n- 性能监控\n\n### 🛠️ [错误处理](/zh-CN/cookbook/error-handling)\n\n为微前端应用实施稳健的错误处理和恢复机制。\n\n**你将学到：**\n- 错误边界实现\n- 优雅降级策略\n- 错误监控和报告\n- 恢复机制\n- 用户体验考虑\n\n### 🔍 [调试和开发](/zh-CN/cookbook/debugging)\n\n掌握微前端应用的调试技术和开发工作流。\n\n**你将学到：**\n- 开发环境设置\n- 调试工具和技术\n- 热重载配置\n- 跨应用调试\n- 生产调试策略\n\n### 🚀 [部署策略](/zh-CN/cookbook/deployment)\n\n学习微前端应用的部署模式和 CI/CD 策略。\n\n**你将学到：**\n- 独立部署工作流\n- 版本管理\n- 回滚策略\n- 环境配置\n- 零停机部署\n\n### 🔄 [状态管理](/zh-CN/cookbook/state-management)\n\n在微应用之间实施有效的状态管理。\n\n**你将学到：**\n- 跨应用状态共享\n- 事件驱动通信\n- 状态同步\n- 数据流模式\n- 存储管理\n\n### 🌐 [路由和导航](/zh-CN/cookbook/routing)\n\n为微前端应用设计和实施导航模式。\n\n**你将学到：**\n- 路由配置策略\n- 深度链接支持\n- 导航守卫\n- 历史管理\n- SEO 考虑\n\n### 🔒 [安全](/zh-CN/cookbook/security)\n\n为微前端架构实施安全最佳实践。\n\n**你将学到：**\n- 内容安全策略 (CSP)\n- 跨源资源共享 (CORS)\n- 身份验证和授权\n- 安全通信模式\n- 漏洞防护\n\n### 🧪 [测试策略](/zh-CN/cookbook/testing)\n\n为微前端应用开发全面的测试策略。\n\n**你将学到：**\n- 微应用单元测试\n- 集成测试策略\n- 端到端测试\n- 视觉回归测试\n- 性能测试\n\n### 📊 [监控和分析](/zh-CN/cookbook/monitoring)\n\n为微前端应用实施监控和分析。\n\n**你将学到：**\n- 性能监控\n- 错误跟踪\n- 用户分析\n- 应用健康检查\n- 业务指标\n\n## 🎯 入门指南\n\n如果你是 qiankun 或微前端的新手，我们建议按以下顺序开始这些指南：\n\n1. **[样式隔离](/zh-CN/cookbook/style-isolation)** - 防止 CSS 冲突的必备知识\n2. **[错误处理](/zh-CN/cookbook/error-handling)** - 生产稳定性的关键\n3. **[性能优化](/zh-CN/cookbook/performance)** - 用户体验的重要因素\n4. **[调试和开发](/zh-CN/cookbook/debugging)** - 提高开发效率\n\n## 🏗️ 常见模式\n\n### 微前端架构模式\n\n```mermaid\ngraph TB\n A[主应用] --> B[用户管理]\n A --> C[产品目录]\n A --> D[购物车]\n A --> E[订单处理]\n \n B --> F[用户服务]\n C --> G[产品服务]\n D --> H[购物车服务]\n E --> I[订单服务]\n \n F --> J[用户数据库]\n G --> K[产品数据库]\n H --> L[会话存储]\n I --> M[订单数据库]\n```\n\n### 通信模式\n\n```mermaid\nsequenceDiagram\n participant M as 主应用\n participant A as 微应用 A\n participant B as 微应用 B\n participant S as 共享存储\n \n M->>A: 加载并挂载\n A->>S: 订阅事件\n M->>B: 加载并挂载\n B->>S: 订阅事件\n \n A->>S: 发出事件\n S->>B: 通知事件\n B->>S: 更新状态\n S->>A: 广播更新\n```\n\n## 🎪 真实世界示例\n\n### 电商平台\n\n典型的电商平台可能结构如下：\n\n- **主应用**：导航、布局、用户会话\n- **产品目录**：浏览和搜索产品\n- **购物车**：管理购物车项目和结账\n- **用户账户**：个人资料管理和订单历史\n- **管理面板**：内容管理和分析\n\n### 企业仪表板\n\n企业仪表板可能包括：\n\n- **主框架**：身份验证和导航\n- **分析模块**：商业智能和报告\n- **用户管理**：角色和权限管理\n- **内容管理**：动态内容编辑\n- **设置模块**：系统配置\n\n## ⚠️ 常见陷阱\n\n### 1. 过度工程化\n\n**问题**：为小功能创建太多微应用。\n\n**解决方案**：从单体开始，当团队或领域自然分离时再提取微应用。\n\n### 2. 共享依赖\n\n**问题**：微应用共享依赖导致版本冲突。\n\n**解决方案**：使用适当的打包策略，考虑为共享库使用模块联邦。\n\n### 3. 性能问题\n\n**问题**：多个微应用同时加载导致性能下降。\n\n**解决方案**：实施懒加载、适当的缓存和资源优化。\n\n### 4. 测试复杂性\n\n**问题**：独立测试微应用无法捕获集成问题。\n\n**解决方案**：在单元测试的基础上实施全面的集成测试。\n\n## 🔧 开发工作流\n\n### 推荐的开发流程\n\n1. **设计阶段**\n - 定义应用边界\n - 规划通信模式\n - 设计共享接口\n\n2. **开发阶段**\n - 设置开发环境\n - 实现微应用\n - 配置构建和部署\n\n3. **测试阶段**\n - 单独的应用单元测试\n - 完整系统集成测试\n - 性能和安全测试\n\n4. **部署阶段**\n - 独立部署应用\n - 监控应用健康\n - 实施回滚策略\n\n### 团队组织\n\n```mermaid\ngraph LR\n A[平台团队] --> B[共享基础设施]\n A --> C[主应用]\n \n D[功能团队 1] --> E[微应用 1]\n F[功能团队 2] --> G[微应用 2]\n H[功能团队 3] --> I[微应用 3]\n \n B --> E\n B --> G\n B --> I\n```\n\n## 📖 进一步阅读\n\n- [微前端架构](https://micro-frontends.org/)\n- [模块联邦](https://webpack.js.org/concepts/module-federation/)\n- [Single-SPA 文档](https://single-spa.js.org/)\n- [qiankun GitHub 仓库](https://github.com/umijs/qiankun)\n\n## 🤝 贡献\n\n有想要分享的模式或实践吗？欢迎为手册贡献内容！请遵循我们的[贡献指南](https://github.com/umijs/qiankun/blob/master/CONTRIBUTING.md)。\n\n## 🔗 相关文档\n\n- [API 参考](/zh-CN/api/) - 完整的 API 文档\n- [快速开始指南](/zh-CN/guide/quick-start) - qiankun 入门\n- [生态系统](/zh-CN/ecosystem/) - UI 绑定和工具 " }, { "path": "docs/zh-CN/cookbook/performance.md", "content": "# 性能优化\n\n对于微前端应用来说，性能至关重要。由于多个应用同时加载和运行，优化资源加载、运行时性能和用户体验非常重要。本指南涵盖了优化基于 qiankun 的微前端应用的综合策略。\n\n## 🎯 性能概述\n\n### 常见性能挑战\n\n微前端架构引入了独特的性能考虑因素：\n\n- **多包加载**：每个微应用都加载自己的 JavaScript 和 CSS\n- **资源重复**：共享依赖被多次加载\n- **运行时开销**：多个应用实例同时运行\n- **网络延迟**：每个微应用的额外 HTTP 请求\n- **内存使用**：多个应用导致内存消耗增加\n\n### 需要监控的性能指标\n\n```javascript\n// 微前端性能的关键指标\nconst performanceMetrics = {\n // 加载性能\n timeToFirstByte: 'TTFB',\n firstContentfulPaint: 'FCP',\n largestContentfulPaint: 'LCP',\n \n // 交互性\n firstInputDelay: 'FID',\n timeToInteractive: 'TTI',\n \n // 微前端特定\n microAppLoadTime: '自定义指标',\n microAppMountTime: '自定义指标',\n totalBundleSize: '自定义指标'\n};\n```\n\n## 🚀 资源加载优化\n\n### 预取策略\n\nqiankun 提供了几种预取选项来改善加载性能：\n\n#### 基础预取\n\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n prefetch: true // 启用默认预取\n});\n```\n\n#### 选择性预取\n\n```javascript\nstart({\n prefetch: ['critical-app-1', 'critical-app-2'] // 只预取特定应用\n});\n```\n\n#### 智能预取\n\n```javascript\nstart({\n prefetch: (apps) => {\n // 基于用户行为、时间或网络条件的自定义预取逻辑\n const now = new Date().getHours();\n const isBusinessHours = now >= 9 && now <= 17;\n \n if (isBusinessHours) {\n return {\n criticalAppNames: ['dashboard', 'user-management'],\n minorAppsName: ['analytics']\n };\n }\n \n return {\n criticalAppNames: ['dashboard'],\n minorAppsName: []\n };\n }\n});\n```\n\n#### 网络感知预取\n\n```javascript\n// 基于网络条件的高级预取\nconst networkAwarePrefetch = (apps) => {\n const connection = navigator.connection || navigator.mozConnection || navigator.webkitConnection;\n \n if (!connection) {\n // 未知连接的默认行为\n return { criticalAppNames: apps.slice(0, 2), minorAppsName: [] };\n }\n \n const effectiveType = connection.effectiveType;\n const saveData = connection.saveData;\n \n if (saveData || effectiveType === 'slow-2g' || effectiveType === '2g') {\n // 慢速连接的最小预取\n return { criticalAppNames: [], minorAppsName: [] };\n }\n \n if (effectiveType === '3g') {\n // 3G 的适度预取\n return { criticalAppNames: apps.slice(0, 1), minorAppsName: [] };\n }\n \n // 4G 及以上的积极预取\n return {\n criticalAppNames: apps.slice(0, 3),\n minorAppsName: apps.slice(3)\n };\n};\n\nstart({\n prefetch: networkAwarePrefetch\n});\n```\n\n### 懒加载\n\n#### 基于路由的懒加载\n\n```javascript\n// 只在访问路由时加载微应用\nregisterMicroApps([\n {\n name: 'user-management',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/users',\n // 应用只在访问 /users 路由时加载\n },\n {\n name: 'analytics',\n entry: '//localhost:8081',\n container: '#container',\n activeRule: '/analytics',\n // 按需加载\n }\n]);\n```\n\n#### 条件加载\n\n```javascript\n// 基于用户权限或功能加载微应用\nconst userPermissions = getCurrentUserPermissions();\n\nconst microApps = [\n {\n name: 'dashboard',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/dashboard'\n }\n];\n\n// 有条件地添加管理应用\nif (userPermissions.includes('admin')) {\n microApps.push({\n name: 'admin-panel',\n entry: '//localhost:8082',\n container: '#container',\n activeRule: '/admin'\n });\n}\n\nregisterMicroApps(microApps);\n```\n\n#### 使用 Intersection Observer 进行懒加载\n\n```javascript\n// 当微应用进入视口时加载\nconst observerCallback = (entries, observer) => {\n entries.forEach(entry => {\n if (entry.isIntersecting) {\n const appName = entry.target.dataset.app;\n loadMicroApp({\n name: appName,\n entry: entry.target.dataset.entry,\n container: entry.target\n });\n observer.unobserve(entry.target);\n }\n });\n};\n\nconst observer = new IntersectionObserver(observerCallback, {\n threshold: 0.1\n});\n\ndocument.querySelectorAll('[data-lazy-app]').forEach(el => {\n observer.observe(el);\n});\n```\n\n## 📦 打包优化\n\n### 代码分割\n\n#### 微应用级别分割\n\n```javascript\n// 微应用的 webpack.config.js\nmodule.exports = {\n optimization: {\n splitChunks: {\n chunks: 'all',\n cacheGroups: {\n vendor: {\n test: /[\\\\/]node_modules[\\\\/]/,\n name: 'vendors',\n chunks: 'all',\n priority: 10\n },\n common: {\n name: 'common',\n minChunks: 2,\n chunks: 'all',\n priority: 5\n }\n }\n }\n }\n};\n```\n\n#### 微应用中的动态导入\n\n```javascript\n// 带动态导入的 React 组件\nimport React, { Suspense, lazy } from 'react';\n\nconst HeavyComponent = lazy(() => import('./HeavyComponent'));\n\nfunction MyMicroApp() {\n return (\n
\n

微应用

\n 加载重组件中...
}>\n \n \n
\n );\n}\n```\n\n### 共享依赖\n\n#### 外部依赖\n\n```javascript\n// webpack.config.js - 外部化共享库\nmodule.exports = {\n externals: {\n 'react': 'React',\n 'react-dom': 'ReactDOM',\n 'lodash': '_',\n 'moment': 'moment'\n }\n};\n```\n\n#### 模块联邦\n\n```javascript\n// 主应用的 webpack.config.js\nconst ModuleFederationPlugin = require('@module-federation/webpack');\n\nmodule.exports = {\n plugins: [\n new ModuleFederationPlugin({\n name: 'shell',\n shared: {\n react: {\n singleton: true,\n requiredVersion: '^18.0.0'\n },\n 'react-dom': {\n singleton: true,\n requiredVersion: '^18.0.0'\n }\n }\n })\n ]\n};\n\n// 微应用的 webpack.config.js\nmodule.exports = {\n plugins: [\n new ModuleFederationPlugin({\n name: 'microApp',\n shared: {\n react: {\n singleton: true,\n requiredVersion: '^18.0.0'\n },\n 'react-dom': {\n singleton: true,\n requiredVersion: '^18.0.0'\n }\n }\n })\n ]\n};\n```\n\n## 🏎️ 运行时性能\n\n### 内存管理\n\n#### 卸载时清理\n\n```javascript\n// 生命周期钩子中的适当清理\nconst lifeCycles = {\n async afterUnmount(app) {\n // 清除定时器\n if (window.microAppTimers) {\n window.microAppTimers.forEach(timer => clearInterval(timer));\n window.microAppTimers = [];\n }\n \n // 移除事件监听器\n if (window.microAppListeners) {\n window.microAppListeners.forEach(({ element, event, handler }) => {\n element.removeEventListener(event, handler);\n });\n window.microAppListeners = [];\n }\n \n // 清除缓存\n if (window.microAppCache) {\n window.microAppCache.clear();\n }\n \n // 强制垃圾回收（如果可用）\n if (window.gc) {\n window.gc();\n }\n }\n};\n```\n\n#### 内存泄漏检测\n\n```javascript\n// 监控内存使用情况\nconst memoryMonitor = {\n baseline: null,\n \n measureBaseline() {\n this.baseline = performance.memory ? {\n usedJSHeapSize: performance.memory.usedJSHeapSize,\n totalJSHeapSize: performance.memory.totalJSHeapSize\n } : null;\n },\n \n checkForLeaks(appName) {\n if (!performance.memory || !this.baseline) return;\n \n const current = {\n usedJSHeapSize: performance.memory.usedJSHeapSize,\n totalJSHeapSize: performance.memory.totalJSHeapSize\n };\n \n const growth = current.usedJSHeapSize - this.baseline.usedJSHeapSize;\n const growthMB = growth / (1024 * 1024);\n \n if (growthMB > 50) { // 如果内存增长超过50MB则警告\n console.warn(`${appName} 中可能存在内存泄漏: ${growthMB.toFixed(2)}MB 增长`);\n }\n }\n};\n```\n\n### 虚拟 DOM 优化\n\n#### React 优化\n\n```javascript\n// 优化 React 微应用\nimport React, { memo, useMemo, useCallback } from 'react';\n\nconst OptimizedComponent = memo(({ data, onUpdate }) => {\n // 记忆化昂贵的计算\n const processedData = useMemo(() => {\n return data.map(item => ({\n ...item,\n calculated: expensiveCalculation(item)\n }));\n }, [data]);\n \n // 记忆化事件处理器\n const handleUpdate = useCallback((id, newValue) => {\n onUpdate(id, newValue);\n }, [onUpdate]);\n \n return (\n
\n {processedData.map(item => (\n \n ))}\n
\n );\n});\n```\n\n#### Vue 优化\n\n```vue\n\n\n\n```\n\n## 🗄️ 缓存策略\n\n### HTTP 缓存\n\n#### 微应用资源\n\n```javascript\n// 为微应用资源配置缓存头\n// nginx.conf\nserver {\n location ~* \\.(js|css|png|jpg|jpeg|gif|svg|woff|woff2)$ {\n expires 1y;\n add_header Cache-Control \"public, immutable\";\n add_header Vary \"Accept-Encoding\";\n }\n \n location /api/ {\n expires -1;\n add_header Cache-Control \"no-cache, no-store, must-revalidate\";\n }\n}\n```\n\n#### Service Worker 缓存\n\n```javascript\n// sw.js - 微应用缓存的 Service Worker\nconst CACHE_NAME = 'micro-app-cache-v1';\nconst MICRO_APP_URLS = [\n '/micro-app-1/static/js/main.js',\n '/micro-app-1/static/css/main.css',\n '/micro-app-2/static/js/main.js',\n '/micro-app-2/static/css/main.css'\n];\n\nself.addEventListener('install', event => {\n event.waitUntil(\n caches.open(CACHE_NAME)\n .then(cache => cache.addAll(MICRO_APP_URLS))\n );\n});\n\nself.addEventListener('fetch', event => {\n if (MICRO_APP_URLS.some(url => event.request.url.includes(url))) {\n event.respondWith(\n caches.match(event.request)\n .then(response => response || fetch(event.request))\n );\n }\n});\n```\n\n### 应用级缓存\n\n#### 智能应用缓存\n\n```javascript\n// 缓存微应用实例以便更快地重新挂载\nclass MicroAppCache {\n constructor() {\n this.cache = new Map();\n this.maxSize = 5;\n }\n \n set(appName, appInstance) {\n if (this.cache.size >= this.maxSize) {\n // 移除最少使用的应用\n const firstKey = this.cache.keys().next().value;\n this.cache.delete(firstKey);\n }\n \n this.cache.set(appName, {\n instance: appInstance,\n timestamp: Date.now()\n });\n }\n \n get(appName) {\n const cached = this.cache.get(appName);\n if (cached) {\n // 移动到末尾（标记为最近使用）\n this.cache.delete(appName);\n this.cache.set(appName, cached);\n return cached.instance;\n }\n return null;\n }\n \n has(appName) {\n return this.cache.has(appName);\n }\n \n clear() {\n this.cache.clear();\n }\n}\n\nconst appCache = new MicroAppCache();\n```\n\n## ⚡ 网络优化\n\n### 连接优化\n\n#### HTTP/2 推送\n\n```javascript\n// 带有微应用资源 HTTP/2 推送的 Express.js 服务器\nconst express = require('express');\nconst spdy = require('spdy');\n\nconst app = express();\n\napp.get('/main-app', (req, res) => {\n // 推送关键微应用资源\n res.push('/micro-app-1/static/js/main.js');\n res.push('/micro-app-1/static/css/main.css');\n \n res.sendFile(__dirname + '/index.html');\n});\n\nconst server = spdy.createServer(options, app);\n```\n\n#### 资源提示\n\n```html\n\n\n \n \n \n \n \n \n \n \n \n \n\n```\n\n### CDN 策略\n\n#### 多 CDN 设置\n\n```javascript\n// 基于性能的智能 CDN 选择\nclass CDNManager {\n constructor() {\n this.cdns = [\n 'https://cdn1.example.com',\n 'https://cdn2.example.com',\n 'https://cdn3.example.com'\n ];\n this.performanceCache = new Map();\n }\n \n async getBestCDN() {\n if (this.performanceCache.size === 0) {\n await this.measureCDNPerformance();\n }\n \n // 返回最快的 CDN\n return [...this.performanceCache.entries()]\n .sort((a, b) => a[1] - b[1])[0][0];\n }\n \n async measureCDNPerformance() {\n const promises = this.cdns.map(async (cdn) => {\n const start = performance.now();\n try {\n await fetch(`${cdn}/health-check`);\n const latency = performance.now() - start;\n this.performanceCache.set(cdn, latency);\n } catch (error) {\n this.performanceCache.set(cdn, Infinity);\n }\n });\n \n await Promise.all(promises);\n }\n}\n```\n\n## 📊 性能监控\n\n### 实时指标\n\n#### Performance Observer\n\n```javascript\n// 监控微应用加载性能\nclass MicroAppPerformanceMonitor {\n constructor() {\n this.metrics = new Map();\n this.initObservers();\n }\n \n initObservers() {\n // 监控加载性能\n if ('PerformanceObserver' in window) {\n const loadObserver = new PerformanceObserver((list) => {\n for (const entry of list.getEntries()) {\n if (entry.name.includes('micro-app')) {\n this.recordLoadTime(entry);\n }\n }\n });\n \n loadObserver.observe({ entryTypes: ['navigation', 'resource'] });\n \n // 监控布局偏移\n const clsObserver = new PerformanceObserver((list) => {\n for (const entry of list.getEntries()) {\n if (!entry.hadRecentInput) {\n this.recordLayoutShift(entry);\n }\n }\n });\n \n clsObserver.observe({ entryTypes: ['layout-shift'] });\n }\n }\n \n recordLoadTime(entry) {\n const appName = this.extractAppName(entry.name);\n this.metrics.set(`${appName}_load_time`, entry.loadEnd - entry.loadStart);\n }\n \n recordLayoutShift(entry) {\n const currentCLS = this.metrics.get('cumulative_layout_shift') || 0;\n this.metrics.set('cumulative_layout_shift', currentCLS + entry.value);\n }\n \n getMetrics() {\n return Object.fromEntries(this.metrics);\n }\n}\n```\n\n#### 自定义计时 API\n\n```javascript\n// 微应用生命周期的自定义计时\nclass MicroAppTiming {\n static mark(name) {\n performance.mark(name);\n }\n \n static measure(name, startMark, endMark) {\n performance.measure(name, startMark, endMark);\n \n // 发送到分析服务\n const measure = performance.getEntriesByName(name)[0];\n this.sendToAnalytics({\n metric: name,\n duration: measure.duration,\n timestamp: Date.now()\n });\n }\n \n static sendToAnalytics(data) {\n // 发送到你的分析服务\n fetch('/api/analytics/performance', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify(data)\n });\n }\n}\n\n// 微应用生命周期中的使用\nconst lifeCycles = {\n async beforeLoad(app) {\n MicroAppTiming.mark(`${app.name}_load_start`);\n },\n \n async afterMount(app) {\n MicroAppTiming.mark(`${app.name}_mount_end`);\n MicroAppTiming.measure(\n `${app.name}_total_time`,\n `${app.name}_load_start`,\n `${app.name}_mount_end`\n );\n }\n};\n```\n\n### 性能分析\n\n#### 用户体验指标\n\n```javascript\n// 跟踪微应用的用户体验指标\nclass UXMetrics {\n constructor() {\n this.metrics = {};\n this.initTracking();\n }\n \n initTracking() {\n // 微应用的可交互时间\n this.trackTimeToInteractive();\n \n // 用户参与度指标\n this.trackUserEngagement();\n \n // 错误率\n this.trackErrorRates();\n }\n \n trackTimeToInteractive() {\n const observer = new PerformanceObserver((list) => {\n for (const entry of list.getEntries()) {\n if (entry.entryType === 'measure' && entry.name.includes('tti')) {\n this.metrics.timeToInteractive = entry.duration;\n }\n }\n });\n \n observer.observe({ entryTypes: ['measure'] });\n }\n \n trackUserEngagement() {\n let interactions = 0;\n \n ['click', 'scroll', 'keydown'].forEach(event => {\n document.addEventListener(event, () => {\n interactions++;\n this.metrics.interactions = interactions;\n });\n });\n }\n \n trackErrorRates() {\n window.addEventListener('error', (event) => {\n const appName = this.getAppFromError(event);\n this.metrics.errors = this.metrics.errors || {};\n this.metrics.errors[appName] = (this.metrics.errors[appName] || 0) + 1;\n });\n }\n}\n```\n\n## 🎨 UI/UX 性能\n\n### 加载状态\n\n#### 骨架屏加载\n\n```jsx\n// 微应用加载的 React 骨架屏组件\nimport React from 'react';\n\nconst MicroAppSkeleton = ({ appName }) => {\n return (\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n );\n};\n\n// 微应用加载使用示例\nfunction MicroAppContainer({ appName, entry }) {\n const [loading, setLoading] = useState(true);\n const [app, setApp] = useState(null);\n \n useEffect(() => {\n loadMicroApp({\n name: appName,\n entry,\n container: '#micro-app-container'\n }).then(() => {\n setLoading(false);\n });\n }, [appName, entry]);\n \n if (loading) {\n return ;\n }\n \n return
;\n}\n```\n\n#### 渐进式增强\n\n```javascript\n// 微应用的渐进式增强\nclass ProgressiveLoader {\n constructor(container, config) {\n this.container = container;\n this.config = config;\n this.loadingStates = ['initial', 'skeleton', 'partial', 'complete'];\n this.currentState = 'initial';\n }\n \n async load() {\n // 显示初始加载状态\n this.setState('skeleton');\n this.renderSkeleton();\n \n try {\n // 首先加载关键 CSS\n await this.loadCriticalCSS();\n \n // 显示部分内容\n this.setState('partial');\n await this.loadCriticalJS();\n \n // 加载剩余资源\n await this.loadRemainingAssets();\n \n // 完成加载\n this.setState('complete');\n this.mountApp();\n \n } catch (error) {\n this.handleLoadError(error);\n }\n }\n \n renderSkeleton() {\n this.container.innerHTML = this.config.skeletonHTML;\n }\n \n async loadCriticalCSS() {\n const link = document.createElement('link');\n link.rel = 'stylesheet';\n link.href = `${this.config.entry}/critical.css`;\n \n return new Promise((resolve, reject) => {\n link.onload = resolve;\n link.onerror = reject;\n document.head.appendChild(link);\n });\n }\n}\n```\n\n### 动画性能\n\n#### 硬件加速\n\n```css\n/* 优化微应用过渡动画 */\n.micro-app-transition {\n /* 使用 transform 而不是改变布局属性 */\n transform: translateX(0);\n transition: transform 0.3s ease-out;\n \n /* 启用硬件加速 */\n will-change: transform;\n \n /* 使用 GPU 合成 */\n transform: translateZ(0);\n}\n\n.micro-app-enter {\n transform: translateX(100%);\n}\n\n.micro-app-enter-active {\n transform: translateX(0);\n}\n\n.micro-app-exit {\n transform: translateX(0);\n}\n\n.micro-app-exit-active {\n transform: translateX(-100%);\n}\n```\n\n#### 使用 Intersection Observer 进行动画\n\n```javascript\n// 使用 Intersection Observer 高效触发动画\nclass AnimationManager {\n constructor() {\n this.observer = new IntersectionObserver(\n this.handleIntersection.bind(this),\n { threshold: 0.1 }\n );\n }\n \n observe(element) {\n this.observer.observe(element);\n }\n \n handleIntersection(entries) {\n entries.forEach(entry => {\n if (entry.isIntersecting) {\n this.triggerAnimation(entry.target);\n this.observer.unobserve(entry.target);\n }\n });\n }\n \n triggerAnimation(element) {\n // 使用 CSS 类进行硬件加速动画\n element.classList.add('animate-in');\n \n // 或使用 Web Animations API 进行复杂动画\n element.animate([\n { opacity: 0, transform: 'translateY(20px)' },\n { opacity: 1, transform: 'translateY(0)' }\n ], {\n duration: 300,\n easing: 'ease-out'\n });\n }\n}\n```\n\n## 📱 移动端性能\n\n### 移动端特定优化\n\n#### 触摸事件优化\n\n```javascript\n// 优化移动端微应用的触摸事件\nclass TouchOptimizer {\n constructor() {\n this.setupPassiveListeners();\n this.optimizeTouchHandling();\n }\n \n setupPassiveListeners() {\n // 使用被动监听器提高滚动性能\n document.addEventListener('touchstart', this.handleTouchStart, { passive: true });\n document.addEventListener('touchmove', this.handleTouchMove, { passive: true });\n }\n \n optimizeTouchHandling() {\n // 防抖触摸事件\n let touchTimeout;\n \n document.addEventListener('touchend', () => {\n clearTimeout(touchTimeout);\n touchTimeout = setTimeout(() => {\n // 延迟处理触摸结束以防止意外双击\n }, 300);\n });\n }\n \n handleTouchStart(event) {\n // 触摸开始时的最小处理\n }\n \n handleTouchMove(event) {\n // 使用 requestAnimationFrame 进行平滑滚动\n requestAnimationFrame(() => {\n // 处理触摸移动\n });\n }\n}\n```\n\n#### 视口管理\n\n```javascript\n// 为不同微应用优化视口\nclass ViewportManager {\n constructor() {\n this.defaultViewport = 'width=device-width, initial-scale=1.0';\n this.viewportMeta = document.querySelector('meta[name=\"viewport\"]');\n }\n \n setViewportForApp(appName) {\n const appViewports = {\n 'mobile-first-app': 'width=device-width, initial-scale=1.0, user-scalable=no',\n 'desktop-app': 'width=1024, initial-scale=0.5',\n 'responsive-app': 'width=device-width, initial-scale=1.0'\n };\n \n const viewport = appViewports[appName] || this.defaultViewport;\n this.viewportMeta.setAttribute('content', viewport);\n }\n \n resetViewport() {\n this.viewportMeta.setAttribute('content', this.defaultViewport);\n }\n}\n```\n\n## 🔧 开发环境 vs 生产环境优化\n\n### 环境特定配置\n\n#### 开发环境优化\n\n```javascript\n// 微应用的 webpack.config.dev.js\nmodule.exports = {\n mode: 'development',\n \n optimization: {\n // 禁用压缩以加快构建速度\n minimize: false,\n \n // 分割块以便更好地调试\n splitChunks: {\n chunks: 'all',\n cacheGroups: {\n vendor: {\n test: /[\\\\/]node_modules[\\\\/]/,\n name: 'vendors',\n chunks: 'all'\n }\n }\n }\n },\n \n devServer: {\n // 启用热重载\n hot: true,\n \n // 为开发优化\n liveReload: true,\n \n // 微应用通信的 CORS\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n};\n```\n\n#### 生产环境优化\n\n```javascript\n// 微应用的 webpack.config.prod.js\nconst CompressionPlugin = require('compression-webpack-plugin');\nconst { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer');\n\nmodule.exports = {\n mode: 'production',\n \n optimization: {\n // 启用所有优化\n minimize: true,\n sideEffects: false,\n \n // 高级块分割\n splitChunks: {\n chunks: 'all',\n maxSize: 244000,\n cacheGroups: {\n vendor: {\n test: /[\\\\/]node_modules[\\\\/]/,\n name: 'vendors',\n chunks: 'all',\n priority: 10\n },\n common: {\n name: 'common',\n minChunks: 2,\n chunks: 'all',\n priority: 5\n }\n }\n }\n },\n \n plugins: [\n // Gzip 压缩\n new CompressionPlugin({\n algorithm: 'gzip',\n test: /\\.(js|css|html|svg)$/,\n threshold: 8192,\n minRatio: 0.8\n }),\n \n // 包分析（可选）\n new BundleAnalyzerPlugin({\n analyzerMode: 'static',\n openAnalyzer: false\n })\n ]\n};\n```\n\n## 🎯 性能最佳实践总结\n\n### ✅ 应该做的\n\n1. **为关键微应用实施预取**\n2. **在微应用内使用代码分割**\n3. **在多个级别利用缓存**\n4. **持续监控性能**\n5. **优化移动端体验**\n6. **对非关键功能使用懒加载**\n7. **在卸载钩子中实施适当清理**\n8. **高效共享依赖**\n9. **使用 Service Worker 进行缓存**\n10. **使用硬件加速优化动画**\n\n### ❌ 不应该做的\n\n1. **不要一次加载所有微应用**\n2. **不要忽略包大小**\n3. **不要重复大型依赖**\n4. **不要忘记内存清理**\n5. **不要阻塞主线程**\n6. **不要忽略移动端性能**\n7. **不要在慢速连接上过度预取**\n8. **不要使用同步操作**\n9. **不要忽略错误边界**\n10. **不要跳过性能监控**\n\n### 📊 性能检查清单\n\n```javascript\n// 微应用性能审计检查清单\nconst performanceChecklist = {\n loading: {\n prefetchStrategy: '✓ 已实施智能预取',\n bundleSize: '✓ 包大小小于250KB gzipped',\n codesplitting: '✓ 关键路径已分离',\n caching: '✓ 启用积极缓存'\n },\n \n runtime: {\n memoryLeaks: '✓ 已实施清理',\n animationPerf: '✓ 使用硬件加速',\n eventOptimization: '✓ 使用被动监听器',\n lazyLoading: '✓ 非关键功能懒加载'\n },\n \n monitoring: {\n coreWebVitals: '✓ 监控 LCP、FID、CLS',\n customMetrics: '✓ 跟踪应用特定指标',\n errorTracking: '✓ 记录性能错误',\n analytics: '✓ 测量用户体验'\n }\n};\n```\n\n## 🔗 相关文档\n\n- [样式隔离](/cookbook/style-isolation) - CSS 性能和隔离\n- [错误处理](/cookbook/error-handling) - 错误的性能影响\n- [配置](/api/configuration) - 性能相关配置\n- [调试](/cookbook/debugging) - 性能调试技术 " }, { "path": "docs/zh-CN/cookbook/style-isolation.md", "content": "# 样式隔离\n\n样式隔离是微前端架构中最关键的方面之一。当多个应用在同一浏览器上下文中运行时，CSS 冲突可能导致视觉不一致和布局错误。本指南涵盖了在 qiankun 应用中实现有效样式隔离的各种策略。\n\n## 🎯 理解问题\n\n### 微前端中的 CSS 冲突\n\n当多个微应用加载到同一页面时，它们共享相同的全局 CSS 命名空间。这可能导致：\n\n- **样式覆盖**：后加载的应用覆盖早期样式\n- **选择器冲突**：相同的类名造成意外样式\n- **全局污染**：微应用影响主应用样式\n- **布局破坏**：由于样式冲突导致的意外布局变化\n\n### CSS 冲突示例\n\n```css\n/* 主应用 */\n.button {\n background: blue;\n padding: 10px;\n}\n\n/* 微应用 */\n.button {\n background: red; /* 这将覆盖主应用样式！ */\n border: none;\n}\n```\n\n## 🛡️ qiankun 的内置样式隔离\n\nqiankun 提供了几种内置的样式隔离机制，您可以通过配置启用。\n\n### 严格样式隔离\n\n使用 Shadow DOM 的最强大隔离方法：\n\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n sandbox: {\n strictStyleIsolation: true\n }\n});\n```\n\n**工作原理：**\n- 为每个微应用创建 Shadow DOM\n- 完全隔离应用之间的样式\n- 防止任何样式泄漏\n\n**优点：**\n- 完全样式隔离\n- 不可能发生 CSS 冲突\n- 易于实现\n\n**缺点：**\n- 一些第三方库可能无法正常工作\n- 调试可能更复杂\n- 大型应用的性能开销\n\n### 实验性样式隔离\n\n使用 CSS 作用域的侵入性较小的方法：\n\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n sandbox: {\n experimentalStyleIsolation: true\n }\n});\n```\n\n**工作原理：**\n- 为 CSS 选择器添加唯一前缀\n- 将样式作用域限定为微应用容器\n- 保持 DOM 结构\n\n**优点：**\n- 更好的第三方库兼容性\n- 更容易调试\n- 较少的性能开销\n\n**缺点：**\n- 不如严格隔离强大\n- 一些边缘情况可能仍会导致冲突\n\n## 🎨 CSS-in-JS 解决方案\n\nCSS-in-JS 库通过生成唯一的类名提供天然的样式隔离。\n\n### Styled Components\n\n```jsx\n// 使用 Styled Components 的微应用\nimport styled from 'styled-components';\n\nconst Button = styled.button`\n background: ${props => props.primary ? 'blue' : 'grey'};\n padding: 10px 20px;\n border: none;\n border-radius: 4px;\n \n &:hover {\n opacity: 0.8;\n }\n`;\n\nfunction MyComponent() {\n return (\n
\n \n \n
\n );\n}\n```\n\n### Emotion\n\n```jsx\n/** @jsxImportSource @emotion/react */\nimport { css } from '@emotion/react';\n\nconst buttonStyle = css`\n background: blue;\n color: white;\n padding: 10px 20px;\n border: none;\n border-radius: 4px;\n \n &:hover {\n background: darkblue;\n }\n`;\n\nfunction MyComponent() {\n return ;\n}\n```\n\n### 动态导入的 CSS 模块\n\n```css\n/* Button.module.css */\n.button {\n background: blue;\n color: white;\n padding: 10px 20px;\n border: none;\n border-radius: 4px;\n}\n\n.button:hover {\n background: darkblue;\n}\n```\n\n```jsx\n// Button.jsx\nimport styles from './Button.module.css';\n\nfunction Button({ children, ...props }) {\n return (\n \n );\n}\n```\n\n## 🏗️ CSS 作用域策略\n\n### BEM 方法论\n\n使用 Block、Element、Modifier 命名约定避免冲突：\n\n```css\n/* 主应用 */\n.main-app__button {\n background: blue;\n}\n\n.main-app__button--primary {\n background: darkblue;\n}\n\n/* 微应用 */\n.micro-app__button {\n background: red;\n}\n\n.micro-app__button--large {\n padding: 15px 30px;\n}\n```\n\n### 命名空间前缀\n\n为所有 CSS 类添加唯一前缀：\n\n```css\n/* 用户管理微应用 */\n.user-mgmt-container { }\n.user-mgmt-header { }\n.user-mgmt-button { }\n\n/* 产品目录微应用 */\n.product-cat-container { }\n.product-cat-header { }\n.product-cat-button { }\n```\n\n### CSS 自定义属性（变量）\n\n使用 CSS 变量实现一致的主题，避免冲突：\n\n```css\n/* 主应用 - 定义主题变量 */\n:root {\n --primary-color: #007bff;\n --secondary-color: #6c757d;\n --success-color: #28a745;\n --danger-color: #dc3545;\n}\n\n/* 微应用 - 使用主题变量 */\n.micro-app-button {\n background: var(--primary-color);\n color: white;\n}\n```\n\n## 🎭 运行时样式管理\n\n### 动态 CSS 加载\n\n在微应用挂载时动态加载 CSS：\n\n```javascript\n// 动态 CSS 加载的生命周期钩子\nconst lifeCycles = {\n async beforeMount(app) {\n // 加载微应用特定的 CSS\n const link = document.createElement('link');\n link.rel = 'stylesheet';\n link.href = `${app.entry}/static/css/main.css`;\n link.id = `${app.name}-styles`;\n document.head.appendChild(link);\n },\n \n async afterUnmount(app) {\n // 移除微应用 CSS\n const link = document.getElementById(`${app.name}-styles`);\n if (link) {\n document.head.removeChild(link);\n }\n }\n};\n\nregisterMicroApps([\n {\n name: 'micro-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/micro-app'\n }\n], lifeCycles);\n```\n\n### 使用 PostCSS 进行 CSS 作用域\n\n使用 PostCSS 插件自动为 CSS 添加作用域：\n\n```javascript\n// postcss.config.js\nmodule.exports = {\n plugins: [\n require('postcss-prefixwrap')('.micro-app-container')\n ]\n};\n```\n\n**输入 CSS：**\n```css\n.button {\n background: blue;\n}\n```\n\n**输出 CSS：**\n```css\n.micro-app-container .button {\n background: blue;\n}\n```\n\n## 🔧 框架特定解决方案\n\n### React 应用\n\n#### 在 Create React App 中使用 CSS 模块\n\n```javascript\n// Button.module.css\n.button {\n background: blue;\n color: white;\n}\n\n// Button.jsx\nimport styles from './Button.module.css';\n\nfunction Button({ children }) {\n return ;\n}\n```\n\n#### 自定义 CSS 前缀 Hook\n\n```javascript\nimport { useMemo } from 'react';\n\nfunction useCSSPrefix(prefix) {\n return useMemo(() => {\n return (className) => `${prefix}-${className}`;\n }, [prefix]);\n}\n\n// 用法\nfunction MyComponent() {\n const cx = useCSSPrefix('user-mgmt');\n \n return (\n
\n \n
\n );\n}\n```\n\n### Vue 应用\n\n#### 作用域样式\n\n```vue\n\n\n\n```\n\n#### Vue 中的 CSS 模块\n\n```vue\n\n\n\n```\n\n### Angular 应用\n\n#### ViewEncapsulation\n\n```typescript\nimport { Component, ViewEncapsulation } from '@angular/core';\n\n@Component({\n selector: 'app-my-component',\n template: `\n
\n \n
\n `,\n styles: [`\n .component {\n padding: 20px;\n }\n .button {\n background: blue;\n color: white;\n }\n `],\n encapsulation: ViewEncapsulation.Emulated // 默认\n})\nexport class MyComponent { }\n```\n\n## 🎪 组件库策略\n\n### 设计系统方法\n\n创建所有微应用都使用的共享设计系统：\n\n```javascript\n// shared-design-system/Button.js\nexport const Button = ({ variant = 'primary', size = 'medium', children, ...props }) => {\n const baseClasses = 'btn';\n const variantClasses = {\n primary: 'btn-primary',\n secondary: 'btn-secondary'\n };\n const sizeClasses = {\n small: 'btn-sm',\n medium: 'btn-md',\n large: 'btn-lg'\n };\n \n const className = [\n baseClasses,\n variantClasses[variant],\n sizeClasses[size]\n ].join(' ');\n \n return ;\n};\n```\n\n### 用于主题化的 CSS 自定义属性\n\n```css\n/* 设计系统 CSS */\n:root {\n --btn-primary-bg: #007bff;\n --btn-primary-color: white;\n --btn-secondary-bg: #6c757d;\n --btn-secondary-color: white;\n --btn-padding-sm: 8px 12px;\n --btn-padding-md: 10px 16px;\n --btn-padding-lg: 12px 20px;\n}\n\n.btn {\n border: none;\n border-radius: 4px;\n cursor: pointer;\n font-family: inherit;\n}\n\n.btn-primary {\n background: var(--btn-primary-bg);\n color: var(--btn-primary-color);\n}\n\n.btn-secondary {\n background: var(--btn-secondary-bg);\n color: var(--btn-secondary-color);\n}\n\n.btn-sm { padding: var(--btn-padding-sm); }\n.btn-md { padding: var(--btn-padding-md); }\n.btn-lg { padding: var(--btn-padding-lg); }\n```\n\n## 🚫 第三方库处理\n\n### 隔离第三方样式\n\n当使用注入全局样式的第三方库时：\n\n```javascript\n// 在隔离环境中加载第三方 CSS\nconst loadLibraryStyles = (libraryName, cssUrl) => {\n return new Promise((resolve) => {\n const iframe = document.createElement('iframe');\n iframe.style.display = 'none';\n document.body.appendChild(iframe);\n \n const iframeDoc = iframe.contentDocument;\n const link = iframeDoc.createElement('link');\n link.rel = 'stylesheet';\n link.href = cssUrl;\n link.onload = () => {\n // 提取并为 CSS 添加作用域\n const styles = Array.from(iframeDoc.styleSheets[0].cssRules)\n .map(rule => rule.cssText)\n .join('\\n');\n \n const scopedStyles = scopeCSS(styles, `.${libraryName}-container`);\n \n const style = document.createElement('style');\n style.textContent = scopedStyles;\n style.id = `${libraryName}-scoped-styles`;\n document.head.appendChild(style);\n \n document.body.removeChild(iframe);\n resolve();\n };\n iframeDoc.head.appendChild(link);\n });\n};\n```\n\n### 第三方集成的 CSS-in-JS\n\n```javascript\nimport { createGlobalStyle } from 'styled-components';\n\n// 将第三方样式作用域限定为特定容器\nconst AntdStyles = createGlobalStyle`\n .micro-app-container {\n .ant-btn {\n /* 专门为此微应用覆盖 Ant Design 按钮样式 */\n border-radius: 8px;\n }\n \n .ant-table {\n /* 覆盖 Ant Design 表格样式 */\n border: 1px solid #f0f0f0;\n }\n }\n`;\n\nfunction MicroApp() {\n return (\n
\n \n {/* 您的微应用内容 */}\n
\n );\n}\n```\n\n## 🔍 调试样式冲突\n\n### 开发工具\n\n#### 样式检查脚本\n\n```javascript\n// 添加到浏览器控制台进行调试\nconst findStyleConflicts = (selector) => {\n const elements = document.querySelectorAll(selector);\n \n elements.forEach((el, index) => {\n const styles = window.getComputedStyle(el);\n const rules = [];\n \n for (let i = 0; i < document.styleSheets.length; i++) {\n try {\n const sheet = document.styleSheets[i];\n const cssRules = sheet.cssRules || sheet.rules;\n \n for (let j = 0; j < cssRules.length; j++) {\n if (el.matches(cssRules[j].selectorText)) {\n rules.push({\n selector: cssRules[j].selectorText,\n rule: cssRules[j].cssText,\n sheet: sheet.href || 'inline'\n });\n }\n }\n } catch (e) {\n // 跨域样式表\n }\n }\n \n console.log(`元素 ${index + 1}:`, el);\n console.log('应用的样式:', rules);\n });\n};\n\n// 用法: findStyleConflicts('.button');\n```\n\n#### 样式来源跟踪器\n\n```javascript\n// 跟踪哪个微应用加载了哪些样式\nconst styleTracker = {\n styles: new Map(),\n \n track(appName, styleElement) {\n if (!this.styles.has(appName)) {\n this.styles.set(appName, []);\n }\n this.styles.get(appName).push(styleElement);\n },\n \n getByApp(appName) {\n return this.styles.get(appName) || [];\n },\n \n getConflicts() {\n const allSelectors = new Map();\n \n this.styles.forEach((styles, appName) => {\n styles.forEach(style => {\n // 解析 CSS 并检查选择器冲突\n // 实现取决于 CSS 解析器\n });\n });\n \n return allSelectors;\n }\n};\n```\n\n### 运行时冲突检测\n\n```javascript\n// 在运行时检测样式冲突\nconst detectStyleConflicts = () => {\n const observer = new MutationObserver((mutations) => {\n mutations.forEach((mutation) => {\n if (mutation.type === 'childList') {\n mutation.addedNodes.forEach((node) => {\n if (node.tagName === 'STYLE' || node.tagName === 'LINK') {\n checkForConflicts(node);\n }\n });\n }\n });\n });\n \n observer.observe(document.head, { childList: true });\n};\n\nconst checkForConflicts = (styleNode) => {\n // 检查 CSS 选择器冲突的实现\n console.warn('添加了新的样式节点:', styleNode);\n};\n```\n\n## 📊 性能考虑\n\n### CSS 加载性能\n\n```javascript\n// 优化微应用的 CSS 加载\nconst optimizedCSSLoader = {\n cache: new Map(),\n \n async loadCSS(url, appName) {\n if (this.cache.has(url)) {\n return this.cache.get(url);\n }\n \n const response = await fetch(url);\n const css = await response.text();\n const optimizedCSS = this.optimizeCSS(css, appName);\n \n this.cache.set(url, optimizedCSS);\n return optimizedCSS;\n },\n \n optimizeCSS(css, appName) {\n // 移除未使用的选择器\n // 添加应用特定前缀\n // 必要时压缩\n return css.replace(/(\\.[a-zA-Z-_]+)/g, `.${appName}-$1`);\n }\n};\n```\n\n### 样式的包分割\n\n```javascript\n// webpack.config.js - 按微应用分割 CSS\nmodule.exports = {\n optimization: {\n splitChunks: {\n cacheGroups: {\n styles: {\n name: 'styles',\n test: /\\.css$/,\n chunks: 'all',\n enforce: true\n }\n }\n }\n }\n};\n```\n\n## 🎯 最佳实践总结\n\n### ✅ 应该做的\n\n1. **尽可能使用 qiankun 的内置隔离**\n2. **实施一致的命名约定**（BEM、命名空间）\n3. **使用 CSS-in-JS** 进行自动隔离\n4. **创建共享设计系统** 以保持一致性\n5. **在开发中测试样式隔离**\n6. **在生产中监控冲突**\n7. **为您的团队记录样式指南**\n\n### ❌ 不应该做的\n\n1. **不要在微应用中依赖全局 CSS**\n2. **不要使用过于通用的类名**（.button、.container）\n3. **不要忘记在卸载时清理样式**\n4. **不要忽略第三方库样式**\n5. **不要跳过样式隔离测试**\n6. **除非绝对必要，不要使用 !important**\n\n### 🎪 真实世界示例\n\n这是一个良好隔离的微应用的完整示例：\n\n```jsx\n// MicroApp.jsx\nimport React from 'react';\nimport styled, { createGlobalStyle } from 'styled-components';\n\n// 作用域限定为此微应用的全局样式\nconst GlobalStyles = createGlobalStyle`\n .user-management-app {\n font-family: 'Inter', sans-serif;\n \n * {\n box-sizing: border-box;\n }\n }\n`;\n\n// 带隔离的样式组件\nconst Container = styled.div`\n padding: 20px;\n background: #f8f9fa;\n min-height: 100vh;\n`;\n\nconst Header = styled.h1`\n color: #343a40;\n margin-bottom: 20px;\n`;\n\nconst Button = styled.button`\n background: ${props => props.primary ? '#007bff' : '#6c757d'};\n color: white;\n border: none;\n padding: 10px 20px;\n border-radius: 4px;\n cursor: pointer;\n \n &:hover {\n opacity: 0.9;\n }\n`;\n\nfunction UserManagementApp() {\n return (\n
\n \n \n
用户管理
\n \n \n \n
\n );\n}\n\nexport default UserManagementApp;\n```\n\n## 🔗 相关文档\n\n- [性能优化](/cookbook/performance) - 优化加载和运行时性能\n- [错误处理](/cookbook/error-handling) - 处理 CSS 相关错误\n- [配置](/api/configuration) - 配置样式隔离选项\n- [调试](/cookbook/debugging) - 调试样式冲突 " }, { "path": "docs/zh-CN/ecosystem/create-qiankun.md", "content": "# Create Qiankun\n\n`create-qiankun` 是一个专为 qiankun 微前端框架设计的 CLI 脚手架工具。它帮助开发者快速构建示例项目，高效开始微前端开发。\n\n## 🚀 快速开始\n\n### 使用 npm\n\n```bash\nnpx create-qiankun@latest\n```\n\n### 使用 yarn\n\n```bash\nyarn create qiankun@latest\n```\n\n### 使用 pnpm\n\n```bash\npnpm dlx create-qiankun@latest\n```\n\n## 🎯 特性\n\n- **多种项目类型**：选择仅主应用、仅微应用或完整设置\n- **框架支持**：React 18、Vue 3、Vue 2 和 Umi 4 模板\n- **路由模式**：支持 hash 和 history 路由模式\n- **包管理器选项**：npm、yarn、pnpm 或 pnpm workspace\n- **自动配置**：自动端口冲突检测和启动脚本注入\n- **Monorepo 支持**：内置 pnpm workspace 设置管理多个应用\n\n## 📋 要求\n\n- **Node.js**：v18 或更高版本（推荐：使用 [fnm](https://github.com/Schniz/fnm) 进行版本管理）\n- **包管理器**：npm、yarn 或 pnpm\n\n## 🎮 交互式设置\n\n运行 `create-qiankun` 时，您将通过交互式设置过程：\n\n### 步骤 1：项目名称\n\n```bash\n? Project name: › my-qiankun-project\n```\n\n### 步骤 2：项目类型\n\n```bash\n? Choose a way to create › \n❯ Create main application and sub applications\n Just create main application \n Just create sub applications\n```\n\n**选项：**\n- **Create main application and sub applications**：完整设置，包含主应用和多个微应用\n- **Just create main application**：仅创建主（shell）应用\n- **Just create sub applications**：仅创建微应用\n\n### 步骤 3：主应用框架（如适用）\n\n```bash\n? Choose a framework for your main application › \n❯ React18+Webpack\n Vue3+Webpack\n React18+umi4\n```\n\n### 步骤 4：路由模式（如适用）\n\n```bash\n? Choose a route pattern for your main application › \n❯ hash\n history\n```\n\n### 步骤 5：子应用框架（如适用）\n\n```bash\n? Choose a framework for your sub application › \nSpace to select. Return to submit.\n\n❯◯ React18+Webpack\n ◯ Vue3+Webpack \n ◯ Vue2+Webpack\n ◯ React18+umi4\n```\n\n### 步骤 6：包管理器\n\n```bash\n? Which package manager do you want to use? › \n❯ npm\n yarn\n pnpm\n pnpm with workspace\n```\n\n## 📦 可用模板\n\n### 主应用模板\n\n| 模板 | 描述 | 特性 |\n|----------|-------------|----------|\n| **React18+Webpack** | React 18 with Webpack 5 | 现代 React、TypeScript 支持、热重载 |\n| **Vue3+Webpack** | Vue 3 with Vue CLI | Composition API、TypeScript、Element Plus |\n| **React18+umi4** | Umi 4 框架 | 内置 qiankun 支持、Ant Design Pro |\n\n### 子应用模板\n\n| 模板 | 描述 | 状态 | 备注 |\n|----------|-------------|--------|-------|\n| **React18+Webpack** | React 18 微应用 | ✅ 稳定 | 生产就绪 |\n| **Vue3+Webpack** | Vue 3 微应用 | ✅ 稳定 | 生产就绪 |\n| **Vue2+Webpack** | Vue 2 微应用 | ⚠️ 有限 | pnpm workspace 存在问题 |\n| **React18+umi4** | Umi 4 微应用 | ✅ 稳定 | 内置微应用支持 |\n| **Vite+Vue3** | Vue 3 with Vite | 🚧 开发中 | 开发中 |\n| **Vite+React18** | React 18 with Vite | 🚧 开发中 | 开发中 |\n\n## 🏗️ 项目结构\n\n### 单一项目结构\n\n```\nmy-qiankun-project/\n├── main-app/ # 主应用\n│ ├── src/\n│ ├── package.json\n│ └── webpack.config.js\n├── react18-sub/ # React 微应用\n│ ├── src/\n│ ├── package.json\n│ └── webpack.config.js\n├── vue3-sub/ # Vue 微应用\n│ ├── src/\n│ ├── package.json\n│ └── vue.config.js\n└── package.json\n```\n\n### Pnpm Workspace 结构\n\n```\nmy-qiankun-project/\n├── packages/\n│ ├── main-app/ # 主应用\n│ ├── react18-sub/ # React 微应用\n│ └── vue3-sub/ # Vue 微应用\n├── package.json # Workspace 配置\n├── pnpm-workspace.yaml # Workspace 定义\n└── scripts/\n └── checkPnpm.js # 包管理器验证\n```\n\n## 🔧 生成的配置\n\n### 主应用配置\n\n主应用自动配置包含：\n\n```typescript\n// 主应用微应用注册\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'react18-sub',\n entry: '//localhost:8080',\n container: '#subapp-viewport',\n activeRule: '/react18-sub',\n },\n {\n name: 'vue3-sub', \n entry: '//localhost:8081',\n container: '#subapp-viewport',\n activeRule: '/vue3-sub',\n }\n]);\n\nstart();\n```\n\n### 微应用配置\n\n每个微应用包含：\n\n**React 微应用：**\n```javascript\n// webpack.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunWebpackPlugin()\n ]\n};\n```\n\n**Vue 微应用：**\n```javascript\n// vue.config.js\nconst { defineConfig } = require('@vue/cli-service');\nconst { QiankunWebpackPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = defineConfig({\n configureWebpack: {\n plugins: [\n new QiankunWebpackPlugin()\n ]\n }\n});\n```\n\n### 端口配置\n\n自动端口分配防止冲突：\n\n```json\n{\n \"scripts\": {\n \"dev\": \"PORT=8080 react-scripts start\",\n \"check-port\": \"node scripts/checkPort.js\"\n }\n}\n```\n\n## 🎨 自定义选项\n\n### 环境特定配置\n\n```javascript\n// config/development.js\nmodule.exports = {\n microApps: [\n {\n name: 'react-app',\n entry: '//localhost:8080',\n activeRule: '/react-app'\n }\n ]\n};\n\n// config/production.js\nmodule.exports = {\n microApps: [\n {\n name: 'react-app', \n entry: '//app.example.com',\n activeRule: '/react-app'\n }\n ]\n};\n```\n\n### 自定义路由\n\n```typescript\n// Hash 路由（默认）\nconst router = createRouter({\n history: createWebHashHistory(),\n routes: [...]\n});\n\n// History 路由 \nconst router = createRouter({\n history: createWebHistory(),\n routes: [...]\n});\n```\n\n## 🚀 开发工作流\n\n### 单一包管理器\n\n```bash\n# 启动主应用\ncd main-app && npm run dev\n\n# 启动微应用（在单独的终端）\ncd react18-sub && npm run dev \ncd vue3-sub && npm run dev\n```\n\n### Pnpm Workspace\n\n```bash\n# 安装所有依赖\npnpm install\n\n# 同时启动所有应用\npnpm run dev\n\n# 启动特定应用\npnpm --filter main-app run dev\npnpm --filter react18-sub run dev\n```\n\n### 生成的脚本\n\nCLI 自动注入有用的脚本：\n\n```json\n{\n \"scripts\": {\n \"dev\": \"concurrently \\\"npm run dev:main\\\" \\\"npm run dev:subs\\\"\",\n \"dev:main\": \"cd main-app && npm run dev\",\n \"dev:subs\": \"concurrently \\\"cd react18-sub && npm run dev\\\" \\\"cd vue3-sub && npm run dev\\\"\",\n \"build\": \"npm run build:main && npm run build:subs\",\n \"clean\": \"rimraf node_modules **/*/node_modules\"\n }\n}\n```\n\n## 🔧 高级用法\n\n### 命令行参数\n\n通过提供参数跳过交互式提示：\n\n```bash\nnpx create-qiankun my-project CreateMainAndSubApp react18-main hash react18-webpack-sub,vue3-webpack-sub pnpm\n```\n\n**参数顺序：**\n1. 项目名称\n2. 创建类型 (`CreateMainApp` | `CreateSubApp` | `CreateMainAndSubApp`)\n3. 主应用模板（如适用）\n4. 路由模式（如适用） \n5. 子应用模板（逗号分隔，如适用）\n6. 包管理器\n\n### 批量创建\n\n```bash\n# 创建多个项目\nfor project in app1 app2 app3; do\n npx create-qiankun $project CreateMainAndSubApp react18-main history react18-webpack-sub pnpm\ndone\n```\n\n### 自定义模板\n\n您可以通过为项目贡献或分叉仓库来使用自定义模板扩展 CLI。\n\n## 🎯 项目示例\n\n### 完整的 React + Vue 设置\n\n```bash\nnpx create-qiankun my-micro-frontend-app\n# 选择：Create main application and sub applications\n# 主应用：React18+Webpack\n# 路由：history\n# 子应用：React18+Webpack, Vue3+Webpack\n# 包管理器：pnpm with workspace\n```\n\n**结果：**\n- 带路由的主 React 应用\n- React 18 微应用\n- Vue 3 微应用 \n- 自动端口分配（3000、8080、8081）\n- Workspace 配置\n- 开发脚本\n\n### 基于 Umi 的 Monorepo\n\n```bash\nnpx create-qiankun enterprise-app\n# 选择：Create main application and sub applications \n# 主应用：React18+umi4\n# 路由：history\n# 子应用：React18+umi4, Vue3+Webpack\n# 包管理器：pnpm with workspace\n```\n\n**特性：**\n- 内置 qiankun 支持的 Umi 4 主应用\n- Umi 4 微应用\n- Vue 3 微应用\n- Ant Design Pro 组件\n- TypeScript 配置\n\n## 📚 最佳实践\n\n### 1. 使用描述性名称\n\n```bash\n# ✅ 好：描述性项目名称\nnpx create-qiankun e-commerce-platform\nnpx create-qiankun admin-dashboard\n\n# ❌ 坏：通用名称\nnpx create-qiankun app1\nnpx create-qiankun project\n```\n\n### 2. 选择适当的包管理器\n\n```bash\n# 对于简单项目\nnpm / yarn\n\n# 对于多团队的 monorepo\npnpm with workspace\n```\n\n### 3. 规划路由策略\n\n```bash\n# Hash 路由 - 更简单的部署\n# History 路由 - 更好的 SEO，需要服务器配置\n```\n\n### 4. 考虑框架兼容性\n\n- **React + Vue**：适合混合团队\n- **相同框架**：更容易的依赖管理\n- **Umi**：最适合企业应用\n\n## 🐛 故障排除\n\n### 端口冲突\n\nCLI 自动检测和解决端口冲突。如果遇到问题：\n\n```bash\n# 检查运行中的进程\nlsof -i :8080\n\n# 杀死冲突进程\nkill -9 $(lsof -t -i:8080)\n```\n\n### Pnpm Workspace 问题\n\n```bash\n# 清除 node_modules 并重新安装\npnpm run clean\npnpm install\n\n# 检查 workspace 配置\ncat pnpm-workspace.yaml\n```\n\n### 构建错误\n\n```bash\n# 清除构建缓存\nrm -rf dist/ build/ .cache/\n\n# 重新安装依赖\nrm -rf node_modules package-lock.json\nnpm install\n```\n\n### Vue 2 与 Pnpm Workspace\n\n已知限制：Vue 2 模板与 pnpm workspace 存在兼容性问题。使用替代方法：\n\n```bash\n# 使用常规 pnpm 替代\n# 选择：pnpm（不是 pnpm with workspace）\n\n# 或对 Vue 2 项目使用 yarn/npm\n```\n\n## 🔗 生成项目特性\n\n### 自动配置\n\n- 微前端构建的 **Webpack 优化**\n- 跨域请求的 **CORS 处理** \n- 不同环境的 **Public path** 配置\n- 本地开发的 **开发代理** 设置\n\n### 开发体验\n\n- 所有应用中的 **热模块替换**\n- 微应用失败的 **错误边界**\n- 微应用转换期间的 **加载状态**\n- 适用的 **TypeScript 支持**\n\n### 生产就绪\n\n- 微前端部署的 **构建优化**\n- **资源优化** 和代码分割\n- 不同阶段的 **环境配置**\n- **CI/CD 友好** 结构\n\n## 📖 下一步\n\n创建项目后：\n\n1. **探索生成的代码** 以了解结构\n2. **根据需要自定义配置**\n3. **随着项目增长添加更多微应用**\n4. **设置 CI/CD 流水线** 进行自动化部署\n5. **阅读 qiankun 文档** 了解高级特性\n\n## 🔗 相关文档\n\n- [核心 APIs](/zh-CN/api/) - qiankun 核心 APIs\n- [React 绑定](/zh-CN/ecosystem/react) - React UI 绑定\n- [Vue 绑定](/zh-CN/ecosystem/vue) - Vue UI 绑定\n- [Webpack 插件](/zh-CN/ecosystem/webpack-plugin) - 构建工具配置\n\n## 🤝 贡献\n\n想要添加新模板或改进 CLI？查看 [GitHub 仓库](https://github.com/umijs/qiankun) 并为 `packages/create-qiankun` 目录贡献。 " }, { "path": "docs/zh-CN/ecosystem/index.md", "content": "# 生态系统\n\nqiankun 提供了丰富的 UI 绑定和工具生态系统，帮助你高效地构建和维护微前端应用。\n\n## 🧩 UI 绑定\n\nqiankun 为流行框架提供声明式 UI 组件，使在主应用中加载和管理微应用变得更加容易。\n\n### React\n\n**`@qiankunjs/react`** - qiankun 官方 React 绑定\n\n- **特性**：声明式 MicroApp 组件、自动加载状态、错误边界\n- **优势**：类型安全、React hooks 支持、无缝集成\n- **适用场景**：基于 React 的主应用\n\n```bash\nnpm install @qiankunjs/react\n```\n\n[了解更多 React 绑定 →](/zh-CN/ecosystem/react)\n\n### Vue\n\n**`@qiankunjs/vue`** - qiankun 官方 Vue 绑定\n\n- **特性**：Vue 2/3 兼容、组合式 API 支持、基于插槽的自定义\n- **优势**：响应式加载状态、基于模板的方法、TypeScript 支持\n- **适用场景**：基于 Vue 的主应用\n\n```bash\nnpm install @qiankunjs/vue\n```\n\n[了解更多 Vue 绑定 →](/zh-CN/ecosystem/vue)\n\n## 🛠️ 开发工具\n\n### Webpack 插件\n\n**`@qiankunjs/webpack-plugin`** - 微应用的 Webpack 插件\n\n- **特性**：自动公共路径注入、构建优化、开发模式支持\n- **优势**：零配置设置、改善开发体验、生产就绪构建\n- **适用场景**：基于 webpack 的微应用必备\n\n```bash\nnpm install @qiankunjs/webpack-plugin --save-dev\n```\n\n[了解更多 Webpack 插件 →](/zh-CN/ecosystem/webpack-plugin)\n\n### Create Qiankun\n\n**`create-qiankun`** - 脚手架工具用于创建 qiankun 项目\n\n- **特性**：多种模板、主应用+微应用设置、包含最佳实践\n- **优势**：快速项目初始化、生产就绪配置、现代工具\n- **适用场景**：启动新的 qiankun 项目或添加微前端能力\n\n```bash\nnpx create-qiankun my-micro-frontend-app\n```\n\n[了解更多 Create Qiankun →](/zh-CN/ecosystem/create-qiankun)\n\n## 🎯 快速开始对比\n\n### 不使用 UI 绑定（核心 API）\n\n```typescript\nimport { loadMicroApp } from 'qiankun';\n\n// 手动方式\nconst microApp = loadMicroApp({\n name: 'my-app',\n entry: '//localhost:8080',\n container: '#subapp-container'\n});\n\n// 手动生命周期管理\nmicroApp.mountPromise.then(() => {\n setLoading(false);\n}).catch(error => {\n setError(error);\n});\n```\n\n### 使用 React 绑定\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n### 使用 Vue 绑定\n\n```vue\n\n\n\n```\n\n## 🔄 集成流程\n\n```mermaid\ngraph LR\n A[主应用] --> B[UI 绑定]\n B --> C[qiankun 核心]\n C --> D[微应用 1]\n C --> E[微应用 2]\n C --> F[微应用 3]\n \n G[Webpack 插件] --> D\n G --> E\n G --> F\n \n H[Create Qiankun] --> A\n H --> D\n H --> E\n H --> F\n```\n\n## 📋 功能对比\n\n| 功能 | 核心 API | React 绑定 | Vue 绑定 |\n|------|----------|------------|----------|\n| **加载状态** | 手动 | ✅ 自动 | ✅ 自动 |\n| **错误处理** | 手动 | ✅ 错误边界 | ✅ 错误边界 |\n| **自定义加载** | 手动 | ✅ 组件 | ✅ 插槽 |\n| **自定义错误** | 手动 | ✅ 组件 | ✅ 插槽 |\n| **TypeScript** | ✅ 完整 | ✅ 完整 | ✅ 完整 |\n| **框架集成** | 手动 | ✅ Hooks | ✅ 组合式 API |\n\n## 🎨 使用模式\n\n### 1. 简单加载\n\n**React：**\n```tsx\n\n```\n\n**Vue：**\n```vue\n\n```\n\n### 2. 自定义加载和错误处理\n\n**React：**\n```tsx\n loading ? : null}\n errorBoundary={(error) => }\n/>\n```\n\n**Vue：**\n```vue\n\n \n \n\n```\n\n### 3. 属性传递\n\n**React：**\n```tsx\n\n```\n\n**Vue：**\n```vue\n\n```\n\n## 🚀 入门指南\n\n### 步骤 1：选择你的技术栈\n\n1. **React 主应用** → 使用 `@qiankunjs/react`\n2. **Vue 主应用** → 使用 `@qiankunjs/vue`\n3. **其他框架** → 使用核心 qiankun API\n\n### 步骤 2：创建项目脚手架\n\n```bash\n# 创建新项目\nnpx create-qiankun my-app\n\n# 选择模板：\n# - React 主应用 + React 微应用\n# - Vue 主应用 + Vue 微应用\n# - Umi 主应用 + 多个微应用\n# - 自定义配置\n```\n\n### 步骤 3：配置微应用\n\n为每个微应用添加 webpack 插件：\n\n```javascript\n// webpack.config.js\nconst { QiankunWebpackPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunWebpackPlugin()\n ]\n};\n```\n\n### 步骤 4：开始开发\n\n```bash\n# 启动主应用\ncd main-app && npm start\n\n# 启动微应用（在新终端中）\ncd micro-app && npm start\n```\n\n## 🔧 高级配置\n\n### 基于环境的配置\n\n```typescript\n// React 主应用\nconst MicroAppConfig = {\n development: {\n entry: '//localhost:8080',\n autoSetLoading: true,\n autoCaptureError: true,\n },\n production: {\n entry: '//your-domain.com/micro-app',\n autoSetLoading: false, // 自定义加载\n autoCaptureError: true,\n }\n};\n\nconst config = MicroAppConfig[process.env.NODE_ENV];\n\nfunction App() {\n return ;\n}\n```\n\n### 多应用仪表板\n\n```tsx\n// React - 多个微应用\nfunction Dashboard() {\n return (\n
\n \n
\n \n
\n
\n \n
\n
\n );\n}\n```\n\n## 📚 文档链接\n\n- [React 绑定](/zh-CN/ecosystem/react) - 完整 React 集成指南\n- [Vue 绑定](/zh-CN/ecosystem/vue) - 完整 Vue 集成指南\n- [Webpack 插件](/zh-CN/ecosystem/webpack-plugin) - 构建工具配置\n- [Create Qiankun](/zh-CN/ecosystem/create-qiankun) - 项目脚手架\n- [API 参考](/zh-CN/api/) - 核心 qiankun API\n\n## 🤝 社区\n\n- [GitHub 讨论](https://github.com/umijs/qiankun/discussions) - 提问和分享想法\n- [Issues](https://github.com/umijs/qiankun/issues) - 错误报告和功能请求\n- [更新日志](https://github.com/umijs/qiankun/releases) - 最新更新和发布\n\n选择最适合你项目需求的工具，开始构建强大的微前端应用！ " }, { "path": "docs/zh-CN/ecosystem/react.md", "content": "# React 绑定\n\nqiankun 的官方 React 绑定提供了一种声明式的方式来将微应用集成到您的 React 主应用中。`@qiankunjs/react` 包提供了一个强大的 `` 组件，内置加载状态、错误处理和 TypeScript 支持。\n\n## 📦 安装\n\n```bash\nnpm install @qiankunjs/react\n```\n\n**要求：**\n- React ≥ 16.9.0\n- qiankun ≥ 3.0.0\n\n## 🚀 快速开始\n\n### 基本用法\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n
\n

主应用

\n \n
\n );\n}\n\nexport default App;\n```\n\n### 带加载状态\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n### 带错误处理\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n## 🎯 组件 API\n\n### 属性\n\n| 属性 | 类型 | 必需 | 默认值 | 描述 |\n|------|------|------|--------|------|\n| `name` | `string` | ✅ | - | 微应用的唯一名称 |\n| `entry` | `string` | ✅ | - | 微应用的入口 URL |\n| `autoSetLoading` | `boolean` | ❌ | `false` | 自动管理加载状态 |\n| `autoCaptureError` | `boolean` | ❌ | `false` | 自动处理错误 |\n| `loader` | `(loading: boolean) => React.ReactNode` | ❌ | `undefined` | 自定义加载组件 |\n| `errorBoundary` | `(error: any) => React.ReactNode` | ❌ | `undefined` | 自定义错误组件 |\n| `className` | `string` | ❌ | `undefined` | 微应用容器的 CSS 类 |\n| `wrapperClassName` | `string` | ❌ | `undefined` | 包装器的 CSS 类（使用 loader/errorBoundary 时） |\n| `settings` | `AppConfiguration` | ❌ | `{}` | qiankun 配置选项 |\n| `lifeCycles` | `LifeCycles` | ❌ | `undefined` | 生命周期钩子 |\n\n### 额外属性\n\n传递给 `` 的任何额外属性都会转发给微应用作为 props：\n\n```tsx\n\n```\n\n## 🔄 生命周期管理\n\n### 使用 Ref 访问微应用实例\n\n```tsx\nimport React, { useRef, useEffect } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction App() {\n const microAppRef = useRef();\n\n useEffect(() => {\n // 获取微应用状态\n console.log(microAppRef.current?.getStatus());\n }, []);\n\n const handleUnmount = () => {\n microAppRef.current?.unmount();\n };\n\n return (\n
\n \n \n
\n );\n}\n```\n\n### 应用状态\n\n微应用实例提供这些状态值：\n\n- `NOT_LOADED` - 初始状态，尚未加载\n- `LOADING_SOURCE_CODE` - 加载应用资源中\n- `NOT_BOOTSTRAPPED` - 资源已加载，尚未引导\n- `BOOTSTRAPPING` - 运行引导生命周期\n- `NOT_MOUNTED` - 已引导但未挂载\n- `MOUNTING` - 运行挂载生命周期\n- `MOUNTED` - 成功挂载并运行\n- `UPDATING` - 运行更新生命周期\n- `UNMOUNTING` - 运行卸载生命周期\n- `UNLOADING` - 清理资源\n\n## 🎨 自定义\n\n### 自定义加载组件\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport { Spin, Alert } from 'antd';\n\nconst CustomLoader: React.FC<{ loading: boolean }> = ({ loading }) => {\n if (!loading) return null;\n \n return (\n
\n \n

加载微应用中...

\n
\n );\n};\n\nfunction App() {\n return (\n }\n />\n );\n}\n```\n\n### 自定义错误边界\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport { Alert, Button } from 'antd';\n\nconst CustomErrorBoundary: React.FC<{ error: Error }> = ({ error }) => {\n const handleRetry = () => {\n window.location.reload();\n };\n\n return (\n
\n \n 重试\n \n }\n />\n
\n );\n};\n\nfunction App() {\n return (\n }\n />\n );\n}\n```\n\n### 样式设置\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport './MicroApp.css';\n\nfunction App() {\n return (\n \n );\n}\n```\n\n```css\n/* MicroApp.css */\n.micro-app-wrapper {\n border: 1px solid #e8e8e8;\n border-radius: 6px;\n overflow: hidden;\n}\n\n.micro-app-container {\n min-height: 400px;\n background: #fafafa;\n}\n```\n\n## 🔧 高级用法\n\n### 多个微应用\n\n```tsx\nimport React, { useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\nimport { Tabs } from 'antd';\n\nconst { TabPane } = Tabs;\n\nfunction Dashboard() {\n const [activeTab, setActiveTab] = useState('dashboard');\n\n return (\n
\n \n \n \n \n \n \n \n \n \n \n \n
\n );\n}\n```\n\n### 条件加载\n\n```tsx\nimport React, { useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction ConditionalApp() {\n const [showMicroApp, setShowMicroApp] = useState(false);\n const [user, setUser] = useState(null);\n\n // 只有用户认证后才加载微应用\n if (!user) {\n return
请登录以继续
;\n }\n\n return (\n
\n \n \n {showMicroApp && (\n \n )}\n
\n );\n}\n```\n\n### 动态入口 URL\n\n```tsx\nimport React, { useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction DynamicApp() {\n const [environment, setEnvironment] = useState('development');\n \n const entryUrls = {\n development: '//localhost:8080',\n staging: '//staging.example.com',\n production: '//app.example.com'\n };\n\n return (\n
\n \n \n \n
\n );\n}\n```\n\n## 🎮 状态管理\n\n### 使用 Context 共享状态\n\n```tsx\nimport React, { createContext, useContext, useState } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\n// 创建共享状态的 Context\nconst AppContext = createContext();\n\nfunction MainApp() {\n const [sharedState, setSharedState] = useState({\n user: { id: 1, name: 'John' },\n theme: 'dark'\n });\n\n return (\n \n
\n \n \n
\n \n );\n}\n\nfunction MicroAppContainer() {\n const { sharedState } = useContext(AppContext);\n \n return (\n \n );\n}\n```\n\n### 应用间通信\n\n```tsx\nimport React, { useEffect, useRef } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction CommunicatingApps() {\n const microApp1Ref = useRef();\n const microApp2Ref = useRef();\n\n useEffect(() => {\n // 设置通信渠道\n window.appCommunication = {\n sendMessage: (from, to, message) => {\n const event = new CustomEvent('microAppMessage', {\n detail: { from, to, message }\n });\n window.dispatchEvent(event);\n }\n };\n\n // 监听消息\n const handleMessage = (event) => {\n console.log('收到消息:', event.detail);\n };\n\n window.addEventListener('microAppMessage', handleMessage);\n\n return () => {\n window.removeEventListener('microAppMessage', handleMessage);\n delete window.appCommunication;\n };\n }, []);\n\n return (\n
\n
\n \n
\n
\n \n
\n
\n );\n}\n```\n\n## 🔒 TypeScript 支持\n\n### 类型化属性\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\ninterface UserProfileProps {\n userId: string;\n theme: 'light' | 'dark';\n permissions: string[];\n}\n\n// 为额外属性添加类型\nconst UserProfileApp: React.FC = () => {\n const user = getCurrentUser();\n \n return (\n \n );\n};\n```\n\n### 微应用自定义 Hook\n\n```tsx\nimport { useRef, useEffect, useState } from 'react';\nimport type { MicroApp as MicroAppType } from 'qiankun';\n\ninterface UseMicroAppOptions {\n onStatusChange?: (status: string) => void;\n onError?: (error: Error) => void;\n}\n\nexport function useMicroApp(options: UseMicroAppOptions = {}) {\n const microAppRef = useRef();\n const [status, setStatus] = useState('NOT_LOADED');\n const [error, setError] = useState(null);\n\n useEffect(() => {\n const checkStatus = () => {\n if (microAppRef.current) {\n const currentStatus = microAppRef.current.getStatus();\n if (currentStatus !== status) {\n setStatus(currentStatus);\n options.onStatusChange?.(currentStatus);\n }\n }\n };\n\n const interval = setInterval(checkStatus, 1000);\n return () => clearInterval(interval);\n }, [status, options]);\n\n const handleError = (err: Error) => {\n setError(err);\n options.onError?.(err);\n };\n\n return {\n microAppRef,\n status,\n error,\n handleError\n };\n}\n\n// 使用方式\nfunction App() {\n const { microAppRef, status, error } = useMicroApp({\n onStatusChange: (status) => console.log('状态变化:', status),\n onError: (error) => console.error('应用错误:', error)\n });\n\n return (\n
\n

状态: {status}

\n {error &&

错误: {error.message}

}\n \n
\n );\n}\n```\n\n## 🚀 性能优化\n\n### 懒加载\n\n```tsx\nimport React, { Suspense, lazy } from 'react';\n\n// 懒加载 MicroApp 组件\nconst LazyMicroApp = lazy(() => \n import('@qiankunjs/react').then(module => ({ default: module.MicroApp }))\n);\n\nfunction App() {\n return (\n 加载中...
}>\n \n \n );\n}\n```\n\n### 记忆化\n\n```tsx\nimport React, { memo, useMemo } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nconst MemoizedMicroApp = memo(MicroApp);\n\nfunction OptimizedApp({ user, settings }) {\n const microAppProps = useMemo(() => ({\n userId: user.id,\n theme: settings.theme,\n language: settings.language\n }), [user.id, settings.theme, settings.language]);\n\n return (\n \n );\n}\n```\n\n## 🐛 错误处理与调试\n\n### 开发模式错误处理\n\n```tsx\nimport React from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nfunction DevMicroApp() {\n const isDevelopment = process.env.NODE_ENV === 'development';\n\n const handleError = (error: Error) => {\n console.error('微应用错误:', error);\n \n if (isDevelopment) {\n // 在开发环境显示详细错误\n return (\n
\n

开发环境错误

\n 
{error.stack}
\n \n
\n );\n }\n \n // 在生产环境显示用户友好的错误\n return (\n
\n

出现了一些问题，请稍后再试。

\n
\n );\n };\n\n return (\n \n );\n}\n```\n\n## 📚 最佳实践\n\n### 1. 使用描述性名称\n\n```tsx\n// ✅ 好：描述性名称\n\n\n\n// ❌ 坏：通用名称\n\n\n```\n\n### 2. 始终处理加载状态\n\n```tsx\n// ✅ 好：处理加载状态\n }\n/>\n\n// ❌ 坏：没有加载指示\n\n```\n\n### 3. 实现错误边界\n\n```tsx\n// ✅ 好：优雅地处理错误\n }\n/>\n```\n\n### 4. 使用环境特定的配置\n\n```tsx\n// ✅ 好：环境感知\nconst config = {\n development: { entry: '//localhost:8080', debug: true },\n production: { entry: '//app.example.com', debug: false }\n};\n\n\n```\n\n## 🔗 相关文档\n\n- [Vue 绑定](/zh-CN/ecosystem/vue) - Vue UI 绑定\n- [核心 API](/zh-CN/api/) - qiankun 核心 API\n- [配置](/zh-CN/api/configuration) - 配置选项\n- [生命周期](/zh-CN/api/lifecycles) - 生命周期钩子 " }, { "path": "docs/zh-CN/ecosystem/vue.md", "content": "# Vue 绑定\n\nqiankun 的官方 Vue 绑定提供了一种声明式的方式来将微应用集成到您的 Vue 主应用中。`@qiankunjs/vue` 包提供了一个强大的 `` 组件，支持 Vue 2/3 兼容性、Composition API 和基于插槽的自定义。\n\n## 📦 安装\n\n```bash\nnpm install @qiankunjs/vue\n```\n\n**要求：**\n- Vue 2.0+ 或 Vue 3.0+ \n- qiankun ≥ 3.0.0\n- 对于 Vue 2，您可能需要 `@vue/composition-api`\n\n## 🚀 快速开始\n\n### Vue 3 与 Composition API\n\n```vue\n\n\n\n```\n\n### Vue 2 与 Options API\n\n```vue\n\n\n\n```\n\n### 带加载状态\n\n```vue\n\n\n\n```\n\n### 带错误处理\n\n```vue\n\n\n\n```\n\n## 🎯 组件 API\n\n### 属性\n\n| 属性 | 类型 | 必需 | 默认值 | 描述 |\n|------|------|------|--------|------|\n| `name` | `string` | ✅ | - | 微应用的唯一名称 |\n| `entry` | `string` | ✅ | - | 微应用的入口 URL |\n| `autoSetLoading` | `boolean` | ❌ | `false` | 自动管理加载状态 |\n| `autoCaptureError` | `boolean` | ❌ | `false` | 自动处理错误 |\n| `className` | `string` | ❌ | `undefined` | 微应用容器的 CSS 类 |\n| `wrapperClassName` | `string` | ❌ | `undefined` | 包装器的 CSS 类（使用插槽时） |\n| `appProps` | `Record` | ❌ | `undefined` | 传递给微应用的属性 |\n| `settings` | `AppConfiguration` | ❌ | `{}` | qiankun 配置选项 |\n| `lifeCycles` | `LifeCycles` | ❌ | `undefined` | 生命周期钩子 |\n\n### 插槽\n\n| 插槽 | 描述 | 参数 |\n|------|------|------|\n| `loader` | 自定义加载组件 | `{ loading: boolean }` |\n| `errorBoundary` | 自定义错误组件 | `{ error: Error }` |\n\n## 🎨 自定义\n\n### 使用插槽自定义加载\n\n```vue\n\n\n\n\n\n```\n\n### 自定义错误边界\n\n```vue\n\n\n\n\n\n```\n\n### 样式设置\n\n```vue\n\n\n\n```\n\n## 🔧 高级用法\n\n### 带标签页的多个微应用\n\n```vue\n\n\n\n\n\n```\n\n### 条件加载\n\n```vue\n\n\n\n```\n\n### 动态入口 URL\n\n```vue\n\n\n\n```\n\n## 🎮 状态管理\n\n### 使用 Pinia 进行状态共享\n\n```vue\n\n\n\n\n```\n\n```typescript\n// stores/app.ts\nimport { defineStore } from 'pinia';\n\nexport const useAppStore = defineStore('app', {\n state: () => ({\n user: null,\n theme: 'dark',\n language: 'zh-CN'\n }),\n \n actions: {\n setUser(user) {\n this.user = user;\n },\n \n setTheme(theme) {\n this.theme = theme;\n }\n }\n});\n```\n\n```vue\n\n\n\n\n```\n\n### 应用间通信\n\n```vue\n\n\n\n\n\n```\n\n## 🔒 TypeScript 支持\n\n### 自定义 Composable\n\n```typescript\n// composables/useMicroApp.ts\nimport { ref, onMounted, onUnmounted } from 'vue';\nimport type { Ref } from 'vue';\n\ninterface UseMicroAppOptions {\n onStatusChange?: (status: string) => void;\n onError?: (error: Error) => void;\n}\n\nexport function useMicroApp(options: UseMicroAppOptions = {}) {\n const microAppRef: Ref = ref();\n const status = ref('NOT_LOADED');\n const error = ref(null);\n\n const checkStatus = () => {\n if (microAppRef.value?.microApp) {\n const currentStatus = microAppRef.value.microApp.getStatus();\n if (currentStatus !== status.value) {\n status.value = currentStatus;\n options.onStatusChange?.(currentStatus);\n }\n }\n };\n\n const handleError = (err: Error) => {\n error.value = err;\n options.onError?.(err);\n };\n\n let interval: number;\n\n onMounted(() => {\n interval = window.setInterval(checkStatus, 1000);\n });\n\n onUnmounted(() => {\n if (interval) {\n clearInterval(interval);\n }\n });\n\n return {\n microAppRef,\n status,\n error,\n handleError\n };\n}\n```\n\n```vue\n\n\n\n```\n\n## 🚀 性能优化\n\n### 使用 Suspense 进行懒加载\n\n```vue\n\n\n\n```\n\n### 使用 computed 进行记忆化\n\n```vue\n\n\n\n```\n\n### 基于路由的微应用使用 Keep-alive\n\n```vue\n\n\n\n```\n\n```vue\n\n\n\n\n```\n\n## 🐛 错误处理与调试\n\n### 开发模式错误处理\n\n```vue\n\n\n\n```\n\n```vue\n\n\n\n\n\n\n```\n\n## 📚 Vue 2 兼容性\n\n### 在 Vue 2 中使用\n\n```vue\n\n\n\n```\n\n### 在 Vue 2 中使用 Composition API\n\n```vue\n\n\n\n```\n\n## 📚 最佳实践\n\n### 1. 使用描述性名称\n\n```vue\n\n\n\n\n\n\n\n```\n\n### 2. 始终处理加载状态\n\n```vue\n\n\n \n\n\n\n\n```\n\n### 3. 实现错误边界\n\n```vue\n\n\n \n\n```\n\n### 4. 使用响应式属性\n\n```vue\n\n\n\n\n```\n\n### 5. 环境特定的配置\n\n```vue\n\n\n\n\n```\n\n## 🔗 相关文档\n\n- [React 绑定](/zh-CN/ecosystem/react) - React UI 绑定\n- [核心 API](/zh-CN/api/) - qiankun 核心 API\n- [配置](/zh-CN/api/configuration) - 配置选项\n- [生命周期](/zh-CN/api/lifecycles) - 生命周期钩子 " }, { "path": "docs/zh-CN/ecosystem/webpack-plugin.md", "content": "# Webpack 插件\n\n`@qiankunjs/webpack-plugin` 是专为 qiankun 微前端框架设计的 Webpack 插件。它简化并自动化了将微应用与 qiankun 集成所需的常见配置，确保正确的构建输出和运行时行为。\n\n## 🚀 安装\n\n### 使用 npm\n\n```bash\nnpm install @qiankunjs/webpack-plugin --save-dev\n```\n\n### 使用 yarn\n\n```bash\nyarn add @qiankunjs/webpack-plugin --dev\n```\n\n### 使用 pnpm\n\n```bash\npnpm add @qiankunjs/webpack-plugin --save-dev\n```\n\n## 🎯 功能特性\n\n- **自动库配置**：设置正确的输出库名称和格式供 qiankun 使用\n- **唯一 JSONP 函数**：确保唯一的 `jsonpFunction` 名称以防止微应用间冲突\n- **浏览器兼容性**：将全局对象设置为 `window` 以确保在浏览器中正确执行\n- **入口脚本标记**：自动为 HTML 中的主脚本标签添加 `entry` 属性\n- **Webpack 4 & 5 支持**：兼容 Webpack 4 和 Webpack 5\n- **零配置**：开箱即用，具有合理的默认设置\n\n## 📋 系统要求\n\n- **Webpack**：4.x 或 5.x\n- **Node.js**：v14 或更高版本\n- **package.json**：必须存在于项目根目录\n\n## 🚀 快速开始\n\n### 基本用法\n\n```javascript\n// webpack.config.js\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n entry: './src/index.js',\n plugins: [\n new QiankunPlugin()\n ]\n};\n```\n\n这个基本配置将：\n- 使用 `package.json` 中的 `name` 字段作为库名称\n- 自动为最后一个脚本标签添加 `entry` 属性\n- 配置输出以供 qiankun 使用\n\n### 自定义选项\n\n```javascript\n// webpack.config.js\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n entry: './src/index.js',\n plugins: [\n new QiankunPlugin({\n packageName: 'my-micro-app',\n entrySrcPattern: /main\\.[a-f0-9]+\\.js$/\n })\n ]\n};\n```\n\n## 🎛️ 配置选项\n\n### `packageName` (可选)\n\n- **类型**：`string`\n- **默认值**：`package.json` 中的 name 字段值\n- **描述**：指定 qiankun 用于识别微应用的输出库名称\n\n```javascript\nnew QiankunPlugin({\n packageName: 'my-custom-app-name'\n})\n```\n\n### `entrySrcPattern` (可选)\n\n- **类型**：`RegExp`\n- **默认值**：`null`（将标记最后一个脚本标签）\n- **描述**：用于匹配特定脚本标签以添加 `entry` 属性的正则表达式模式\n\n```javascript\nnew QiankunPlugin({\n entrySrcPattern: /index\\.[a-f0-9]+\\.js$/\n})\n```\n\n## 🔧 框架集成\n\n### React 应用\n\n```javascript\n// webpack.config.js (Create React App with CRACO)\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n webpack: {\n plugins: {\n add: [\n new QiankunPlugin({\n packageName: 'react-micro-app'\n })\n ]\n }\n }\n};\n```\n\n### Vue 应用\n\n```javascript\n// vue.config.js\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n configureWebpack: {\n plugins: [\n new QiankunPlugin({\n packageName: 'vue-micro-app'\n })\n ]\n }\n};\n```\n\n### Angular 应用\n\n```javascript\n// custom-webpack.config.js\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunPlugin({\n packageName: 'angular-micro-app'\n })\n ]\n};\n```\n\n## 🏗️ 插件功能\n\n### 1. 输出库配置\n\n插件自动配置 webpack 输出以将微应用暴露为库：\n\n**Webpack 4：**\n```javascript\n{\n output: {\n library: 'your-app-name',\n libraryTarget: 'window',\n jsonpFunction: 'webpackJsonp_your-app-name',\n globalObject: 'window',\n chunkLoadingGlobal: 'webpackJsonp_your-app-name'\n }\n}\n```\n\n**Webpack 5：**\n```javascript\n{\n output: {\n library: {\n name: 'your-app-name',\n type: 'window'\n },\n jsonpFunction: 'webpackJsonp_your-app-name',\n globalObject: 'window',\n chunkLoadingGlobal: 'webpackJsonp_your-app-name'\n }\n}\n```\n\n### 2. 入口脚本标记\n\n插件处理 HTML 文件并为适当的脚本标签添加 `entry` 属性：\n\n**处理前：**\n```html\n\n\n\n 我的微应用\n\n\n
\n \n\n\n```\n\n**处理后：**\n```html\n\n\n\n 我的微应用\n\n\n
\n \n\n\n```\n\n## 🎨 高级配置\n\n### 自定义入口模式匹配\n\n对于具有复杂构建输出的应用，您可以精确指定哪个脚本应被标记为入口：\n\n```javascript\nnew QiankunPlugin({\n // 匹配特定命名模式的脚本\n entrySrcPattern: /main\\.[a-f0-9]{8}\\.js$/\n})\n```\n\n```javascript\nnew QiankunPlugin({\n // 匹配特定目录中的脚本\n entrySrcPattern: /\\/js\\/app\\./\n})\n```\n\n```javascript\nnew QiankunPlugin({\n // 匹配特定前缀的脚本\n entrySrcPattern: /^bundle\\./\n})\n```\n\n### 多个 HTML 文件\n\n插件会处理项目中的所有 HTML 文件，对每个文件应用相同的入口标记逻辑。\n\n### 开发与生产环境\n\n```javascript\nconst isDev = process.env.NODE_ENV === 'development';\n\nnew QiankunPlugin({\n packageName: isDev ? 'my-app-dev' : 'my-app-prod',\n entrySrcPattern: isDev ? /main\\.js$/ : /main\\.[a-f0-9]+\\.js$/\n})\n```\n\n## ✅ 验证\n\n### 检查库暴露\n\n```bash\n# 构建微应用\nnpm run build\n\n# 检查主包是否包含库\ngrep -n \"window\\[.*your-app-name\" dist/static/js/main.*.js\n```\n\n### 验证入口属性\n\n```bash\n# 检查 HTML 是否包含 entry 属性\ngrep -n \"entry\" dist/index.html\n```\n\n## 🐛 故障排除\n\n### 匹配到多个脚本标签\n\n**错误：** `The regular expression matched multiple script tags, please check your regex.`\n\n**解决方案：** 使您的正则表达式模式更具体：\n\n```javascript\n// ❌ 太宽泛 - 匹配多个文件\nentrySrcPattern: /\\.js$/\n\n// ✅ 更具体 - 只匹配主文件\nentrySrcPattern: /main\\.[a-f0-9]+\\.js$/\n```\n\n### 没有匹配到脚本标签\n\n**错误：** `The provided regular expression did not match any scripts.`\n\n**解决方案：** 检查您的模式是否与实际生成的文件名匹配：\n\n```javascript\n// 检查实际生成的文件\nconsole.log(fs.readdirSync('dist/static/js/'));\n\n// 相应调整模式\nentrySrcPattern: /app\\.[a-f0-9]+\\.js$/\n```\n\n### 库未暴露\n\n**问题：** qiankun 找不到您的微应用\n\n**解决方案：**\n\n1. 检查 `package.json` 是否有有效的名称：\n```json\n{\n \"name\": \"my-micro-app\"\n}\n```\n\n2. 在浏览器控制台中验证库是否已暴露：\n```javascript\n// 加载后应该存在\nwindow['my-micro-app']\n```\n\n3. 确保插件已应用：\n```javascript\n// 确保插件在 plugins 数组中\nplugins: [\n new QiankunPlugin()\n]\n```\n\n### JSONP 函数冲突\n\n**问题：** 多个微应用导致冲突\n\n**解决方案：** 使用不同的包名称：\n\n```javascript\n// 应用 1\nnew QiankunPlugin({\n packageName: 'app-dashboard'\n})\n\n// 应用 2\nnew QiankunPlugin({\n packageName: 'app-settings'\n})\n```\n\n## 🔧 集成示例\n\n### Create React App (CRACO)\n\n```javascript\n// craco.config.js\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n webpack: {\n configure: (webpackConfig) => {\n webpackConfig.plugins.push(\n new QiankunPlugin({\n packageName: process.env.REACT_APP_NAME || 'react-app'\n })\n );\n return webpackConfig;\n }\n }\n};\n```\n\n### Vue CLI\n\n```javascript\n// vue.config.js\nconst { defineConfig } = require('@vue/cli-service');\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = defineConfig({\n configureWebpack: {\n plugins: [\n new QiankunPlugin()\n ]\n },\n // 额外的 qiankun 特定配置\n devServer: {\n port: 8080,\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n});\n```\n\n### Next.js (使用自定义 webpack 配置)\n\n```javascript\n// next.config.js\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n webpack: (config, { dev, isServer }) => {\n if (!isServer) {\n config.plugins.push(\n new QiankunPlugin({\n packageName: 'nextjs-micro-app'\n })\n );\n }\n return config;\n }\n};\n```\n\n### Vite (使用 vite-plugin-qiankun)\n\n虽然此插件是为 Webpack 设计的，但对于 Vite 用户：\n\n```javascript\n// vite.config.js\nimport { defineConfig } from 'vite';\nimport qiankun from 'vite-plugin-qiankun';\n\nexport default defineConfig({\n plugins: [\n qiankun('my-vite-app', {\n useDevMode: true\n })\n ]\n});\n```\n\n## 📊 性能考虑\n\n### 包体积\n\n插件对包的开销很小：\n- 库包装器：~100 字节\n- JSONP 函数自定义：~50 字节\n\n### 构建时间\n\n插件在 emit 阶段运行，通常增加：\n- HTML 处理：< 100ms\n- webpack 配置：< 50ms\n\n### 运行时性能\n\n- 无运行时性能影响\n- 启用 qiankun 的高效加载机制\n- 防止全局命名空间冲突\n\n## 🔒 安全考虑\n\n### 库命名\n\n使用描述性、非冲突的库名称：\n\n```javascript\n// ✅ 好 - 特定且唯一\npackageName: 'company-dashboard-app'\n\n// ❌ 坏 - 太通用，可能冲突\npackageName: 'app'\n```\n\n### CORS 配置\n\n确保您的微应用使用适当的 CORS 头提供服务：\n\n```javascript\n// 开发服务器配置\ndevServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',\n 'Access-Control-Allow-Headers': 'X-Requested-With, content-type, Authorization'\n }\n}\n```\n\n## 📚 最佳实践\n\n### 1. 一致的命名约定\n\n```javascript\n// 跨环境使用一致的命名\nconst appName = process.env.NODE_ENV === 'production' \n ? 'company-app-prod' \n : 'company-app-dev';\n\nnew QiankunPlugin({\n packageName: appName\n})\n```\n\n### 2. 环境特定的模式\n\n```javascript\n// 不同环境使用不同模式\nconst entrySrcPattern = process.env.NODE_ENV === 'production'\n ? /main\\.[a-f0-9]+\\.js$/ // 生产环境使用哈希\n : /main\\.js$/; // 开发环境使用简单名称\n\nnew QiankunPlugin({\n entrySrcPattern\n})\n```\n\n### 3. 验证配置\n\n```javascript\n// 在构建过程中添加验证\nconst pkg = require('./package.json');\n\nif (!pkg.name) {\n throw new Error('package.json 必须有 name 字段供 qiankun 使用');\n}\n\nnew QiankunPlugin({\n packageName: pkg.name\n})\n```\n\n### 4. 测试集成\n\n```javascript\n// 测试您的配置\ndescribe('Qiankun 集成', () => {\n it('应该在 window 上暴露库', () => {\n expect(window[process.env.REACT_APP_NAME]).toBeDefined();\n });\n\n it('应该有入口脚本标记', () => {\n const entryScript = document.querySelector('script[entry]');\n expect(entryScript).toBeTruthy();\n });\n});\n```\n\n## 🔗 相关文档\n\n- [核心 API](/zh-CN/api/) - qiankun 核心 API\n- [Create Qiankun](/zh-CN/ecosystem/create-qiankun) - 项目脚手架工具\n- [React 绑定](/zh-CN/ecosystem/react) - React UI 绑定\n- [Vue 绑定](/zh-CN/ecosystem/vue) - Vue UI 绑定\n\n## 📈 迁移指南\n\n### 从手动配置迁移\n\n如果您之前手动配置 webpack for qiankun：\n\n**之前：**\n```javascript\nmodule.exports = {\n output: {\n library: 'myApp',\n libraryTarget: 'window',\n jsonpFunction: 'webpackJsonp_myApp'\n }\n};\n```\n\n**之后：**\n```javascript\nconst { QiankunPlugin } = require('@qiankunjs/webpack-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunPlugin({\n packageName: 'myApp'\n })\n ]\n};\n```\n\n### 从其他微前端解决方案迁移\n\n该插件处理 qiankun 所需的 webpack 特定配置，消除了手动库设置和入口脚本标记的需要。\n\n## 🤝 贡献\n\n发现问题或想要贡献？查看 [GitHub 仓库](https://github.com/umijs/qiankun) 并贡献到 `packages/webpack-plugin` 目录。 " }, { "path": "docs/zh-CN/faq/index.md", "content": "# 常见问题\n\n本 FAQ 涵盖了使用 qiankun 时遇到的最常见问题和问题。如果您找不到所需的答案，请查看我们的 [GitHub Issues](https://github.com/umijs/qiankun/issues) 或加入我们的社区讨论。\n\n## 🚀 入门指南\n\n### 问：什么是 qiankun，什么时候应该使用它？\n\n**答：** qiankun 是一个基于 single-spa 的微前端框架，通过组合多个较小的独立应用来构建大规模前端应用。在以下情况下应该考虑使用 qiankun：\n\n- 团队在不断壮大，需要跨多个团队扩展开发\n- 有需要与新功能共存的遗留应用\n- 希望在一个应用中使用不同的框架（React、Vue、Angular）\n- 需要为应用的不同部分提供独立部署能力\n\n### 问：qiankun 与其他微前端解决方案有何不同？\n\n**答：** qiankun 提供了几个关键优势：\n\n- **生产就绪**：由蚂蚁集团在大规模应用中构建和测试\n- **框架无关**：适用于 React、Vue、Angular 和原生 JavaScript\n- **强大的沙箱**：开箱即用的 JavaScript 和 CSS 隔离\n- **HTML 入口**：使用 HTML 文件作为入口点的简单配置\n- **丰富的生态系统**：UI 绑定、CLI 工具和 webpack 插件\n\n### 问：我可以在现有应用中使用 qiankun 吗？\n\n**答：** 可以！qiankun 旨在与现有应用一起工作。您可以：\n\n1. **包装现有应用**：将当前应用转换为 qiankun 主应用\n2. **增量迁移**：逐步将功能提取到微应用中\n3. **遗留集成**：在新微应用旁边运行遗留应用\n4. **框架迁移**：逐步从一个框架迁移到另一个框架\n\n## 🔧 安装和设置\n\n### 问：加载微应用时遇到 CORS 错误，如何修复？\n\n**答：** CORS 错误在开发中很常见。以下是解决方案：\n\n**对于 webpack dev server：**\n```javascript\n// webpack.config.js 或 vue.config.js\nmodule.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',\n 'Access-Control-Allow-Headers': 'X-Requested-With, content-type, Authorization'\n }\n }\n};\n```\n\n**对于 Create React App（使用 CRACO）：**\n```javascript\n// craco.config.js\nmodule.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n};\n```\n\n**对于生产环境，配置您的服务器：**\n```nginx\n# nginx.conf\nlocation / {\n add_header Access-Control-Allow-Origin *;\n add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';\n add_header Access-Control-Allow-Headers 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';\n}\n```\n\n### 问：我的微应用无法加载，应该检查什么？\n\n**答：** 按照此故障排除清单：\n\n1. **检查网络选项卡**：微应用资源是否有 404 错误？\n2. **验证 CORS**：控制台中是否有 CORS 错误？\n3. **检查入口点**：HTML 入口文件是否可访问？\n4. **验证导出**：微应用是否导出了必需的生命周期方法？\n5. **检查容器**：DOM 中是否存在容器元素？\n\n**正确的微应用导出示例：**\n```javascript\n// 微应用入口文件\nexport async function bootstrap() {\n console.log('micro app bootstrapped');\n}\n\nexport async function mount(props) {\n console.log('micro app mounted', props);\n // 您的应用挂载逻辑\n}\n\nexport async function unmount(props) {\n console.log('micro app unmounted', props);\n // 您的应用清理逻辑\n}\n```\n\n### 问：如何处理微应用的不同基础路径？\n\n**答：** 在微应用中配置公共路径：\n\n**对于 webpack：**\n```javascript\n// webpack.config.js\nmodule.exports = {\n output: {\n publicPath: process.env.NODE_ENV === 'production' \n ? 'https://mycdn.com/micro-app/' \n : 'http://localhost:8080/'\n }\n};\n```\n\n**对于运行时配置：**\n```javascript\n// 微应用中的 public-path.js\nif (window.__POWERED_BY_QIANKUN__) {\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n}\n```\n\n## 🏗️ 架构和设计\n\n### 问：我应该如何构建微前端架构？\n\n**答：** 遵循以下架构原则：\n\n**1. 领域驱动设计：**\n```\n主应用（Shell）\n├── 用户管理（HR 领域）\n├── 产品目录（商务领域）\n├── 分析仪表板（BI 领域）\n└── 设置（系统领域）\n```\n\n**2. 共享与独立：**\n- **共享**：身份验证、导航、设计系统\n- **独立**：业务逻辑、数据获取、内部状态\n\n**3. 通信模式：**\n```javascript\n// 事件驱动通信\nwindow.dispatchEvent(new CustomEvent('user-updated', { \n detail: { userId: 123 } \n}));\n\n// 基于属性的通信\nregisterMicroApps([{\n name: 'user-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/users',\n props: { \n userPermissions: currentUser.permissions,\n onUserUpdate: handleUserUpdate\n }\n}]);\n```\n\n### 问：如何在微应用之间共享依赖？\n\n**答：** 几种方法效果很好：\n\n**1. 外部依赖（推荐）：**\n```javascript\n// webpack.config.js\nmodule.exports = {\n externals: {\n 'react': 'React',\n 'react-dom': 'ReactDOM',\n 'lodash': '_'\n }\n};\n```\n\n**2. 模块联邦：**\n```javascript\n// 主应用 webpack 配置\nnew ModuleFederationPlugin({\n name: 'shell',\n shared: {\n react: { singleton: true },\n 'react-dom': { singleton: true }\n }\n});\n```\n\n**3. CDN 方法：**\n```html\n\n\n\n```\n\n### 问：微应用可以相互通信吗？\n\n**答：** 可以，以下是推荐的模式：\n\n**1. 事件驱动通信：**\n```javascript\n// 微应用 A\nconst notifyOtherApps = (data) => {\n window.dispatchEvent(new CustomEvent('app-a-event', { detail: data }));\n};\n\n// 微应用 B\nwindow.addEventListener('app-a-event', (event) => {\n console.log('从应用 A 接收到:', event.detail);\n});\n```\n\n**2. 共享状态管理：**\n```javascript\n// 全局存储\nwindow.__SHARED_STORE__ = {\n user: null,\n subscribers: [],\n updateUser: (user) => {\n window.__SHARED_STORE__.user = user;\n window.__SHARED_STORE__.subscribers.forEach(callback => callback(user));\n }\n};\n```\n\n**3. 来自主应用的属性：**\n```javascript\n// 主应用协调通信\nconst handleDataChange = (data) => {\n // 更新所有相关微应用的属性\n updateMicroAppProps('app-a', { sharedData: data });\n updateMicroAppProps('app-b', { sharedData: data });\n};\n```\n\n## 🎨 样式和 CSS\n\n### 问：微应用之间的 CSS 样式发生冲突，如何修复？\n\n**答：** 使用 qiankun 的内置样式隔离：\n\n**1. 严格样式隔离（Shadow DOM）：**\n```javascript\nimport { start } from 'qiankun';\n\nstart({\n sandbox: {\n strictStyleIsolation: true\n }\n});\n```\n\n**2. 实验性样式隔离（CSS 作用域）：**\n```javascript\nstart({\n sandbox: {\n experimentalStyleIsolation: true\n }\n});\n```\n\n**3. 手动 CSS 作用域：**\n```css\n/* 为所有样式添加前缀 */\n.my-micro-app .button {\n background: blue;\n}\n\n.my-micro-app .container {\n padding: 20px;\n}\n```\n\n查看我们的[样式隔离指南](/cookbook/style-isolation)获取全面的解决方案。\n\n### 问：我可以在 qiankun 中使用 CSS-in-JS 库吗？\n\n**答：** 当然可以！CSS-in-JS 库与 qiankun 配合得很好：\n\n**Styled Components：**\n```jsx\nimport styled from 'styled-components';\n\nconst Button = styled.button`\n background: blue;\n color: white;\n`;\n```\n\n**Emotion：**\n```jsx\n/** @jsxImportSource @emotion/react */\nimport { css } from '@emotion/react';\n\nconst buttonStyle = css`\n background: blue;\n color: white;\n`;\n```\n\nCSS-in-JS 提供天然隔离，因为样式作用域限定在组件中。\n\n## 🔄 路由和导航\n\n### 问：如何在微前端设置中处理路由？\n\n**答：** qiankun 支持多种路由策略：\n\n**1. 基于路由的微应用（推荐）：**\n```javascript\nregisterMicroApps([\n {\n name: 'user-management',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/users' // 当路由以 /users 开头时加载\n },\n {\n name: 'product-catalog',\n entry: '//localhost:8081', \n container: '#container',\n activeRule: ['/products', '/categories'] // 多个路由\n }\n]);\n```\n\n**2. 编程式路由：**\n```javascript\n// 在微应用之间导航\nimport { navigateToUrl } from 'single-spa';\n\nconst navigateToUsers = () => {\n navigateToUrl('/users');\n};\n```\n\n**3. 哈希路由：**\n```javascript\nregisterMicroApps([\n {\n name: 'hash-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '#/app' // 基于哈希的路由\n }\n]);\n```\n\n### 问：微应用可以有自己的内部路由吗？\n\n**答：** 可以！每个微应用都可以有自己的内部路由器：\n\n**React Router 示例：**\n```jsx\n// 在您的微应用中\nimport { BrowserRouter, Routes, Route } from 'react-router-dom';\n\nfunction App() {\n const basename = window.__POWERED_BY_QIANKUN__ ? '/users' : '/';\n \n return (\n \n \n } />\n } />\n } />\n \n \n );\n}\n```\n\n## 🚀 性能\n\n### 问：我的微前端应用加载缓慢，如何提高性能？\n\n**答：** 遵循这些优化策略：\n\n**1. 启用预取：**\n```javascript\nstart({\n prefetch: true // 或 'all' 或特定应用名称\n});\n```\n\n**2. 使用代码分割：**\n```javascript\n// 微应用中的动态导入\nconst HeavyComponent = React.lazy(() => import('./HeavyComponent'));\n```\n\n**3. 优化包大小：**\n```javascript\n// webpack.config.js\nmodule.exports = {\n optimization: {\n splitChunks: {\n chunks: 'all'\n }\n }\n};\n```\n\n查看我们的[性能优化指南](/cookbook/performance)获取详细策略。\n\n### 问：如何防止微应用中的内存泄漏？\n\n**答：** 实施适当的清理：\n\n```javascript\n// 微应用生命周期\nexport async function unmount() {\n // 清除定时器\n clearInterval(myInterval);\n \n // 移除事件监听器\n window.removeEventListener('resize', handleResize);\n \n // 清理订阅\n subscription.unsubscribe();\n \n // 清除缓存\n cache.clear();\n}\n```\n\n## 🛠️ 开发和调试\n\n### 问：如何在开发中调试微应用？\n\n**答：** 使用这些调试策略：\n\n**1. 启用源映射：**\n```javascript\n// webpack.config.js\nmodule.exports = {\n devtool: 'source-map'\n};\n```\n\n**2. 使用浏览器开发工具：**\n- 网络选项卡：检查资源加载\n- 控制台：查看错误消息\n- 元素：检查 DOM 结构\n- 源码：使用断点调试 JavaScript\n\n**3. qiankun 调试：**\n```javascript\n// 启用详细日志\nlocalStorage.setItem('qiankun:debug', true);\n```\n\n### 问：我可以在微应用中使用热重载吗？\n\n**答：** 可以，需要一些配置：\n\n**对于 webpack dev server：**\n```javascript\n// webpack.config.js\nmodule.exports = {\n devServer: {\n hot: true,\n headers: {\n 'Access-Control-Allow-Origin': '*'\n }\n }\n};\n```\n\n**注意**：热重载在每个微应用内工作，但主应用的更改可能需要完全刷新。\n\n## 🔒 安全\n\n### 问：如何处理跨微应用的身份验证？\n\n**答：** 在主应用中集中身份验证：\n\n**1. 基于令牌的身份验证：**\n```javascript\n// 主应用处理身份验证\nconst userToken = await authenticate(credentials);\nlocalStorage.setItem('token', userToken);\n\n// 将令牌传递给微应用\nregisterMicroApps([{\n name: 'secure-app',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/secure',\n props: {\n token: userToken,\n user: currentUser\n }\n}]);\n```\n\n**2. 共享身份验证状态：**\n```javascript\n// 全局身份验证状态\nwindow.__AUTH_STATE__ = {\n user: currentUser,\n token: userToken,\n isAuthenticated: true\n};\n```\n\n### 问：微前端是否存在安全问题？\n\n**答：** 请注意这些安全考虑：\n\n**1. 内容安全策略（CSP）：**\n```html\n\n```\n\n**2. CORS 配置：**\n- 只允许受信任的来源\n- 正确验证请求\n- 在生产中使用 HTTPS\n\n**3. 依赖安全：**\n- 定期审计依赖\n- 使用 `npm audit` 等工具\n- 保持依赖更新\n\n## 📱 移动端和浏览器支持\n\n### 问：qiankun 在移动设备上工作吗？\n\n**答：** 可以，qiankun 在移动端工作，需要考虑：\n\n**1. 触摸事件优化：**\n```javascript\n// 使用被动监听器\nelement.addEventListener('touchstart', handler, { passive: true });\n```\n\n**2. 视口管理：**\n```html\n\n```\n\n**3. 性能优化：**\n- 减少包大小\n- 使用懒加载\n- 优化图片和资源\n\n### 问：qiankun 支持哪些浏览器？\n\n**答：** qiankun 支持现代浏览器：\n\n- **Chrome**：49+\n- **Firefox**：45+\n- **Safari**：10+\n- **Edge**：79+\n- **IE**：不支持\n\n对于较旧的浏览器，考虑使用 polyfill：\n```html\n\n```\n\n## 🚢 部署\n\n### 问：如何部署微前端应用？\n\n**答：** 使用独立部署策略：\n\n**1. 分别构建：**\n```bash\n# 独立构建每个应用\ncd main-app && npm run build\ncd micro-app-1 && npm run build \ncd micro-app-2 && npm run build\n```\n\n**2. CDN 部署：**\n```javascript\n// 为每个应用配置不同的 CDN\nconst microApps = [\n {\n name: 'app-1',\n entry: 'https://cdn1.example.com/app-1/',\n container: '#container',\n activeRule: '/app-1'\n },\n {\n name: 'app-2', \n entry: 'https://cdn2.example.com/app-2/',\n container: '#container',\n activeRule: '/app-2'\n }\n];\n```\n\n### 问：如何处理版本控制和更新？\n\n**答：** 实施版本管理：\n\n**1. 语义化版本：**\n```javascript\n// 每个微应用的 package.json\n{\n \"name\": \"user-management-app\",\n \"version\": \"1.2.3\"\n}\n```\n\n**2. 运行时版本检查：**\n```javascript\nconst requiredVersion = '1.2.0';\nconst currentVersion = window.__MICRO_APP_VERSION__;\n\nif (!semver.gte(currentVersion, requiredVersion)) {\n console.warn('微应用版本兼容性问题');\n}\n```\n\n## 🔗 集成\n\n### 问：我可以在服务端渲染（SSR）中使用 qiankun 吗？\n\n**答：** 微前端的 SSR 很复杂但是可能的：\n\n**1. 静态渲染：**\n- 在服务器上渲染微应用\n- 在客户端进行水合\n\n**2. 考虑因素：**\n- 每个微应用都需要 SSR 支持\n- 应用之间的协调具有挑战性\n- 性能影响\n\n**替代方法：**\n- 使用边缘侧包含（ESI）\n- 在页面级别实施微前端\n- 考虑客户端渲染与快速初始加载\n\n### 问：如何将 qiankun 与现有构建工具集成？\n\n**答：** qiankun 与各种构建工具配合使用：\n\n**Webpack：** 使用 `@qiankunjs/webpack-plugin`\n**Vite：** 使用 `vite-plugin-qiankun`\n**Rollup：** 手动配置\n**Parcel：** 手动配置\n\n查看我们的[生态系统](/ecosystem/)部分了解特定集成。\n\n## 🤝 社区和支持\n\n### 问：如果我遇到困难，在哪里可以获得帮助？\n\n**答：** 有多个支持渠道可用：\n\n1. **GitHub Issues**：[umijs/qiankun](https://github.com/umijs/qiankun/issues)\n2. **讨论**：GitHub 讨论用于提问\n3. **Stack Overflow**：用 `qiankun` 标签提问\n4. **Discord/Slack**：社区聊天室\n\n### 问：我如何为 qiankun 做贡献？\n\n**答：** 我们欢迎贡献：\n\n1. **错误报告**：提交详细的问题报告\n2. **功能请求**：提议新功能\n3. **代码贡献**：提交拉取请求\n4. **文档**：改进文档和示例\n5. **社区**：帮助回答问题\n\n查看我们的[贡献指南](https://github.com/umijs/qiankun/blob/master/CONTRIBUTING.md)了解详情。\n\n---\n\n## 📚 其他资源\n\n- [完整 API 参考](/api/)\n- [最佳实践指南](/cookbook/)\n- [生态系统工具](/ecosystem/)\n- [GitHub 仓库](https://github.com/umijs/qiankun)\n- [示例应用](https://github.com/umijs/qiankun/tree/master/examples)\n\n**找不到您要找的内容？** 请[提交问题](https://github.com/umijs/qiankun/issues/new)或开始[讨论](https://github.com/umijs/qiankun/discussions) - 我们在这里帮助您！ " }, { "path": "docs/zh-CN/guide/index.md", "content": "# 什么是 qiankun？\n\nqiankun 是一个基于 [single-spa](https://github.com/single-spa/single-spa) 的微前端实现库，旨在帮助大家能更简单、无痛地构建一个生产可用的微前端架构系统。\n\nqiankun 孵化自蚂蚁金融科技基于微前端架构的云产品统一接入平台，在经过大量的线上应用运行验证及打磨后，我们将其微前端内核抽取出来并开源，希望能同时帮助社区有类似需求的系统更方便的构建自己的微前端系统，同时也希望通过社区的帮助将 qiankun 打磨的更加成熟完善。\n\n目前 qiankun 已在蚂蚁内部服务了超过 2000 个线上应用，在易用性和完整性上，绝对是值得信赖的。\n\n## 💡 什么是微前端？\n\n> 微前端是一种通过独立发布功能来让多个团队共同构建现代 Web 应用的方式。 -- 微前端\n\n微前端架构具有以下核心价值：\n\n- **技术栈无关** - 主框架不限制接入应用的技术栈，微应用具备完全自主权\n- **独立开发、独立部署** - 微应用仓库独立，前后端可独立开发，部署完成后主框架自动完成同步更新\n- **增量升级** - 面对各种复杂场景，我们通常很难对一个已经存在的系统做全量的技术栈升级或重构，而微前端是一种非常好的实施渐进式重构的手段和策略\n- **独立运行时** - 每个微应用之间状态隔离，运行时状态不共享\n\n微前端架构旨在解决单体应用在一个相对长的时间跨度下，由于参与的人员、团队的增多、变迁，从一个普通应用演变成一个巨石应用(Frontend Monolith)后，随之而来的应用不可维护的问题。这类问题在企业级 Web 应用中尤其常见。\n\n### 传统单体应用的问题\n\n```bash\n┌─────────────────────────────────────┐\n│ 单体前端应用 │\n│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │\n│ │模块A│ │模块B│ │模块C│ │模块D│ │\n│ └─────┘ └─────┘ └─────┘ └─────┘ │\n│ 紧密耦合，难以维护 │\n└─────────────────────────────────────┘\n```\n\n### 微前端架构\n\n```bash\n┌─────────────────────────────────────┐\n│ 主应用 │\n│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │\n│ │应用A│ │应用B│ │应用C│ │应用D│ │\n│ └─────┘ └─────┘ └─────┘ └─────┘ │\n│ 独立开发、部署，技术栈无关 │\n└─────────────────────────────────────┘\n```\n\n## 🎯 核心理念\n\nqiankun 的核心设计理念是**去中心化运行时**，这意味着：\n\n- **🥄 简单** - 由于主应用微应用都能做到技术栈无关，qiankun 对于用户而言只是一个类似 jQuery 的库。你需要调用几个 qiankun 的 API 即可完成应用的微前端改造。同时由于 qiankun 的 HTML Entry 及沙箱的设计，使得微应用的接入像使用 iframe 一样简单。\n\n- **🍡 解耦/技术栈无关** - 微前端的核心目标是将巨石应用拆解成若干可以自治的松耦合微应用，而 qiankun 的诸多设计均是秉持这一原则，如 HTML Entry、沙箱、应用间通信等。这样才能确保微应用真正具备独立开发、独立运行的能力。\n\n## 🏗️ 架构图\n\n```mermaid\ngraph TD\n A[主应用] --> B[qiankun]\n B --> C[微应用 A]\n B --> D[微应用 B]\n B --> E[微应用 C]\n \n F[路由] --> A\n G[资源加载] --> B\n H[生命周期] --> B\n I[沙箱隔离] --> B\n```\n\nqiankun 基于以下核心能力：\n\n### 🔄 生命周期管理\n每个微应用都有完整的生命周期：\n- **bootstrap** - 应用初始化\n- **mount** - 应用挂载\n- **unmount** - 应用卸载\n- **update** - 应用更新（可选）\n\n### 🛡️ 沙箱隔离\n- **JS 隔离** - 提供多种沙箱方案，确保应用间 JS 互不影响\n- **CSS 隔离** - 通过样式作用域或 Shadow DOM 实现样式隔离\n\n### 📡 资源加载\n- **HTML Entry** - 通过 HTML 作为入口加载微应用\n- **预加载** - 支持应用资源预加载，提升用户体验\n- **缓存** - 智能资源缓存策略\n\n## 🤔 为什么不是 iframe？\n\n虽然 iframe 是实现微前端最自然的方案，但它也有一些严重的限制：\n\n- **URL 同步问题** - iframe 的 URL 和主应用的 URL 无法同步\n- **UI 不一致** - iframe 处于完全隔离的上下文中，很难保持一致的 UI 样式\n- **性能问题** - 每个 iframe 都会创建新的上下文，消耗更多内存和 CPU 资源\n- **SEO 不友好** - 搜索引擎无法正确索引 iframe 内容\n- **安全限制** - 跨域 iframe 通信存在安全限制\n- **用户体验问题** - 浏览器历史记录、刷新、书签等功能存在问题\n\nqiankun 通过提供完整的微前端解决方案来解决这些问题，既保持了 iframe 的隔离优势，又避免了其局限性。\n\n## ✨ 功能特性\n\nqiankun 提供以下关键特性：\n\n- **📦 基于 single-spa** - 基于 single-spa 提供更加开箱即用的 API\n- **📱 技术栈无关** - 任意 JavaScript 框架都可以使用/接入，无论是 React/Vue/Angular/jQuery 还是其他框架\n- **💪 HTML Entry 接入方式** - 让你接入微应用像使用 iframe 一样简单\n- **🛡️ 样式隔离** - 确保应用间样式不会相互影响\n- **🧳 JS 沙箱** - 确保微应用间全局变量/事件不冲突\n- **⚡ 资源预加载** - 在浏览器空闲时间预加载未打开的微应用资源，加速微应用打开速度\n- **🔌 Umi 插件** - 提供了 @umijs/plugin-qiankun 供 umi 应用一键切换成微前端架构系统\n\n## 🎯 适用场景\n\nqiankun 特别适合以下场景：\n\n- **大型企业应用** - 多团队协作开发\n- **技术栈迁移** - 渐进式升级遗留系统\n- **功能模块化** - 功能模块独立开发部署\n- **第三方集成** - 集成外部应用或服务\n\n## 🚀 开始使用\n\n准备开始使用 qiankun？查看我们的[快速开始](/zh-CN/guide/quick-start)指南，几分钟内构建你的第一个微前端应用！\n\n## 📚 深入学习\n\n- [教程](/zh-CN/guide/tutorial) - 从零开始的详细教程\n- [核心概念](/zh-CN/guide/concepts) - 理解 qiankun 的设计原理\n- [主应用](/zh-CN/guide/main-app) - 如何配置主应用\n- [微应用](/zh-CN/guide/micro-app) - 如何改造现有应用 " }, { "path": "docs/zh-CN/guide/quick-start.md", "content": "# 快速开始\n\n本指南将帮助你在 5 分钟内搭建一个基础的 qiankun 微前端应用。\n\n## 前置条件\n\n- Node.js 16+\n- 基础的 JavaScript/TypeScript 知识\n- 了解 React、Vue 或其他前端框架\n\n## 🚀 步骤 1：安装 qiankun\n\n::: code-group\n\n```bash [npm]\nnpm install qiankun\n```\n\n```bash [yarn]\nyarn add qiankun\n```\n\n```bash [pnpm]\npnpm add qiankun\n```\n\n:::\n\n## 🏠 步骤 2：主应用配置\n\n### 2.1 创建主应用\n\n```bash\n# 使用你喜欢的框架创建主应用\nnpx create-react-app main-app\ncd main-app\nnpm install qiankun\n```\n\n### 2.2 注册微应用\n\n在主应用的入口文件中注册微应用：\n\n```typescript\n// src/index.js\nimport { registerMicroApps, start } from 'qiankun';\n\n// 注册微应用\nregisterMicroApps([\n {\n name: 'vue-app', // 微应用名称，唯一\n entry: '//localhost:8080', // 微应用入口\n container: '#subapp-viewport', // 微应用挂载节点\n activeRule: '/vue', // 微应用激活规则\n },\n {\n name: 'react-app',\n entry: '//localhost:3001',\n container: '#subapp-viewport',\n activeRule: '/react',\n },\n]);\n\n// 启动 qiankun\nstart();\n\n// 正常渲染主应用\nReactDOM.render(, document.getElementById('root'));\n```\n\n### 2.3 创建微应用容器\n\n在主应用中为微应用预留挂载节点：\n\n```jsx\n// src/App.js\nimport React from 'react';\nimport { BrowserRouter as Router, Link } from 'react-router-dom';\n\nfunction App() {\n return (\n \n
\n
\n

qiankun 主应用

\n \n
\n {/* 微应用挂载点 */}\n
\n
\n \n );\n}\n\nexport default App;\n```\n\n## 📦 步骤 3：微应用配置\n\n### 3.1 创建 Vue 微应用\n\n```bash\nnpm install -g @vue/cli\nvue create vue-micro-app\ncd vue-micro-app\n```\n\n### 3.2 导出生命周期\n\n修改 `src/main.js`：\n\n```javascript\nimport { createApp } from 'vue';\nimport { createRouter, createWebHistory } from 'vue-router';\nimport App from './App.vue';\nimport routes from './router';\n\nlet instance = null;\nlet router = null;\n\n/**\n * 渲染函数\n * 两种情况：主应用生命周期调用 / 微应用独立运行\n */\nfunction render(props = {}) {\n const { container } = props;\n \n router = createRouter({\n history: createWebHistory(window.__POWERED_BY_QIANKUN__ ? '/vue' : '/'),\n routes,\n });\n\n instance = createApp(App);\n instance.use(router);\n instance.mount(container ? container.querySelector('#app') : '#app');\n}\n\n// 独立运行\nif (!window.__POWERED_BY_QIANKUN__) {\n render();\n}\n\nexport async function bootstrap() {\n console.log('[vue] vue 应用启动');\n}\n\nexport async function mount(props) {\n console.log('[vue] 来自主框架的参数', props);\n render(props);\n}\n\nexport async function unmount() {\n instance.unmount();\n instance._container.innerHTML = '';\n instance = null;\n router = null;\n}\n```\n\n### 3.3 配置 Webpack\n\n修改 `vue.config.js`：\n\n```javascript\nconst { defineConfig } = require('@vue/cli-service');\nconst packageName = require('./package.json').name;\n\nmodule.exports = defineConfig({\n transpileDependencies: true,\n devServer: {\n port: 8080,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n configureWebpack: {\n output: {\n library: `${packageName}-[name]`,\n libraryTarget: 'umd',\n chunkLoadingGlobal: `webpackJsonp_${packageName}`,\n },\n },\n});\n```\n\n### 3.4 创建 React 微应用\n\n```bash\nnpx create-react-app react-micro-app\ncd react-micro-app\nnpm install react-app-rewired --save-dev\n```\n\n修改 `src/index.js`：\n\n```javascript\nimport React from 'react';\nimport ReactDOM from 'react-dom';\nimport './index.css';\nimport App from './App';\n\nfunction render(props) {\n const { container } = props;\n ReactDOM.render(\n , \n container ? container.querySelector('#root') : document.querySelector('#root')\n );\n}\n\nif (!window.__POWERED_BY_QIANKUN__) {\n render({});\n}\n\nexport async function bootstrap() {\n console.log('[react16] react 应用启动');\n}\n\nexport async function mount(props) {\n console.log('[react16] 来自主框架的参数', props);\n render(props);\n}\n\nexport async function unmount(props) {\n const { container } = props;\n ReactDOM.unmountComponentAtNode(\n container ? container.querySelector('#root') : document.querySelector('#root')\n );\n}\n```\n\n创建 `config-overrides.js`：\n\n```javascript\nconst { name } = require('./package');\n\nmodule.exports = {\n webpack: (config) => {\n config.output.library = `${name}-[name]`;\n config.output.libraryTarget = 'umd';\n config.output.chunkLoadingGlobal = `webpackJsonp_${name}`;\n return config;\n },\n\n devServer: function (configFunction) {\n return function(proxy, allowedHost) {\n const config = configFunction(proxy, allowedHost);\n config.port = 3001;\n config.headers = {\n 'Access-Control-Allow-Origin': '*',\n };\n return config;\n };\n },\n};\n```\n\n修改 `package.json` 中的脚本：\n\n```json\n{\n \"scripts\": {\n \"start\": \"react-app-rewired start\",\n \"build\": \"react-app-rewired build\",\n \"test\": \"react-app-rewired test\",\n \"eject\": \"react-scripts eject\"\n }\n}\n```\n\n## 🎉 步骤 4：启动应用\n\n### 4.1 启动所有应用\n\n```bash\n# 终端 1：启动主应用\ncd main-app\nnpm start\n\n# 终端 2：启动 Vue 微应用\ncd vue-micro-app \nnpm run serve\n\n# 终端 3：启动 React 微应用\ncd react-micro-app\nnpm start\n```\n\n### 4.2 访问应用\n\n- 主应用：http://localhost:3000\n- 点击导航切换到不同的微应用\n\n## ✅ 验证集成\n\n如果一切配置正确，你应该看到：\n\n1. ✅ 主应用正常加载\n2. ✅ 点击导航链接切换到对应的微应用\n3. ✅ 微应用可以独立访问（http://localhost:8080, http://localhost:3001）\n4. ✅ 浏览器控制台显示生命周期日志\n\n## 🎯 常见问题\n\n::: warning CORS 问题\n确保你的微应用 webpack devServer 配置了 CORS 头：\n```javascript\nheaders: {\n 'Access-Control-Allow-Origin': '*',\n}\n```\n:::\n\n::: warning 路由冲突\n在集成模式下，微应用路由需要添加对应前缀：\n```javascript\n// Vue Router\nhistory: createWebHistory(window.__POWERED_BY_QIANKUN__ ? '/vue' : '/')\n\n// React Router\n\n```\n:::\n\n## 🚀 下一步\n\n恭喜！你已经成功构建了第一个 qiankun 微前端应用。接下来你可以：\n\n- [核心概念](/zh-CN/guide/concepts) - 深入理解 qiankun 的设计原理\n- [主应用](/zh-CN/guide/main-app) - 了解更多主应用配置选项\n- [微应用](/zh-CN/guide/micro-app) - 学习如何改造现有应用\n- [最佳实践](/zh-CN/cookbook/) - 学习生产环境最佳实践 " }, { "path": "docs/zh-CN/guide/tutorial.md", "content": "# 教程\n\n本教程适合新接触 `qiankun` 的人群，从零开始介绍如何构建一个 `qiankun` 项目。\n\n## 主应用\n\n主应用不限技术栈，只需要提供一个容器 DOM，然后注册微应用并启动 qiankun 即可。\n\n首先安装 `qiankun`：\n\n```shell\n$ yarn add qiankun # 或者 npm i qiankun -S\n```\n\n注册微应用并启动：\n\n```js\nimport { registerMicroApps, start } from 'qiankun';\n\nregisterMicroApps([\n {\n name: 'angularApp',\n entry: '//localhost:4200',\n container: '#container',\n activeRule: '/app-angular',\n },\n {\n name: 'reactApp',\n entry: '//localhost:3000',\n container: '#container',\n activeRule: '/app-react',\n },\n {\n name: 'vueApp',\n entry: '//localhost:8080',\n container: '#container',\n activeRule: '/app-vue',\n },\n]);\n// 启动 qiankun\nstart();\n```\n\n## 微应用\n\n微应用分为有 `webpack` 构建和无 `webpack` 构建项目，有 `webpack` 的微应用（主要是指 Vue、React、Angular）需要做的事情有：\n\n1. 新增 `public-path.js` 文件，用于修改运行时的 `publicPath`。[什么是运行时的 publicPath？](https://webpack.js.org/guides/public-path/#on-the-fly)\n\n::: warning\n注意：运行时的 `publicPath` 和构建时的 `publicPath` 是不同的，两者不能等价替代。\n:::\n\n2. 微应用建议使用 `history` 模式的路由，需要设置路由 `base`，值和它的 `activeRule` 是一样的。\n3. 在入口文件最顶部引入 `public-path.js`，修改并导出三个生命周期函数。\n4. 修改 `webpack` 配置，在开发环境下允许跨域、并以 `umd` 格式打包。\n\n主要的修改就是以上 4 个，可能根据项目的不同情况而改变。比如，如果你的项目是 `index.html` 和其他所有文件分开部署的，说明你们已经将构建时的 `publicPath` 设置为了完整路径，则不用修改运行时的 `publicPath`（第 1 步可省略）。\n\n对于无 `webpack` 构建的微应用，只需要将生命周期函数挂载到 `window` 上即可。\n\n### React 微应用\n\n以 `create react app` 生成的 `react 16` 项目为例，搭配 `react-router-dom` 5.x。\n\n1. 在 `src` 目录新增 `public-path.js`：\n\n ```js\n if (window.__POWERED_BY_QIANKUN__) {\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n }\n ```\n\n2. 设置 `history` 模式路由的 `base`：\n\n ```html\n \n ```\n\n3. 入口文件 `index.js` 修改，为了避免根 id `#root` 与其他的 DOM 冲突，需要限制查找范围。\n\n ```js\n import './public-path';\n import React from 'react';\n import ReactDOM from 'react-dom';\n import App from './App';\n\n function render(props) {\n const { container } = props;\n ReactDOM.render(, container ? container.querySelector('#root') : document.querySelector('#root'));\n }\n\n if (!window.__POWERED_BY_QIANKUN__) {\n render({});\n }\n\n export async function bootstrap() {\n console.log('[react16] react app bootstraped');\n }\n\n export async function mount(props) {\n console.log('[react16] props from main framework', props);\n render(props);\n }\n\n export async function unmount(props) {\n const { container } = props;\n ReactDOM.unmountComponentAtNode(container ? container.querySelector('#root') : document.querySelector('#root'));\n }\n ```\n\n::: tip\n重要提示：在通过 ReactDOM.render 挂载子应用时，需要确保每个子应用都使用新的路由实例加载。\n:::\n\n4. 修改 `webpack` 配置\n\n 安装插件 `@rescripts/cli`，当然你也可以选择其他的插件，例如 `react-app-rewired`。\n\n ```bash\n npm i -D @rescripts/cli\n ```\n\n 根目录新增 `.rescriptsrc.js`：\n\n ```js\n const { name } = require('./package');\n\n module.exports = {\n webpack: (config) => {\n config.output.library = `${name}-[name]`;\n config.output.libraryTarget = 'umd';\n config.output.jsonpFunction = `webpackJsonp_${name}`;\n config.output.globalObject = 'window';\n\n return config;\n },\n\n devServer: (_) => {\n const config = _;\n\n config.headers = {\n 'Access-Control-Allow-Origin': '*',\n };\n config.historyApiFallback = true;\n config.hot = false;\n config.watchContentBase = false;\n config.liveReload = false;\n\n return config;\n },\n };\n ```\n\n 修改 `package.json`：\n\n ```diff\n - \"start\": \"react-scripts start\",\n + \"start\": \"rescripts start\",\n - \"build\": \"react-scripts build\",\n + \"build\": \"rescripts build\",\n - \"test\": \"react-scripts test\",\n + \"test\": \"rescripts test\",\n - \"eject\": \"react-scripts eject\"\n ```\n\n### React MicroApp 组件\n\n1. 安装\n\n```bash\nnpm i qiankun\nnpm i @qiankunjs/react\n```\n\n2. 使用\n\n直接通过 `` 组件加载（或卸载）子应用，该组件提供了加载和错误捕获相关能力：\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\n### Vue 微应用\n\n以 `vue-cli 3+` 生成的 `vue 2.x` 项目为例，`vue 3` 版本等稳定之后再补充。\n\n1. 在 `src` 目录新增 `public-path.js`：\n\n ```js\n if (window.__POWERED_BY_QIANKUN__) {\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n }\n ```\n\n2. 入口文件 `main.js` 修改，为了避免根 id `#app` 与其他的 DOM 冲突，需要限制查找范围。\n\n ```js\n import './public-path';\n import Vue from 'vue';\n import VueRouter from 'vue-router';\n import App from './App.vue';\n import routes from './router';\n import store from './store';\n\n Vue.config.productionTip = false;\n\n let router = null;\n let instance = null;\n function render(props = {}) {\n const { container } = props;\n router = new VueRouter({\n base: window.__POWERED_BY_QIANKUN__ ? '/app-vue/' : '/',\n mode: 'history',\n routes,\n });\n\n instance = new Vue({\n router,\n store,\n render: (h) => h(App),\n }).$mount(container ? container.querySelector('#app') : '#app');\n }\n\n // 独立运行时\n if (!window.__POWERED_BY_QIANKUN__) {\n render();\n }\n\n export async function bootstrap() {\n console.log('[vue] vue app bootstraped');\n }\n export async function mount(props) {\n console.log('[vue] props from main framework', props);\n render(props);\n }\n export async function unmount() {\n instance.$destroy();\n instance.$el.innerHTML = '';\n instance = null;\n router = null;\n }\n ```\n\n3. 修改 `webpack` 配置（`vue.config.js`）：\n\n ```js\n const { name } = require('./package');\n module.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n configureWebpack: {\n output: {\n library: `${name}-[name]`,\n libraryTarget: 'umd', // 把微应用打包成 umd 库格式\n jsonpFunction: `webpackJsonp_${name}`,\n },\n },\n };\n ```\n\n### Vue MicroApp 组件\n\n1. 安装\n\n```bash\nnpm i qiankun\nnpm i @qiankunjs/vue\n```\n\n2. 使用\n\n直接通过 `` 组件加载（或卸载）子应用，该组件提供了加载和错误捕获相关能力：\n\n```vue\n\n\n\n```\n\n### Angular 微应用\n\n以 `Angular-cli 9` 生成的 `angular 9` 项目为例，其他版本的 `angular` 后续再补充。\n\n1. 在 `src` 目录新增 `public-path.js` 文件，内容为：\n\n ```js\n if (window.__POWERED_BY_QIANKUN__) {\n // eslint-disable-next-line no-undef\n __webpack_public_path__ = window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__;\n }\n ```\n\n2. 设置 `history` 模式路由的 `base`，`src/app/app-routing.module.ts` 文件：\n\n ```diff\n + import { APP_BASE_HREF } from '@angular/common';\n\n @NgModule({\n imports: [RouterModule.forRoot(routes)],\n exports: [RouterModule],\n // @ts-ignore\n + providers: [{ provide: APP_BASE_HREF, useValue: window.__POWERED_BY_QIANKUN__ ? '/app-angular' : '/' }]\n })\n ```\n\n3. 修改入口文件，`src/main.ts` 文件：\n\n ```ts\n import './public-path';\n import { enableProdMode, NgModuleRef } from '@angular/core';\n import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';\n import { AppModule } from './app/app.module';\n import { environment } from './environments/environment';\n\n if (environment.production) {\n enableProdMode();\n }\n\n let app: void | NgModuleRef;\n async function render() {\n app = await platformBrowserDynamic()\n .bootstrapModule(AppModule)\n .catch((err) => console.error(err));\n }\n if (!(window as any).__POWERED_BY_QIANKUN__) {\n render();\n }\n\n export async function bootstrap(props: Object) {\n console.log(props);\n }\n\n export async function mount(props: Object) {\n render();\n }\n\n export async function unmount(props: Object) {\n console.log(props);\n // @ts-ignore\n app.destroy();\n }\n ```\n\n4. 修改 `webpack` 打包配置\n\n 先安装 `@angular-builders/custom-webpack` 插件，**注意：`Angular 9` 项目只能安装 `9.x` 版本，`angular 10` 项目可以安装最新版本**。\n\n ```bash\n npm i @angular-builders/custom-webpack@9.2.0 -D\n ```\n\n 根目录增加 `custom-webpack.config.js` 文件，内容为：\n\n ```js\n const appName = require('./package.json').name;\n module.exports = {\n devServer: {\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n output: {\n library: `${appName}-[name]`,\n libraryTarget: 'umd',\n jsonpFunction: `webpackJsonp_${appName}`,\n },\n };\n ```\n\n 修改 `angular.json`，将 `[项目名称] > architect > build > builder` 和 `[项目名称] > architect > serve > builder` 的值改为我们安装的插件，将我们的 webpack 配置文件加入到 `[项目名称] > architect > build > options`。\n\n ```diff\n - \"builder\": \"@angular-devkit/build-angular:browser\",\n + \"builder\": \"@angular-builders/custom-webpack:browser\",\n \"options\": {\n + \"customWebpackConfig\": {\n + \"path\": \"./custom-webpack.config.js\"\n + }\n }\n ```\n\n ```diff\n - \"builder\": \"@angular-devkit/build-angular:dev-server\",\n + \"builder\": \"@angular-builders/custom-webpack:dev-server\",\n ```\n\n5. 解决 `zone.js` 的问题\n\n 在**主应用**中导入 `zone.js`，需要在 `import qiankun` 之前导入。\n\n 将微应用的 `src/polyfills.ts` 里面的 `zone.js` 导入删除。\n\n ```diff\n - import 'zone.js/dist/zone';\n ```\n\n 在微应用的 `src/index.html` 的 `` 中加入如下内容，用于独立访问微应用时使用。\n\n ```html\n \n \n ```\n\n6. 修复 `ng build` 命令报错的问题，修改 `tsconfig.json` 文件，参考 [issues/431](https://github.com/umijs/qiankun/issues/431)。\n\n ```diff\n - \"target\": \"es2015\",\n + \"target\": \"es5\",\n + \"typeRoots\": [\n + \"node_modules/@types\"\n + ],\n ```\n\n7. 为了防止主应用或其他微应用也为 `angular` 时，`` 发生冲突，建议给 `` 加上一个唯一的 id，比如说当前应用名称。\n\n src/index.html：\n\n ```diff\n - \n + \n ```\n\n src/app/app.component.ts：\n\n ```diff\n - selector: 'app-root',\n + selector: '#angular9 app-root',\n ```\n\n当然，你也可以选择使用 `single-spa-angular` 插件，参考 [single-spa-angular 官网](https://single-spa.js.org/docs/ecosystem-angular) 和 [angular demo](https://github.com/umijs/qiankun/tree/master/examples/angular9)\n\n（**补充**）angular7 的步骤和 angular9 基本一致，除了第 4 步。angular7 修改 `webpack` 配置的步骤如下：\n\n除了安装 7.x 版本的 `angular-builders/custom-webpack` 外，还需要安装 `angular-builders/dev-server`。\n\n```bash\nnpm i @angular-builders/custom-webpack@7 -D\nnpm i @angular-builders/dev-server -D\n```\n\n根目录增加 `custom-webpack.config.js` 文件，内容同上。\n\n修改 `angular.json`，`[项目名称] > architect > build > builder` 和 Angular9 一样，`[项目名称] > architect > serve > builder` 和 Angular9 不一样。\n\n```diff\n- \"builder\": \"@angular-devkit/build-angular:browser\",\n+ \"builder\": \"@angular-builders/custom-webpack:browser\",\n \"options\": {\n+ \"customWebpackConfig\": {\n+ \"path\": \"./custom-webpack.config.js\"\n+ }\n }\n```\n\n```diff\n- \"builder\": \"@angular-devkit/build-angular:dev-server\",\n+ \"builder\": \"@angular-builders/dev-server:generic\",\n```\n\n### 无 webpack 构建的微应用\n\n一些不是由 `webpack` 构建的应用，比如 `jQuery` 应用、`jsp` 应用，都可以按照这个处理。\n\n修改前请确保你的项目里的图片、音视频等资源能够正常加载。如果这些资源的地址都是完整路径（例如 `https://qiankun.umijs.org/logo.png`），则没有问题。如果都是相对路径，需要先将这些资源上传到服务器，再引用完整路径。\n\n我们需要声明一个 script 标签，来导出相应的生命周期钩子。\n\n示例：\n\n1. 声明 entry 入口\n\n ```diff\n \n \n \n \n \n Purehtml Example\n \n \n
\n Purehtml Example\n
\n \n\n + \n \n ```\n\n2. 在 entry js 里导出生命周期\n\n ```javascript\n const render = ($) => {\n $('#purehtml-container').html('Hello, render with jQuery');\n return Promise.resolve();\n };\n\n ((global) => {\n global['purehtml'] = {\n bootstrap: () => {\n console.log('purehtml bootstrap');\n return Promise.resolve();\n },\n mount: () => {\n console.log('purehtml mount');\n return render($);\n },\n unmount: () => {\n console.log('purehtml unmount');\n return Promise.resolve();\n },\n };\n })(window);\n ```\n\n可以参考 [purehtml 例子](https://github.com/umijs/qiankun/tree/master/examples/purehtml)\n\n同时，[子应用必须支持跨域](/faq#子应用静态资源一定要支持跨域吗)\n\n### umi-qiankun 应用\n\n关于 `umi-qiankun` 的教程请前往 [umi 官网](https://umijs.org/zh-CN/plugins/plugin-qiankun) 和 [umi-qiankun 官方 demo](https://github.com/umijs/umi-plugin-qiankun/tree/master/examples) " }, { "path": "docs/zh-CN/index.md", "content": "---\nlayout: home\n\nhero:\n name: Qiankun\n text: 微前端解决方案\n tagline: 可能是你见过的最完善的微前端解决方案🧐\n image:\n src: /logo.png\n alt: Qiankun\n actions:\n - theme: brand\n text: 快速开始\n link: /zh-CN/guide/quick-start\n - theme: alt\n text: 在 GitHub 上查看\n link: https://github.com/umijs/qiankun\n\nfeatures:\n - icon: 🚀\n title: 简单\n details: 兼容任何 JavaScript 框架。构建微前端系统就像使用 iframe 一样简单，但实际上不是 iframe。\n - icon: 🛡️\n title: 完整\n details: 包含构建微前端系统所需的几乎所有基本功能，如样式隔离、JS 沙箱、预加载等。\n - icon: 🔧\n title: 生产就绪\n details: 已经过蚂蚁集团内外大量线上应用的广泛测试和打磨，健壮性值得信赖。\n - icon: ⚡\n title: 高性能\n details: 支持应用预加载，优化用户体验并提高应用切换速度。\n - icon: 🎯\n title: 技术栈无关\n details: 主应用不限制接入应用的技术栈，微应用具备完全自主权。\n - icon: 🔄\n title: 状态隔离\n details: 提供完整的 JS 沙箱机制，确保应用之间不会相互影响。\n---\n\n## 📦 安装\n\n::: code-group\n\n```bash [npm]\nnpm install qiankun\n```\n\n```bash [yarn]\nyarn add qiankun\n```\n\n```bash [pnpm]\npnpm add qiankun\n```\n\n:::\n\n## 🔨 快速开始\n\n### 主应用\n\n```typescript\nimport { registerMicroApps, start } from 'qiankun';\n\n// 注册微应用\nregisterMicroApps([\n {\n name: 'reactApp',\n entry: '//localhost:7100',\n container: '#yourContainer',\n activeRule: '/yourActiveRule',\n },\n {\n name: 'vueApp',\n entry: { scripts: ['//localhost:7100/main.js'] },\n container: '#yourContainer2',\n activeRule: '/yourActiveRule2',\n },\n]);\n\n// 启动 qiankun\nstart();\n```\n\n### 微应用\n\n```typescript\n/**\n * bootstrap 只会在微应用初始化的时候调用一次\n * mount 会在每次进入微应用时调用\n * unmount 会在每次切出/卸载微应用时调用\n */\nexport async function bootstrap() {\n console.log('react app bootstraped');\n}\n\nexport async function mount(props) {\n ReactDOM.render(, props.container ? props.container.querySelector('#root') : document.getElementById('root'));\n}\n\nexport async function unmount(props) {\n ReactDOM.unmountComponentAtNode(\n props.container ? props.container.querySelector('#root') : document.getElementById('root'),\n );\n}\n```\n\n## 🌟 为什么选择 qiankun？\n\n
\n
\n

🎯 零侵入

\n

对现有应用几乎零侵入，只需要暴露必要的生命周期函数即可

\n
\n\n
\n

📱 全场景

\n

支持基于路由的微应用加载和手动加载模式

\n
\n\n
\n

🔒 安全隔离

\n

完整的沙箱解决方案，包括 JS 隔离和 CSS 隔离

\n
\n\n
\n

⚡ 高性能

\n

支持预加载、缓存等多种性能优化方案

\n
\n
\n\n## 👥 社区\n\n| GitHub 讨论 | 钉钉群 | 微信群 |\n| --- | --- | --- |\n| [qiankun 讨论](https://github.com/umijs/qiankun/discussions) | \"钉钉群二维码\" | [查看群二维码](https://github.com/umijs/qiankun/discussions/2343) |\n\n \n" }, { "path": "examples/main/index.html", "content": "\n\n \n \n \n \n Qiankun Micro-Frontend Demo\n \n \n
\n \n \n\n" }, { "path": "examples/main/package.json", "content": "{\n \"name\": \"qiankun-main-app\",\n \"version\": \"2.0.0\",\n \"description\": \"Qiankun main application with modern tech stack\",\n \"type\": \"module\",\n \"scripts\": {\n \"dev\": \"vite\",\n \"build\": \"tsc && vite build\",\n \"preview\": \"vite preview\",\n \"lint\": \"eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0\",\n \"type-check\": \"tsc --noEmit\"\n },\n \"dependencies\": {\n \"@ant-design/icons\": \"^5.2.6\",\n \"antd\": \"^5.12.0\",\n \"clsx\": \"^2.0.0\",\n \"qiankun\": \"^3.0.0-rc.0\",\n \"react\": \"^18.2.0\",\n \"react-dom\": \"^18.2.0\",\n \"tailwind-merge\": \"^2.1.0\",\n \"zustand\": \"^4.4.7\"\n },\n \"devDependencies\": {\n \"@types/react\": \"^18.2.43\",\n \"@types/react-dom\": \"^18.2.17\",\n \"@typescript-eslint/eslint-plugin\": \"^6.14.0\",\n \"@typescript-eslint/parser\": \"^6.14.0\",\n \"@vitejs/plugin-react\": \"^4.2.1\",\n \"autoprefixer\": \"^10.4.16\",\n \"eslint\": \"^8.55.0\",\n \"eslint-plugin-react-hooks\": \"^4.6.0\",\n \"eslint-plugin-react-refresh\": \"^0.4.5\",\n \"postcss\": \"^8.4.32\",\n \"tailwindcss\": \"^3.3.6\",\n \"typescript\": \"^5.2.2\",\n \"vite\": \"^5.0.8\"\n }\n}\n" }, { "path": "examples/main/postcss.config.js", "content": "export default {\n plugins: {\n tailwindcss: {},\n autoprefixer: {},\n },\n}\n" }, { "path": "examples/main/src/App.tsx", "content": "import { useEffect } from 'react';\nimport { Layout } from 'antd';\nimport { useQiankunStore } from './store/qiankun';\nimport Sidebar from './components/Sidebar';\nimport Header from './components/Header';\nimport MicroAppContainer from './components/MicroAppContainer';\n\nconst { Content } = Layout;\n\nfunction App() {\n const { initGlobalState } = useQiankunStore();\n\n useEffect(() => {\n // Initialize qiankun global state\n initGlobalState({\n user: {\n name: 'Qiankun User',\n avatar: 'https://api.dicebear.com/7.x/avataaars/svg?seed=qiankun',\n },\n theme: 'light',\n });\n }, [initGlobalState]);\n\n return (\n \n \n \n
\n \n \n \n \n \n );\n}\n\nexport default App;\n" }, { "path": "examples/main/src/components/Dashboard.tsx", "content": "import { Row, Col, Card, Statistic, Typography, Tag, Space, Button } from 'antd';\nimport {\n AppstoreOutlined,\n ThunderboltOutlined,\n SafetyOutlined,\n GlobalOutlined,\n RocketOutlined,\n CodeOutlined,\n BranchesOutlined,\n} from '@ant-design/icons';\nimport { useQiankunStore } from '../store/qiankun';\n\nconst { Title, Text, Paragraph } = Typography;\n\nconst microApps = [\n { name: 'React', icon: '⚛️', color: '#61DAFB', status: 'active' },\n { name: 'Vue', icon: '💚', color: '#4FC08D', status: 'active' },\n { name: 'Pure HTML', icon: '🌐', color: '#E34F26', status: 'active' },\n { name: 'Vite App', icon: '⚡', color: '#646CFF', status: 'active' },\n];\n\nconst features = [\n { icon: , title: '极速加载', desc: '基于 Qiankun 的微前端架构，实现秒级应用切换' },\n { icon: , title: '沙箱隔离', desc: '完善的 JS/CSS 沙箱机制，确保应用间互不干扰' },\n { icon: , title: '技术栈无关', desc: '支持 React、Vue 等多种前端框架' },\n { icon: , title: '状态共享', desc: '内置全局状态管理，实现跨应用数据通信' },\n];\n\nexport default function Dashboard() {\n const { setActiveApp } = useQiankunStore();\n\n return (\n
\n
\n
\n
\n \n
\n
\n 欢迎使用 Qiankun\n 下一代微前端解决方案演示平台\n
\n
\n\n \n \n \n \n Qiankun 是一个基于 single-spa 的微前端实现库，旨在帮助大家能更简单、无痛的构建一个生产可用微前端架构系统。\n \n \n \n \n \n \n \n
\n
\n 4\n
\n
示例应用
\n
\n \n \n \n
\n\n \n {[\n { title: '已接入应用', value: 4, suffix: '个', color: '#0ea5e9' },\n { title: '支持框架', value: 3, suffix: '种', color: '#10b981' },\n { title: '在线用户', value: 128, suffix: '人', color: '#f59e0b' },\n { title: '系统运行', value: 99.9, suffix: '%', color: '#8b5cf6' },\n ].map((stat, index) => (\n \n \n \n \n \n ))}\n \n\n 子应用列表
} className=\"mb-8\">\n \n {microApps.slice(0, 8).map((app) => (\n \n setActiveApp(app.name.toLowerCase().replace(' ', ''))}>\n
{app.icon}
\n
{app.name}
\n {app.status === 'active' ? '运行中' : '即将上线'}\n \n \n ))}\n \n \n\n \n {features.map((feature, index) => (\n \n \n
{feature.icon}
\n
{feature.title}
\n
{feature.desc}
\n \n \n ))}\n \n
\n );\n}\n" }, { "path": "examples/main/src/components/Header.tsx", "content": "import { Layout, Button, Badge, Avatar, Dropdown, Space, Typography, Tooltip, theme } from 'antd';\nimport {\n BellOutlined,\n GithubOutlined,\n FullscreenOutlined,\n FullscreenExitOutlined,\n GlobalOutlined,\n UserOutlined,\n SettingOutlined,\n LogoutOutlined,\n} from '@ant-design/icons';\nimport { useState } from 'react';\nimport { useQiankunStore } from '../store/qiankun';\n\nconst { Header: AntHeader } = Layout;\nconst { Text } = Typography;\n\nexport default function Header() {\n const { globalState } = useQiankunStore();\n const [isFullscreen, setIsFullscreen] = useState(false);\n const { token } = theme.useToken();\n\n const toggleFullscreen = () => {\n if (!document.fullscreenElement) {\n document.documentElement.requestFullscreen();\n setIsFullscreen(true);\n } else {\n document.exitFullscreen();\n setIsFullscreen(false);\n }\n };\n\n const userMenuItems = [\n { key: 'profile', icon: , label: '个人中心' },\n { key: 'settings', icon: , label: '系统设置' },\n { type: 'divider' },\n { key: 'logout', icon: , label: '退出登录', danger: true },\n ];\n\n const notificationItems = [\n {\n key: '1',\n label: (\n
\n
React 16 应用已加载
\n
2 分钟前
\n
\n ),\n },\n {\n key: '2',\n label: (\n
\n
Vue 3 应用加载失败
\n
5 分钟前
\n
\n ),\n },\n ];\n\n return (\n \n
\n \n
\n\n \n \n \n \n\n \n }\n className=\"text-gray-500 hover:text-blue-500\"\n onClick={() => window.open('https://github.com/umijs/qiankun', '_blank')}\n />\n \n\n \n : }\n className=\"text-gray-500 hover:text-blue-500\"\n onClick={toggleFullscreen}\n />\n \n\n \n \n ,\n ,\n ]}\n />\n
\n );\n }\n\n return (\n
\n {loading && (\n
\n
\n \n

正在加载子应用...

\n
\n
\n )}\n
\n
\n );\n}\n" }, { "path": "examples/main/src/components/Sidebar.tsx", "content": "import { useState } from 'react';\nimport { Layout, Menu, Typography, Space, Tag } from 'antd';\nimport { useQiankunStore } from '../store/qiankun';\nimport {\n HomeOutlined,\n CodeOutlined,\n NodeIndexOutlined,\n ThunderboltOutlined,\n Html5Outlined,\n MenuFoldOutlined,\n MenuUnfoldOutlined,\n SettingOutlined,\n QuestionCircleOutlined,\n ExperimentOutlined,\n} from '@ant-design/icons';\n\nconst { Sider } = Layout;\nconst { Title, Text } = Typography;\n\nconst microApps = [\n { key: 'home', name: '首页', icon: , description: 'Dashboard 概览' },\n { key: 'react', name: 'React', icon: , description: 'React 18 + Vite', color: '#61DAFB' },\n { key: 'vue', name: 'Vue', icon: , description: 'Vue 3 + Vite', color: '#4FC08D' },\n { key: 'purehtml', name: 'Pure HTML', icon: , description: 'Vanilla JS', color: '#E34F26' },\n { key: 'vite', name: 'Vite App', icon: , description: 'Vite + React', color: '#646CFF' },\n];\n\nexport default function Sidebar() {\n const [collapsed, setCollapsed] = useState(false);\n const { activeApp, setActiveApp } = useQiankunStore();\n\n const handleMenuClick = (key: string) => {\n setActiveApp(key === 'home' ? null : key);\n };\n\n return (\n \n
\n \n
\n \n
\n
\n Qiankun\n Micro-Frontend\n
\n \n \n
\n\n handleMenuClick(key)}\n className=\"border-0 pt-2\"\n style={{ background: 'transparent' }}\n >\n {microApps.map((app) => (\n \n
\n {app.name}\n {app.color && !collapsed && (\n \n {app.key.includes('react') ? 'React' : app.key.includes('vue') ? 'Vue' : app.key.includes('angular') ? 'Angular' : 'Other'}\n \n )}\n
\n {!collapsed &&
{app.description}
}\n \n ))}\n \n\n {!collapsed && (\n
\n
\n \n \n \n \n v2.0.0\n
\n
\n )}\n \n );\n}\n" }, { "path": "examples/main/src/main.tsx", "content": "import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { ConfigProvider } from 'antd';\nimport App from './App';\nimport './styles/index.css';\n\n// Ant Design 主题配置\nconst antdConfig = {\n theme: {\n token: {\n colorPrimary: '#0ea5e9',\n colorSuccess: '#10b981',\n colorWarning: '#f59e0b',\n colorError: '#ef4444',\n borderRadius: 8,\n fontFamily: 'Inter, system-ui, -apple-system, sans-serif',\n },\n },\n};\n\nReactDOM.createRoot(document.getElementById('root')!).render(\n \n \n \n \n \n);\n" }, { "path": "examples/main/src/store/qiankun.ts", "content": "import { create } from 'zustand';\n\nexport interface GlobalState {\n user?: {\n name: string;\n avatar?: string;\n };\n theme?: 'light' | 'dark';\n [key: string]: any;\n}\n\ninterface QiankunStore {\n globalState: GlobalState;\n activeApp: string | null;\n loading: boolean;\n error: string | null;\n retryCount: number;\n\n // Actions\n initGlobalState: (state: GlobalState) => void;\n setGlobalState: (state: Partial) => void;\n setActiveApp: (app: string | null) => void;\n setLoading: (loading: boolean) => void;\n setError: (error: string | null) => void;\n retry: () => void;\n}\n\nexport const useQiankunStore = create((set, get) => ({\n globalState: {},\n activeApp: null,\n loading: false,\n error: null,\n retryCount: 0,\n\n initGlobalState: (state: GlobalState) => {\n set({\n globalState: state,\n });\n },\n\n setGlobalState: (state: Partial) => {\n const { globalState } = get();\n set({ globalState: { ...globalState, ...state } });\n },\n\n setActiveApp: (app: string | null) => {\n set({ activeApp: app, error: null });\n },\n\n setLoading: (loading: boolean) => {\n set({ loading });\n },\n\n setError: (error: string | null) => {\n set({ error });\n },\n\n retry: () => {\n set((state) => ({ error: null, retryCount: state.retryCount + 1 }));\n },\n}));\n" }, { "path": "examples/main/src/styles/index.css", "content": "@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n/* Custom scrollbar */\n::-webkit-scrollbar {\n width: 6px;\n height: 6px;\n}\n\n::-webkit-scrollbar-track {\n background: transparent;\n}\n\n::-webkit-scrollbar-thumb {\n background: #cbd5e1;\n border-radius: 3px;\n}\n\n::-webkit-scrollbar-thumb:hover {\n background: #94a3b8;\n}\n\n/* Smooth scrolling */\nhtml {\n scroll-behavior: smooth;\n}\n\n/* Focus outline */\n*:focus-visible {\n outline: 2px solid #3b82f6;\n outline-offset: 2px;\n}\n\n/* Micro-app container styles */\n.micro-app-container {\n min-height: calc(100vh - 64px);\n background: #f8fafc;\n}\n\n/* Loading animation */\n@keyframes spin {\n to {\n transform: rotate(360deg);\n }\n}\n\n.animate-spin {\n animation: spin 1s linear infinite;\n}\n\n/* Fade in animation */\n@keyframes fadeIn {\n from {\n opacity: 0;\n transform: translateY(10px);\n }\n to {\n opacity: 1;\n transform: translateY(0);\n }\n}\n\n.animate-fade-in {\n animation: fadeIn 0.3s ease-out forwards;\n}\n\n/* Card hover effect */\n.card-hover {\n transition: all 0.3s ease;\n}\n\n.card-hover:hover {\n transform: translateY(-2px);\n box-shadow: 0 10px 40px -10px rgba(0, 0, 0, 0.1);\n}\n" }, { "path": "examples/main/src/vite-env.d.ts", "content": "/// \n" }, { "path": "examples/main/tailwind.config.js", "content": "/** @type {import('tailwindcss').Config} */\nexport default {\n content: [\n \"./index.html\",\n \"./src/**/*.{js,ts,jsx,tsx}\",\n ],\n theme: {\n extend: {\n colors: {\n primary: {\n 50: '#f0f9ff',\n 100: '#e0f2fe',\n 200: '#bae6fd',\n 300: '#7dd3fc',\n 400: '#38bdf8',\n 500: '#0ea5e9',\n 600: '#0284c7',\n 700: '#0369a1',\n 800: '#075985',\n 900: '#0c4a6e',\n },\n secondary: {\n 50: '#fdf4ff',\n 100: '#fae8ff',\n 200: '#f5d0fe',\n 300: '#f0abfc',\n 400: '#e879f9',\n 500: '#d946ef',\n 600: '#c026d3',\n 700: '#a21caf',\n 800: '#86198f',\n 900: '#701a75',\n },\n },\n fontFamily: {\n sans: ['Inter', 'system-ui', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'Helvetica Neue', 'Arial', 'sans-serif'],\n },\n animation: {\n 'fade-in': 'fadeIn 0.5s ease-in-out',\n 'slide-in-right': 'slideInRight 0.3s ease-out',\n 'pulse-slow': 'pulse 3s cubic-bezier(0.4, 0, 0.6, 1) infinite',\n },\n keyframes: {\n fadeIn: {\n '0%': { opacity: '0' },\n '100%': { opacity: '1' },\n },\n slideInRight: {\n '0%': { transform: 'translateX(100%)', opacity: '0' },\n '100%': { transform: 'translateX(0)', opacity: '1' },\n },\n },\n },\n },\n corePlugins: {\n preflight: false,\n },\n plugins: [],\n}\n" }, { "path": "examples/main/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"ES2020\",\n \"useDefineForClassFields\": true,\n \"lib\": [\"ES2020\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ESNext\",\n \"skipLibCheck\": true,\n \"moduleResolution\": \"bundler\",\n \"allowImportingTsExtensions\": true,\n \"resolveJsonModule\": true,\n \"isolatedModules\": true,\n \"noEmit\": true,\n \"jsx\": \"react-jsx\",\n \"strict\": true,\n \"noUnusedLocals\": false,\n \"noUnusedParameters\": false,\n \"noFallthroughCasesInSwitch\": true,\n \"esModuleInterop\": true,\n \"allowSyntheticDefaultImports\": true,\n \"baseUrl\": \".\",\n \"paths\": {\n \"@/*\": [\"src/*\"]\n }\n },\n \"include\": [\"src\"],\n \"references\": [{ \"path\": \"./tsconfig.node.json\" }]\n}\n" }, { "path": "examples/main/tsconfig.node.json", "content": "{\n \"compilerOptions\": {\n \"composite\": true,\n \"skipLibCheck\": true,\n \"module\": \"ESNext\",\n \"moduleResolution\": \"bundler\",\n \"allowSyntheticDefaultImports\": true\n },\n \"include\": [\"vite.config.ts\"]\n}\n" }, { "path": "examples/main/vite.config.ts", "content": "import { defineConfig } from 'vite'\nimport react from '@vitejs/plugin-react'\nimport path from 'path'\n\n// https://vitejs.dev/config/\nexport default defineConfig({\n plugins: [react()],\n resolve: {\n alias: {\n '@': path.resolve(__dirname, './src'),\n },\n },\n server: {\n port: 7099,\n cors: true,\n },\n build: {\n outDir: 'dist',\n sourcemap: true,\n },\n})\n" }, { "path": "examples/purehtml/entry.js", "content": "const render = $ => {\n $('#purehtml-container').html('Hello, render with jQuery');\n return Promise.resolve();\n};\n\n(global => {\n global['purehtml'] = {\n bootstrap: () => {\n console.log('purehtml bootstrap');\n return Promise.resolve();\n },\n mount: () => {\n console.log('purehtml mount');\n return render($);\n },\n unmount: () => {\n console.log('purehtml unmount');\n return Promise.resolve();\n },\n };\n})(window);\n" }, { "path": "examples/purehtml/index.html", "content": "\n\n\n \n \n Purehtml Example\n \n\n\n
\n Purehtml Example\n
\n
\n \n\n\n" }, { "path": "examples/purehtml/package.json", "content": "{\n \"name\": \"purehtml\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.html\",\n \"scripts\": {\n \"start\": \"cross-env PORT=7104 http-server . --cors\",\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\"\n },\n \"author\": \"\",\n \"license\": \"MIT\",\n \"devDependencies\": {\n \"cross-env\": \"^7.0.2\",\n \"http-server\": \"^0.12.1\"\n }\n}\n" }, { "path": "examples/react/.gitignore", "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\npnpm-debug.log*\nlerna-debug.log*\n\nnode_modules\ndist\ndist-ssr\n*.local\n\n# Editor directories and files\n.vscode/*\n!.vscode/extensions.json\n.idea\n.DS_Store\n*.suo\n*.ntvs*\n*.njsproj\n*.sln\n*.sw?\n" }, { "path": "examples/react/README.md", "content": "# React + TypeScript + Vite\n\nThis template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.\n\nCurrently, two official plugins are available:\n\n- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh\n- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh\n\n## Expanding the ESLint configuration\n\nIf you are developing a production application, we recommend updating the configuration to enable type aware lint rules:\n\n- Configure the top-level `parserOptions` property like this:\n\n```js\nexport default tseslint.config({\n languageOptions: {\n // other options...\n parserOptions: {\n project: ['./tsconfig.node.json', './tsconfig.app.json'],\n tsconfigRootDir: import.meta.dirname,\n },\n },\n})\n```\n\n- Replace `tseslint.configs.recommended` to `tseslint.configs.recommendedTypeChecked` or `tseslint.configs.strictTypeChecked`\n- Optionally add `...tseslint.configs.stylisticTypeChecked`\n- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and update the config:\n\n```js\n// eslint.config.js\nimport react from 'eslint-plugin-react'\n\nexport default tseslint.config({\n // Set the react version\n settings: { react: { version: '18.3' } },\n plugins: {\n // Add the react plugin\n react,\n },\n rules: {\n // other rules...\n // Enable its recommended rules\n ...react.configs.recommended.rules,\n ...react.configs['jsx-runtime'].rules,\n },\n})\n```\n" }, { "path": "examples/react/config/qiankunHtml.ts", "content": "import type { IndexHtmlTransformContext, PluginOption } from 'vite';\nimport { load } from 'cheerio';\n\nexport default function qiankunHtmlPlugin(): PluginOption {\n return {\n name: 'qiankun-html-transform',\n enforce: 'post',\n apply: 'build',\n transformIndexHtml(html: string, ctx: IndexHtmlTransformContext) {\n if (!ctx || !isQiankunBuild(ctx)) return html;\n return transformHtml(html);\n },\n };\n}\n\nfunction isQiankunBuild(ctx: IndexHtmlTransformContext): boolean {\n return ctx.bundle !== undefined && ctx.server === undefined;\n}\n\nfunction rewriteSystemImport(script: string): string {\n const parentUrl = 'window.__POWERED_BY_QIANKUN__ ? window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__ : document.baseURI';\n \n if (script.includes(parentUrl)) {\n return script;\n }\n \n const legacyEntryPattern = \"document.getElementById('vite-legacy-entry').getAttribute('data-src')\";\n if (script.includes(legacyEntryPattern)) {\n return script.replace(\n `System.import(${legacyEntryPattern})`,\n `System.import(${legacyEntryPattern}, ${parentUrl})`\n );\n }\n \n return script;\n}\n\nfunction transformHtml(html: string): string {\n const $ = load(html);\n\n $('script[type=\"module\"]').remove();\n $('link[rel=\"modulepreload\"]').remove();\n\n $('script[nomodule]').each((_, el) => {\n const scriptContent = $(el).html();\n if (!scriptContent || !scriptContent.includes('System.import')) return;\n\n const updated = rewriteSystemImport(scriptContent);\n if (updated !== scriptContent) {\n $(el).text(updated);\n }\n });\n\n return $.html();\n}\n" }, { "path": "examples/react/eslint.config.js", "content": "import js from '@eslint/js'\nimport globals from 'globals'\nimport reactHooks from 'eslint-plugin-react-hooks'\nimport reactRefresh from 'eslint-plugin-react-refresh'\nimport tseslint from 'typescript-eslint'\n\nexport default tseslint.config(\n { ignores: ['dist'] },\n {\n extends: [js.configs.recommended, ...tseslint.configs.recommended],\n files: ['**/*.{ts,tsx}'],\n languageOptions: {\n ecmaVersion: 2020,\n globals: globals.browser,\n },\n plugins: {\n 'react-hooks': reactHooks,\n 'react-refresh': reactRefresh,\n },\n rules: {\n ...reactHooks.configs.recommended.rules,\n 'react-refresh/only-export-components': [\n 'warn',\n { allowConstantExport: true },\n ],\n },\n },\n)\n" }, { "path": "examples/react/index.html", "content": "\n\n \n \n \n \n Vite + React + TS\n \n \n
\n \n \n\n" }, { "path": "examples/react/package.json", "content": "{\n \"name\": \"react\",\n \"private\": true,\n \"version\": \"0.0.0\",\n \"type\": \"module\",\n \"scripts\": {\n \"dev\": \"vite\",\n \"build\": \"tsc -b && vite build\",\n \"lint\": \"eslint .\",\n \"preview\": \"vite preview\",\n \"build:qiankun\": \"vite build --mode qiankun\",\n \"preview:qiankun\": \"vite preview --mode qiankun\"\n },\n \"dependencies\": {\n \"@qiankunjs/react\": \"^0.0.1-rc.0\",\n \"qiankun\": \"^3.0.0-rc.0\",\n \"react\": \"^18.3.1\",\n \"react-dom\": \"^18.3.1\",\n \"vite-plugin-qiankun\": \"^1.0.15\"\n },\n \"devDependencies\": {\n \"@eslint/js\": \"^9.13.0\",\n \"@types/react\": \"^18.3.12\",\n \"@types/react-dom\": \"^18.3.1\",\n \"@vitejs/plugin-legacy\": \"^5.4.2\",\n \"@vitejs/plugin-react\": \"^4.3.3\",\n \"cheerio\": \"^1.0.0\",\n \"eslint\": \"^9.13.0\",\n \"eslint-plugin-react-hooks\": \"^5.0.0\",\n \"eslint-plugin-react-refresh\": \"^0.4.14\",\n \"globals\": \"^15.11.0\",\n \"typescript\": \"~5.6.2\",\n \"typescript-eslint\": \"^8.11.0\",\n \"vite\": \"^5.4.10\"\n }\n}\n" }, { "path": "examples/react/src/App.css", "content": "#root {\n max-width: 1280px;\n margin: 0 auto;\n padding: 2rem;\n text-align: center;\n}\n\n.logo {\n height: 6em;\n padding: 1.5em;\n will-change: filter;\n transition: filter 300ms;\n}\n.logo:hover {\n filter: drop-shadow(0 0 2em #646cffaa);\n}\n.logo.react:hover {\n filter: drop-shadow(0 0 2em #61dafbaa);\n}\n\n@keyframes logo-spin {\n from {\n transform: rotate(0deg);\n }\n to {\n transform: rotate(360deg);\n }\n}\n\n@media (prefers-reduced-motion: no-preference) {\n a:nth-of-type(2) .logo {\n animation: logo-spin infinite 20s linear;\n }\n}\n\n.card {\n padding: 2em;\n}\n\n.read-the-docs {\n color: #888;\n}\n" }, { "path": "examples/react/src/App.tsx", "content": "import { useState, version } from 'react'\nimport reactLogo from './assets/react.svg'\nimport viteLogo from '/vite.svg'\nimport './App.css'\n\nfunction App() {\n const [count, setCount] = useState(0)\n\n return (\n <>\n
\n \n \"Vite\n \n \n \"React\n \n
\n

React Micro App

\n\n
\n
\n

React Version: {version}

\n

Bundler: Vite

\n

Running in: {(window as any).__POWERED_BY_QIANKUN__ ? 'qiankun' : 'standalone'} mode

\n
\n\n \n\n

\n This React micro-app is built with modern tools and can run both standalone and inside a qiankun main app.\n

\n
\n\n

\n Generated by create-qiankun\n

\n \n )\n}\n\nexport default App\n" }, { "path": "examples/react/src/index.css", "content": ":root {\n font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;\n line-height: 1.5;\n font-weight: 400;\n\n color-scheme: light dark;\n color: rgba(255, 255, 255, 0.87);\n background-color: #242424;\n\n font-synthesis: none;\n text-rendering: optimizeLegibility;\n -webkit-font-smoothing: antialiased;\n -moz-osx-font-smoothing: grayscale;\n}\n\na {\n font-weight: 500;\n color: #646cff;\n text-decoration: inherit;\n}\na:hover {\n color: #535bf2;\n}\n\nbody {\n margin: 0;\n display: flex;\n place-items: center;\n min-width: 320px;\n min-height: 100vh;\n}\n\nh1 {\n font-size: 3.2em;\n line-height: 1.1;\n}\n\nbutton {\n border-radius: 8px;\n border: 1px solid transparent;\n padding: 0.6em 1.2em;\n font-size: 1em;\n font-weight: 500;\n font-family: inherit;\n background-color: #1a1a1a;\n cursor: pointer;\n transition: border-color 0.25s;\n}\nbutton:hover {\n border-color: #646cff;\n}\nbutton:focus,\nbutton:focus-visible {\n outline: 4px auto -webkit-focus-ring-color;\n}\n\n@media (prefers-color-scheme: light) {\n :root {\n color: #213547;\n background-color: #ffffff;\n }\n a:hover {\n color: #747bff;\n }\n button {\n background-color: #f9f9f9;\n }\n}\n" }, { "path": "examples/react/src/main.tsx", "content": "import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport App from './App';\nimport './index.css';\n\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean;\n [key: string]: unknown;\n }\n}\n\nlet root: ReactDOM.Root | undefined;\n\nfunction render(props: { container?: Element } = {}) {\n const container = props.container?.querySelector('#root') ?? document.getElementById('root');\n if (!container) return;\n\n root = ReactDOM.createRoot(container);\n root.render(\n \n \n ,\n );\n}\n\nfunction bootstrap() {\n console.log('[react] bootstrap');\n return Promise.resolve();\n}\n\nfunction mount(props: { container?: Element }) {\n console.log('[react] mount', props);\n render(props);\n return Promise.resolve();\n}\n\nfunction unmount(props: { container?: Element }) {\n console.log('[react] unmount', props);\n if (root) {\n root.unmount();\n root = undefined;\n }\n const container = props.container?.querySelector('#root') ?? document.getElementById('root');\n if (container) {\n container.innerHTML = '';\n }\n return Promise.resolve();\n}\n\n// Standalone mode\nif (!window.__POWERED_BY_QIANKUN__) {\n render();\n}\n\n// Export lifecycle functions to window - MUST be last global assignment\n(function(global) {\n global['react'] = {\n bootstrap,\n mount,\n unmount,\n };\n})(window);\n" }, { "path": "examples/react/src/vite-env.d.ts", "content": "/// \n" }, { "path": "examples/react/tsconfig.app.json", "content": "{\n \"compilerOptions\": {\n \"tsBuildInfoFile\": \"./node_modules/.tmp/tsconfig.app.tsbuildinfo\",\n \"target\": \"ES2020\",\n \"useDefineForClassFields\": true,\n \"lib\": [\"ES2020\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ESNext\",\n \"skipLibCheck\": true,\n\n /* Bundler mode */\n \"moduleResolution\": \"Bundler\",\n \"allowImportingTsExtensions\": true,\n \"isolatedModules\": true,\n \"moduleDetection\": \"force\",\n \"noEmit\": true,\n \"jsx\": \"react-jsx\",\n\n /* Linting */\n \"strict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"noUncheckedSideEffectImports\": true\n },\n \"include\": [\"src\"]\n}\n" }, { "path": "examples/react/tsconfig.json", "content": "{\n \"files\": [],\n \"references\": [\n { \"path\": \"./tsconfig.app.json\" },\n { \"path\": \"./tsconfig.node.json\" }\n ]\n}\n" }, { "path": "examples/react/tsconfig.node.json", "content": "{\n \"compilerOptions\": {\n \"tsBuildInfoFile\": \"./node_modules/.tmp/tsconfig.node.tsbuildinfo\",\n \"target\": \"ES2022\",\n \"lib\": [\"ES2023\"],\n \"module\": \"ESNext\",\n \"skipLibCheck\": true,\n\n /* Bundler mode */\n \"moduleResolution\": \"Bundler\",\n \"allowImportingTsExtensions\": true,\n \"isolatedModules\": true,\n \"moduleDetection\": \"force\",\n \"noEmit\": true,\n\n /* Linting */\n \"strict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"noUncheckedSideEffectImports\": true\n },\n \"include\": [\"vite.config.ts\"]\n}\n" }, { "path": "examples/react/vite.config.ts", "content": "import { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport legacy from '@vitejs/plugin-legacy';\nimport qiankunHtmlPlugin from './config/qiankunHtml';\nimport qiankun from 'vite-plugin-qiankun';\n\nexport default defineConfig(({ mode }) => {\n const isQiankun = mode === 'qiankun';\n\n return {\n base: isQiankun ? './' : '/',\n plugins: [\n react(),\n qiankun('react', {\n useDevMode: true\n }),\n isQiankun && legacy({ renderLegacyChunks: true }),\n isQiankun && qiankunHtmlPlugin(),\n ].filter(Boolean),\n server: {\n port: 7100,\n cors: true,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n build: {\n lib: isQiankun ? undefined : {\n entry: './src/main.tsx',\n name: 'react',\n formats: ['umd'],\n fileName: 'react'\n },\n rollupOptions: isQiankun ? undefined : {\n external: [],\n output: {\n globals: {}\n }\n }\n },\n };\n});\n" }, { "path": "examples/vite/.eslintrc.cjs", "content": "module.exports = {\n env: { browser: true, es2020: true },\n extends: [\n 'eslint:recommended',\n 'plugin:@typescript-eslint/recommended',\n 'plugin:react-hooks/recommended',\n ],\n parser: '@typescript-eslint/parser',\n parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },\n plugins: ['react-refresh'],\n rules: {\n 'react-refresh/only-export-components': 'warn',\n },\n}\n" }, { "path": "examples/vite/.gitignore", "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\npnpm-debug.log*\nlerna-debug.log*\n\nnode_modules\ndist\ndist-ssr\n*.local\n\n# Editor directories and files\n.vscode/*\n!.vscode/extensions.json\n.idea\n.DS_Store\n*.suo\n*.ntvs*\n*.njsproj\n*.sln\n*.sw?\n" }, { "path": "examples/vite/index.html", "content": "\n\n \n \n \n \n \n Vite + React + TS\n \n \n
\n \n \n\n" }, { "path": "examples/vite/package.json", "content": "{\n \"name\": \"vite-micro-app\",\n \"private\": true,\n \"version\": \"0.0.0\",\n \"type\": \"module\",\n \"scripts\": {\n \"dev\": \"vite\",\n \"build\": \"tsc && vite build\",\n \"preview\": \"vite preview\"\n },\n \"dependencies\": {\n \"react\": \"^18.2.0\",\n \"react-dom\": \"^18.2.0\"\n },\n \"devDependencies\": {\n \"@types/react\": \"^18.2.40\",\n \"@types/react-dom\": \"^18.2.17\",\n \"@vitejs/plugin-react\": \"^4.2.1\",\n \"typescript\": \"^5.2.2\",\n \"vite\": \"^5.0.8\"\n }\n}\n" }, { "path": "examples/vite/src/App.css", "content": "#root {\n max-width: 1280px;\n margin: 0 auto;\n padding: 2rem;\n text-align: center;\n}\n\n.logo {\n height: 6em;\n padding: 1.5em;\n will-change: filter;\n transition: filter 300ms;\n}\n.logo:hover {\n filter: drop-shadow(0 0 2em #646cffaa);\n}\n.logo.react:hover {\n filter: drop-shadow(0 0 2em #61dafbaa);\n}\n\n@keyframes logo-spin {\n from {\n transform: rotate(0deg);\n }\n to {\n transform: rotate(360deg);\n }\n}\n\n@media (prefers-reduced-motion: no-preference) {\n a:nth-of-type(2) .logo {\n animation: logo-spin infinite 20s linear;\n }\n}\n\n.card {\n padding: 2em;\n}\n\n.read-the-docs {\n color: #888;\n}\n" }, { "path": "examples/vite/src/App.tsx", "content": "import { useState } from 'react';\nimport reactLogo from './assets/react.svg';\nimport viteLogo from '/vite.svg';\nimport './App.css';\n\nfunction App() {\n const [count, setCount] = useState(0);\n\n return (\n <>\n
\n \n \"Vite\n \n \n \"React\n \n
\n

Vite + React

\n
\n \n

\n Edit src/App.tsx and save to test HMR\n

\n
\n

Click on the Vite and React logos to learn more

\n \n );\n}\n\nexport default App;\n" }, { "path": "examples/vite/src/index.css", "content": ":root {\n font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;\n line-height: 1.5;\n font-weight: 400;\n\n color-scheme: light dark;\n color: rgba(255, 255, 255, 0.87);\n background-color: #242424;\n\n font-synthesis: none;\n text-rendering: optimizeLegibility;\n -webkit-font-smoothing: antialiased;\n -moz-osx-font-smoothing: grayscale;\n -webkit-text-size-adjust: 100%;\n}\n\na {\n font-weight: 500;\n color: #646cff;\n text-decoration: inherit;\n}\na:hover {\n color: #535bf2;\n}\n\nbody {\n margin: 0;\n display: flex;\n place-items: center;\n min-width: 320px;\n min-height: 100vh;\n}\n\nh1 {\n font-size: 3.2em;\n line-height: 1.1;\n}\n\nbutton {\n border-radius: 8px;\n border: 1px solid transparent;\n padding: 0.6em 1.2em;\n font-size: 1em;\n font-weight: 500;\n font-family: inherit;\n background-color: #1a1a1a;\n cursor: pointer;\n transition: border-color 0.25s;\n}\nbutton:hover {\n border-color: #646cff;\n}\nbutton:focus,\nbutton:focus-visible {\n outline: 4px auto -webkit-focus-ring-color;\n}\n\n@media (prefers-color-scheme: light) {\n :root {\n color: #213547;\n background-color: #ffffff;\n }\n a:hover {\n color: #747bff;\n }\n button {\n background-color: #f9f9f9;\n }\n}\n" }, { "path": "examples/vite/src/main.tsx", "content": "import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport App from './App.tsx';\nimport './index.css';\n\nasync function bootstrap() {\n console.log('[react15] react app bootstraped');\n}\n\nconst containerMap = new WeakMap();\n\nasync function mount(props: any) {\n console.log('[react18] props from main framework', props);\n\n const container = props?.container ? props.container.querySelector('#root') : document.getElementById('root');\n const root = ReactDOM.createRoot(container);\n root.render(\n \n \n ,\n );\n\n containerMap.set(container, root);\n}\n\nasync function unmount(props: any) {\n const container = props.container ? props.container.querySelector('#root') : document.getElementById('root');\n const root = containerMap.get(container);\n root.unmount();\n}\n\n// @ts-ignore\nif (!window.__POWERED_BY_QIANKUN__) {\n bootstrap().then(mount);\n}\n\nwindow.vite = {\n bootstrap,\n mount,\n unmount,\n};\n" }, { "path": "examples/vite/src/vite-env.d.ts", "content": "/// \n" }, { "path": "examples/vite/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"target\": \"ESNext\",\n \"lib\": [\"DOM\", \"DOM.Iterable\", \"ESNext\"],\n \"module\": \"ESNext\",\n \"skipLibCheck\": true,\n\n /* Bundler mode */\n \"moduleResolution\": \"bundler\",\n \"allowImportingTsExtensions\": true,\n \"resolveJsonModule\": true,\n \"isolatedModules\": true,\n \"noEmit\": true,\n \"jsx\": \"react-jsx\",\n\n /* Linting */\n \"strict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"noFallthroughCasesInSwitch\": true\n },\n \"include\": [\"src\"],\n \"references\": [{ \"path\": \"./tsconfig.node.json\" }]\n}\n" }, { "path": "examples/vite/tsconfig.node.json", "content": "{\n \"compilerOptions\": {\n \"composite\": true,\n \"skipLibCheck\": true,\n \"module\": \"ESNext\",\n \"moduleResolution\": \"bundler\",\n \"allowSyntheticDefaultImports\": true\n },\n \"include\": [\"vite.config.ts\"]\n}\n" }, { "path": "examples/vite/vite.config.ts", "content": "import { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\n// https://vitejs.dev/config/\nexport default defineConfig({\n plugins: [react()],\n base: 'http://localhost:5173/',\n});\n" }, { "path": "examples/vue/.gitignore", "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\npnpm-debug.log*\nlerna-debug.log*\n\nnode_modules\ndist\ndist-ssr\n*.local\n\n# Editor directories and files\n.vscode/*\n!.vscode/extensions.json\n.idea\n.DS_Store\n*.suo\n*.ntvs*\n*.njsproj\n*.sln\n*.sw?\n" }, { "path": "examples/vue/README.md", "content": "# Vue 3 + TypeScript + Vite\n\nThis template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `\n \n\n" }, { "path": "examples/vue/package.json", "content": "{\n \"name\": \"vue\",\n \"private\": true,\n \"version\": \"0.0.0\",\n \"type\": \"module\",\n \"scripts\": {\n \"dev\": \"vite\",\n \"build\": \"vue-tsc -b && vite build\",\n \"preview\": \"vite preview\",\n \"build:qiankun\": \"vite build --mode qiankun\",\n \"preview:qiankun\": \"vite preview --mode qiankun\"\n },\n \"dependencies\": {\n \"vue\": \"^3.5.12\",\n \"qiankun\": \"^3.0.0-rc.0\",\n \"@qiankunjs/vue\": \"^0.0.1-rc.0\"\n },\n \"devDependencies\": {\n \"@vitejs/plugin-vue\": \"^5.1.4\",\n \"typescript\": \"~5.6.2\",\n \"vite\": \"^5.4.10\",\n \"vue-tsc\": \"^2.1.8\",\n \"@vitejs/plugin-legacy\": \"^5.4.2\",\n \"cheerio\": \"^1.0.0\"\n }\n}\n" }, { "path": "examples/vue/src/App.vue", "content": "\n\n\n\n\n" }, { "path": "examples/vue/src/components/HelloWorld.vue", "content": "\n\n\n\n\n" }, { "path": "examples/vue/src/main.ts", "content": "import { createApp } from 'vue';\nimport App from './App.vue';\nimport './style.css';\n\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean;\n [key: string]: unknown;\n }\n}\n\nlet app: ReturnType | undefined;\n\nfunction render(props: { container?: Element } = {}) {\n const container = props.container?.querySelector('#app') ?? document.getElementById('app');\n if (!container) return;\n\n app = createApp(App);\n app.mount(container);\n}\n\nfunction bootstrap() {\n console.log('[vue] bootstrap');\n return Promise.resolve();\n}\n\nfunction mount(props: { container?: Element }) {\n console.log('[vue] mount', props);\n render(props);\n return Promise.resolve();\n}\n\nfunction unmount(props: { container?: Element }) {\n console.log('[vue] unmount', props);\n if (app) {\n app.unmount();\n app = undefined;\n }\n const container = props.container?.querySelector('#app') ?? document.getElementById('app');\n if (container) {\n container.innerHTML = '';\n }\n return Promise.resolve();\n}\n\n// Export lifecycle functions to window immediately\n(function(global) {\n global['vue'] = {\n bootstrap,\n mount,\n unmount,\n };\n})(window);\n\n// Standalone mode\nif (!window.__POWERED_BY_QIANKUN__) {\n render();\n}\n" }, { "path": "examples/vue/src/style.css", "content": ":root {\n font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;\n line-height: 1.5;\n font-weight: 400;\n\n color-scheme: light dark;\n color: rgba(255, 255, 255, 0.87);\n background-color: #242424;\n\n font-synthesis: none;\n text-rendering: optimizeLegibility;\n -webkit-font-smoothing: antialiased;\n -moz-osx-font-smoothing: grayscale;\n}\n\na {\n font-weight: 500;\n color: #646cff;\n text-decoration: inherit;\n}\na:hover {\n color: #535bf2;\n}\n\nbody {\n margin: 0;\n display: flex;\n place-items: center;\n min-width: 320px;\n min-height: 100vh;\n}\n\nh1 {\n font-size: 3.2em;\n line-height: 1.1;\n}\n\nbutton {\n border-radius: 8px;\n border: 1px solid transparent;\n padding: 0.6em 1.2em;\n font-size: 1em;\n font-weight: 500;\n font-family: inherit;\n background-color: #1a1a1a;\n cursor: pointer;\n transition: border-color 0.25s;\n}\nbutton:hover {\n border-color: #646cff;\n}\nbutton:focus,\nbutton:focus-visible {\n outline: 4px auto -webkit-focus-ring-color;\n}\n\n.card {\n padding: 2em;\n}\n\n#app {\n max-width: 1280px;\n margin: 0 auto;\n padding: 2rem;\n text-align: center;\n}\n\n@media (prefers-color-scheme: light) {\n :root {\n color: #213547;\n background-color: #ffffff;\n }\n a:hover {\n color: #747bff;\n }\n button {\n background-color: #f9f9f9;\n }\n}\n" }, { "path": "examples/vue/src/vite-env.d.ts", "content": "/// \n" }, { "path": "examples/vue/tsconfig.app.json", "content": "{\n \"compilerOptions\": {\n \"tsBuildInfoFile\": \"./node_modules/.tmp/tsconfig.app.tsbuildinfo\",\n \"target\": \"ES2020\",\n \"useDefineForClassFields\": true,\n \"module\": \"ESNext\",\n \"lib\": [\"ES2020\", \"DOM\", \"DOM.Iterable\"],\n \"skipLibCheck\": true,\n\n /* Bundler mode */\n \"moduleResolution\": \"Bundler\",\n \"allowImportingTsExtensions\": true,\n \"isolatedModules\": true,\n \"moduleDetection\": \"force\",\n \"noEmit\": true,\n \"jsx\": \"preserve\",\n\n /* Linting */\n \"strict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"noUncheckedSideEffectImports\": true\n },\n \"include\": [\"src/**/*.ts\", \"src/**/*.tsx\", \"src/**/*.vue\"]\n}\n" }, { "path": "examples/vue/tsconfig.json", "content": "{\n \"files\": [],\n \"references\": [\n { \"path\": \"./tsconfig.app.json\" },\n { \"path\": \"./tsconfig.node.json\" }\n ]\n}\n" }, { "path": "examples/vue/tsconfig.node.json", "content": "{\n \"compilerOptions\": {\n \"tsBuildInfoFile\": \"./node_modules/.tmp/tsconfig.node.tsbuildinfo\",\n \"target\": \"ES2022\",\n \"lib\": [\"ES2023\"],\n \"module\": \"ESNext\",\n \"skipLibCheck\": true,\n\n /* Bundler mode */\n \"moduleResolution\": \"Bundler\",\n \"allowImportingTsExtensions\": true,\n \"isolatedModules\": true,\n \"moduleDetection\": \"force\",\n \"noEmit\": true,\n\n /* Linting */\n \"strict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"noUncheckedSideEffectImports\": true\n },\n \"include\": [\"vite.config.ts\"]\n}\n" }, { "path": "examples/vue/vite.config.ts", "content": "import { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\nimport legacy from '@vitejs/plugin-legacy';\nimport qiankunHtmlPlugin from './config/qiankunHtml';\n\nexport default defineConfig(({ mode }) => {\n const isQiankun = mode === 'qiankun';\n\n return {\n base: isQiankun ? './' : '/',\n plugins: [\n vue(),\n isQiankun && legacy({ renderLegacyChunks: true }),\n isQiankun && qiankunHtmlPlugin(),\n ].filter(Boolean),\n server: {\n port: 7101,\n cors: true,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n };\n});\n" }, { "path": "package.json", "content": "{\n \"name\": \"qiankun-monorepo\",\n \"private\": true,\n \"engines\": {\n \"node\": \">=16\"\n },\n \"scripts\": {\n \"start:example\": \"pnpm run build && npm run start:main\",\n \"start:main\": \"cd ./examples/main && npm run dev\",\n \"build\": \"pnpm -r run build\",\n \"prerelease:alpha\": \"changeset pre enter alpha && changeset && changeset version\",\n \"release:alpha\": \"pnpm run build && changeset publish && changeset pre exit\",\n \"eslint\": \"eslint packages/\",\n \"prettier\": \"prettier --write .\",\n \"prettier:check\": \"prettier -c .\",\n \"docs:dev\": \"vitepress dev docs\",\n \"docs:build\": \"vitepress build docs\",\n \"docs:preview\": \"vitepress preview docs\",\n \"ci\": \"pnpm run build && pnpm run eslint && pnpm run prettier:check\",\n \"ci:publish\": \"changeset publish\",\n \"test\": \"pnpm -r run test\",\n \"prepare\": \"husky install\",\n \"clean\": \"rimraf node_modules **/*/node_modules\"\n },\n \"devDependencies\": {\n \"@changesets/cli\": \"^2.29.8\",\n \"@commitlint/cli\": \"^20.4.1\",\n \"@commitlint/config-conventional\": \"^20.4.1\",\n \"@edge-runtime/vm\": \"^3.2.0\",\n \"@types/lodash\": \"^4.17.23\",\n \"@types/node\": \"^18.19.130\",\n \"@typescript-eslint/eslint-plugin\": \"^6.21.0\",\n \"@typescript-eslint/parser\": \"^6.21.0\",\n \"babel-plugin-import\": \"^1.13.8\",\n \"cross-env\": \"^7.0.3\",\n \"eslint\": \"^8.57.1\",\n \"eslint-config-prettier\": \"^9.1.2\",\n \"eslint-formatter-pretty\": \"^5.0.0\",\n \"father\": \"^4.6.13\",\n \"happy-dom\": \"^12.10.3\",\n \"husky\": \"^8.0.3\",\n \"lint-staged\": \"^9.5.0\",\n \"mermaid\": \"^11.12.2\",\n \"prettier\": \"^3.8.1\",\n \"rimraf\": \"^3.0.2\",\n \"typescript\": \"^5.9.3\",\n \"vitepress\": \"^1.6.4\",\n \"vitest\": \"^0.34.6\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/umijs/qiankun.git\"\n },\n \"license\": \"MIT\",\n \"bugs\": {\n \"url\": \"https://github.com/umijs/qiankun/issues\"\n },\n \"homepage\": \"https://github.com/umijs/qiankun#readme\",\n \"lint-staged\": {\n \"**/*.{js,ts,json,css,md}\": [\"prettier --write --ignore-unknown\"],\n \"packages/*/{src,types}/**/*.ts\": [\"eslint --cache --ext .js,.jsx,.ts,.tsx --format=pretty --fix\"],\n \"packages/**/*.d.ts\": [\"eslint --ext .ts\"]\n },\n \"packageManager\": \"pnpm@10.28.2\",\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\"\n }\n}\n" }, { "path": "packages/bundler-plugin/.fatherrc.js", "content": "export { default } from '../../.fatherrc.cjs';\n" }, { "path": "packages/bundler-plugin/CHANGELOG.md", "content": "# @qiankunjs/webpack-plugin\n\n## 0.0.1-rc.1\n\n### Patch Changes\n\n- fa128ee: fix: improve QiankunPlugin webpack compatibility and error handling\n\n## 0.0.1-rc.4\n\n### Patch Changes\n\n- 35f7863: fix: move cheerio to dependencies\n\n## 0.0.1-rc.3\n\n### Patch Changes\n\n- b7ec9e79: fix: correct entry script identification and webpack version detection in Vue CLI 5\n\n## 0.0.1-rc.2\n\n### Patch Changes\n\n- cb1bd997: fix(webpack-plugin):fix webpack module not found during webpack-plugin build\n" }, { "path": "packages/bundler-plugin/README-zh.md", "content": "# @qiankunjs/bundler-plugin\n\n`@qiankunjs/bundler-plugin` 是为 [qiankun](https://github.com/umijs/qiankun) 微前端框架设计的打包工具插件集。当前支持 Webpack (4 & 5)，未来计划支持 Vite、Turbopack 等其他打包工具。\n\n## 安装\n\n使用 npm:\n\n```bash\nnpm install @qiankunjs/bundler-plugin --save-dev\n```\n\n或使用 yarn:\n\n```bash\nyarn add @qiankunjs/bundler-plugin --dev\n```\n\n## Webpack 插件\n\n### 功能\n\n- 自动设置输出库的名称和格式\n- 确保 `jsonpFunction`/`chunkLoadingGlobal` 名称的唯一性\n- 设置全局对象为 `window`，确保库可以在浏览器中运行\n- 自动为 HTML 中的入口 script 标签加上 entry 标记\n- 同时支持 Webpack 4 和 Webpack 5\n\n### 使用\n\n在您的 `webpack.config.js` 或其他配置文件中：\n\n```javascript\nconst { QiankunWebpackPlugin } = require('@qiankunjs/bundler-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunWebpackPlugin({\n packageName: 'optionalPackageName',\n }),\n ],\n};\n```\n\n### 选项\n\n- `packageName`: 指定输出库的名称。如果未提供，将使用 `package.json` 中的名称。\n\n### 入口脚本检测\n\n插件会自动检测并标记 HTML 中的入口脚本：\n\n1. 使用 webpack 的 `compilation.entrypoints` API 识别入口 chunk\n2. 单入口构建：标记主入口 chunk 的脚本\n3. 多入口构建：根据 HTML 文件名匹配对应的 entrypoint\n4. 如果自动检测失败，回退到最后一个 script 标签\n\n## 贡献\n\n欢迎任何形式的贡献！请提交 PR 或开启 issue 讨论。\n\n## 许可证\n\nMIT\n" }, { "path": "packages/bundler-plugin/README.md", "content": "# @qiankunjs/bundler-plugin\n\nBundler plugins for the [qiankun](https://github.com/umijs/qiankun) micro-frontend framework. Currently supports Webpack (4 & 5), with plans to support other bundlers like Vite and Turbopack in the future.\n\n## Installation\n\nUsing npm:\n\n```bash\nnpm install @qiankunjs/bundler-plugin --save-dev\n```\n\nOr using yarn:\n\n```bash\nyarn add @qiankunjs/bundler-plugin --dev\n```\n\n## Webpack Plugin\n\n### Features\n\n- Automatically sets the name and format of the output library\n- Ensures the uniqueness of the `jsonpFunction`/`chunkLoadingGlobal` name\n- Sets the global object to `window`, ensuring the library can run in the browser\n- Automatically adds an entry marker to the entry script tag in HTML\n- Supports both Webpack 4 and Webpack 5\n\n### Usage\n\nIn your `webpack.config.js` or other configuration files:\n\n```javascript\nconst { QiankunWebpackPlugin } = require('@qiankunjs/bundler-plugin');\n\nmodule.exports = {\n plugins: [\n new QiankunWebpackPlugin({\n packageName: 'optionalPackageName',\n }),\n ],\n};\n```\n\n### Options\n\n- `packageName`: Specifies the name of the output library. If not provided, the name from `package.json` will be used.\n\n### Entry Script Detection\n\nThe plugin automatically detects and marks the entry script in your HTML:\n\n1. Uses webpack's `compilation.entrypoints` API to identify entry chunks\n2. For single entry builds: marks the main entry chunk's script\n3. For multi-entry builds: matches HTML filename to entrypoint name\n4. Falls back to the last script tag if automatic detection fails\n\n## Contributing\n\nAny form of contribution is welcome! Please submit PRs or open issues for discussion.\n\n## License\n\nMIT\n" }, { "path": "packages/bundler-plugin/package.json", "content": "{\n \"name\": \"@qiankunjs/bundler-plugin\",\n \"version\": \"0.0.1-rc.1\",\n \"description\": \"Bundler plugins for qiankun micro-frontend framework\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/umijs/qiankun.git\"\n },\n \"main\": \"./dist/cjs/index.js\",\n \"module\": \"./dist/esm/index.js\",\n \"types\": \"./dist/esm/index.d.ts\",\n \"exports\": {\n \".\": {\n \"import\": \"./dist/esm/index.js\",\n \"require\": \"./dist/cjs/index.js\",\n \"types\": \"./dist/esm/index.d.ts\"\n },\n \"./webpack\": {\n \"import\": \"./dist/esm/webpack/index.js\",\n \"require\": \"./dist/cjs/webpack/index.js\",\n \"types\": \"./dist/esm/webpack/index.d.ts\"\n }\n },\n \"scripts\": {\n \"build:webpack4\": \"cd ./tests/webpack4 && npm install && pnpm run build\",\n \"build:webpack5\": \"cd ./tests/webpack5 && npm install && pnpm run build\",\n \"test\": \"pnpm run build && pnpm run build:webpack4 && pnpm run build:webpack5 && vitest --run\",\n \"build\": \"father build\"\n },\n \"files\": [\n \"dist\"\n ],\n \"peerDependencies\": {\n \"webpack\": \"^4.0.0 || ^5.0.0\"\n },\n \"peerDependenciesMeta\": {\n \"webpack\": {\n \"optional\": true\n }\n },\n \"author\": \"Hermanna\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"webpack-sources\": \"^3.2.3\",\n \"cheerio\": \"^1.0.0-rc.12\"\n },\n \"devDependencies\": {\n \"@types/webpack-sources\": \"^3.2.1\",\n \"webpack\": \"^5.0.0\"\n }\n}\n" }, { "path": "packages/bundler-plugin/src/index.ts", "content": "export { QiankunWebpackPlugin, type QiankunWebpackPluginOptions } from './webpack';\nexport { QiankunWebpackPlugin as default } from './webpack';\n" }, { "path": "packages/bundler-plugin/src/webpack/index.ts", "content": "import * as fs from 'fs';\nimport * as path from 'path';\nimport type { Compiler, Compilation } from 'webpack';\n\nexport interface QiankunWebpackPluginOptions {\n packageName?: string;\n}\n\ninterface Chunk {\n files: Iterable | undefined;\n hasRuntime?: () => boolean;\n}\n\ninterface Entrypoint {\n chunks: Chunk[] | undefined;\n getEntrypointChunk?: () => Chunk;\n getFiles?: () => string[];\n}\n\ninterface PackageJson {\n name?: string;\n}\n\ninterface HtmlTagObject {\n tagName: string;\n voidTag: boolean;\n attributes: Record;\n innerHTML?: string;\n meta?: Record;\n}\n\ninterface HtmlWebpackPluginData {\n assetTags: {\n scripts: HtmlTagObject[];\n styles: HtmlTagObject[];\n meta: HtmlTagObject[];\n };\n outputName: string;\n publicPath: string;\n plugin: unknown;\n}\n\ninterface HtmlWebpackPluginHooks {\n alterAssetTags: {\n tapAsync: (\n name: string,\n callback: (data: HtmlWebpackPluginData, cb: (err: Error | null, data: HtmlWebpackPluginData) => void) => void,\n ) => void;\n };\n}\n\ninterface HtmlWebpackPluginStatic {\n getHooks(compilation: Compilation): HtmlWebpackPluginHooks;\n}\n\nexport class QiankunWebpackPlugin {\n private readonly packageName: string;\n\n private static cachedPackageJson: PackageJson | null = null;\n\n constructor(options: QiankunWebpackPluginOptions = {}) {\n this.packageName = options.packageName || QiankunWebpackPlugin.getPackageName();\n }\n\n private static getPackageName(): string {\n if (!QiankunWebpackPlugin.cachedPackageJson) {\n const packageJsonPath = path.join(process.cwd(), 'package.json');\n try {\n const content = fs.readFileSync(packageJsonPath, 'utf-8');\n QiankunWebpackPlugin.cachedPackageJson = JSON.parse(content) as PackageJson;\n } catch {\n QiankunWebpackPlugin.cachedPackageJson = {};\n }\n }\n return QiankunWebpackPlugin.cachedPackageJson.name || '';\n }\n\n apply(compiler: Compiler): void {\n this.configureOutput(compiler);\n this.registerHtmlProcessing(compiler);\n }\n\n private configureOutput(compiler: Compiler): void {\n const output = compiler.options.output;\n // webpack 4 doesn't have compiler.webpack, use it for version detection\n const webpack = (compiler as unknown as { webpack?: { version?: string } }).webpack;\n const isWebpack5 = webpack?.version?.startsWith('5');\n\n if (isWebpack5) {\n output.library = {\n name: this.packageName,\n type: 'window',\n };\n } else {\n // @ts-expect-error webpack 4 specific options\n output.library = this.packageName;\n // @ts-expect-error webpack 4 specific options\n output.libraryTarget = 'window';\n // @ts-expect-error webpack 4 specific options\n output.jsonpFunction = `webpackJsonp_${this.packageName}`;\n output.globalObject = 'window';\n }\n }\n\n private registerHtmlProcessing(compiler: Compiler): void {\n compiler.hooks.compilation.tap('QiankunWebpackPlugin', (compilation: Compilation) => {\n const HtmlWebpackPlugin = this.findHtmlWebpackPlugin(compiler);\n\n if (HtmlWebpackPlugin) {\n this.hookIntoHtmlWebpackPlugin(compilation, HtmlWebpackPlugin);\n }\n });\n }\n\n private findHtmlWebpackPlugin(compiler: Compiler): HtmlWebpackPluginStatic | null {\n const plugins = (compiler.options as unknown as { plugins?: unknown[] }).plugins ?? [];\n\n for (const plugin of plugins) {\n const ctor = (plugin as { constructor?: HtmlWebpackPluginStatic } | null)?.constructor;\n if (ctor && typeof ctor.getHooks === 'function') {\n return ctor;\n }\n }\n\n return null;\n }\n\n private hookIntoHtmlWebpackPlugin(compilation: Compilation, HtmlWebpackPlugin: HtmlWebpackPluginStatic): void {\n const hooks = HtmlWebpackPlugin.getHooks(compilation);\n\n hooks.alterAssetTags.tapAsync('QiankunWebpackPlugin', (data, callback) => {\n const scripts = data.assetTags.scripts;\n\n if (scripts.length === 0) {\n callback(null, data);\n return;\n }\n\n const hasEntry = scripts.some((script) => 'entry' in script.attributes);\n if (hasEntry) {\n callback(null, data);\n return;\n }\n\n const entryScriptSrc = this.findEntryScriptSrc(compilation, data.outputName);\n\n let marked = false;\n if (entryScriptSrc) {\n const entryScript = scripts.find((script) => {\n const src = script.attributes.src;\n return typeof src === 'string' && this.matchEntryScript(src, entryScriptSrc);\n });\n\n if (entryScript) {\n entryScript.attributes.entry = true;\n marked = true;\n }\n }\n\n if (!marked) {\n scripts[scripts.length - 1].attributes.entry = true;\n }\n\n callback(null, data);\n });\n }\n\n private findEntryScriptSrc(compilation: Compilation, htmlOutputName: string): string | null {\n const entrypoints = compilation.entrypoints as Map | undefined;\n if (!entrypoints || entrypoints.size === 0) {\n return null;\n }\n\n // For single entry, use the only entrypoint\n if (entrypoints.size === 1) {\n const entrypoint = entrypoints.values().next().value as Entrypoint;\n return this.getEntryChunkFile(entrypoint);\n }\n\n // For multiple entries, try to match by HTML filename\n const htmlBaseName = path.basename(htmlOutputName, '.html');\n const matchedEntrypoint = entrypoints.get(htmlBaseName);\n if (matchedEntrypoint) {\n return this.getEntryChunkFile(matchedEntrypoint);\n }\n\n // Fallback: use the first entrypoint\n const firstEntrypoint = entrypoints.values().next().value as Entrypoint;\n return this.getEntryChunkFile(firstEntrypoint);\n }\n\n private getEntryChunkFile(entrypoint: Entrypoint): string | null {\n // Webpack 5: getEntrypointChunk returns the main chunk\n if (typeof entrypoint.getEntrypointChunk === 'function') {\n const chunk = entrypoint.getEntrypointChunk();\n const files = chunk.files;\n if (files) {\n for (const file of files) {\n if (file.endsWith('.js')) {\n return file;\n }\n }\n }\n }\n\n // Webpack 4/5 fallback: iterate chunks to find the one with runtime or entry modules\n const chunks = entrypoint.chunks;\n if (chunks) {\n for (let i = chunks.length - 1; i >= 0; i--) {\n const chunk = chunks[i];\n // In code-split scenarios, the entry chunk usually has runtime\n if (chunk.hasRuntime?.() || i === chunks.length - 1) {\n const files = Array.from(chunk.files ?? []);\n for (const file of files) {\n if (file.endsWith('.js')) {\n return file;\n }\n }\n }\n }\n }\n\n // Last resort: get files from entrypoint\n const allFiles = entrypoint.getFiles?.() || [];\n for (const file of allFiles) {\n if (file.endsWith('.js')) {\n return file;\n }\n }\n\n return null;\n }\n\n private matchEntryScript(scriptSrc: string, entryFile: string): boolean {\n // Handle both absolute and relative paths\n const normalizedSrc = scriptSrc.replace(/^\\//, '');\n const normalizedEntry = entryFile.replace(/^\\//, '');\n\n return (\n normalizedSrc === normalizedEntry ||\n normalizedSrc.endsWith('/' + normalizedEntry) ||\n normalizedSrc.endsWith(normalizedEntry)\n );\n }\n}\n\nexport default QiankunWebpackPlugin;\n" }, { "path": "packages/bundler-plugin/tests/fixtures/webpack4.html", "content": "\n\n \n \n \n Webpack Test\n \n \n
\n \n \n \n\n" }, { "path": "packages/bundler-plugin/tests/fixtures/webpack5.html", "content": "\n\n \n \n \n Webpack Test\n \n \n
\n \n \n \n\n" }, { "path": "packages/bundler-plugin/tests/plugin.test.ts", "content": "import * as fs from 'fs';\nimport * as path from 'path';\nimport { describe, expect, it } from 'vitest';\nimport { load as cheerioLoad } from 'cheerio';\n\nfunction normalizeHtml(html: string): string {\n const $ = cheerioLoad(html);\n $('body')\n .contents()\n // eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison -- cheerio's AnyNode has ElementType enum\n .filter((_, el) => el.type === 'text' && !(el as unknown as { data: string }).data.trim())\n .remove();\n return $.html();\n}\n\nfunction readFixture(name: string): string {\n return fs.readFileSync(path.join(__dirname, 'fixtures', `${name}.html`), 'utf-8');\n}\n\ndescribe('QiankunWebpackPlugin', () => {\n describe('integration tests', () => {\n it('should generate expected HTML for webpack 4', () => {\n const actual = normalizeHtml(fs.readFileSync(path.join(__dirname, 'webpack4/dist/index.html'), 'utf-8'));\n const expected = normalizeHtml(readFixture('webpack4'));\n expect(actual).toBe(expected);\n });\n\n it('should generate expected HTML for webpack 5', () => {\n const actual = normalizeHtml(fs.readFileSync(path.join(__dirname, 'webpack5/dist/index.html'), 'utf-8'));\n const expected = normalizeHtml(readFixture('webpack5'));\n expect(actual).toBe(expected);\n });\n });\n});\n" }, { "path": "packages/bundler-plugin/tests/webpack4/.eslintrc.js", "content": "module.exports = {\n env: {\n node: true,\n commonjs: true,\n },\n};\n" }, { "path": "packages/bundler-plugin/tests/webpack4/index.html", "content": "\n\n \n \n \n Webpack Test\n \n \n
\n \n \n\n" }, { "path": "packages/bundler-plugin/tests/webpack4/index.js", "content": "console.log('Hello from test demo!');\n" }, { "path": "packages/bundler-plugin/tests/webpack4/package.json", "content": "{\n \"name\": \"webpack4\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\": {\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\",\n \"build\": \"webpack\"\n },\n \"keywords\": [],\n \"author\": \"\",\n \"license\": \"ISC\",\n \"devDependencies\": {\n \"html-webpack-plugin\": \"^4.5.2\",\n \"webpack\": \"4\",\n \"webpack-cli\": \"4\"\n }\n}\n" }, { "path": "packages/bundler-plugin/tests/webpack4/webpack.config.js", "content": "const path = require('path');\nconst { QiankunWebpackPlugin } = require('../../dist/cjs');\nconst HtmlWebpackPlugin = require('html-webpack-plugin');\n\nmodule.exports = {\n entry: './index.js',\n output: {\n filename: 'bundle.js',\n path: path.resolve(__dirname, 'dist'),\n },\n mode: 'development',\n plugins: [\n new HtmlWebpackPlugin({\n template: './index.html',\n filename: 'index.html',\n }),\n new QiankunWebpackPlugin(),\n ],\n};\n" }, { "path": "packages/bundler-plugin/tests/webpack5/.eslintrc.js", "content": "module.exports = {\n env: {\n node: true,\n commonjs: true,\n },\n};\n" }, { "path": "packages/bundler-plugin/tests/webpack5/index.html", "content": "\n\n \n \n \n Webpack Test\n \n \n
\n \n \n\n" }, { "path": "packages/bundler-plugin/tests/webpack5/index.js", "content": "console.log('Hello from test demo!');\n" }, { "path": "packages/bundler-plugin/tests/webpack5/package.json", "content": "{\n \"name\": \"webpack5\",\n \"version\": \"1.0.0\",\n \"description\": \"\",\n \"main\": \"index.js\",\n \"scripts\": {\n \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\",\n \"build\": \"webpack\"\n },\n \"keywords\": [],\n \"author\": \"\",\n \"license\": \"ISC\",\n \"devDependencies\": {\n \"html-webpack-plugin\": \"^5.5.3\",\n \"webpack\": \"5\",\n \"webpack-cli\": \"5\"\n }\n}\n" }, { "path": "packages/bundler-plugin/tests/webpack5/webpack.config.js", "content": "const path = require('path');\nconst { QiankunWebpackPlugin } = require('../../dist/cjs');\nconst HtmlWebpackPlugin = require('html-webpack-plugin');\n\nmodule.exports = {\n entry: './index.js',\n output: {\n filename: 'bundle.js',\n path: path.resolve(__dirname, 'dist'),\n },\n mode: 'development',\n plugins: [\n new HtmlWebpackPlugin({\n template: './index.html',\n filename: 'index.html',\n scriptLoading: 'blocking',\n }),\n new QiankunWebpackPlugin(),\n ],\n};\n" }, { "path": "packages/create-qiankun/.fatherrc.js", "content": "export default {\n platform: 'node',\n cjs: {\n input: 'src',\n output: 'dist',\n },\n};\n" }, { "path": "packages/create-qiankun/CHANGELOG.md", "content": "# create-qiankun\n\n## 0.0.1-rc.2\n\n### Patch Changes\n\n- fa128ee: fix: improve QiankunPlugin webpack compatibility and error handling\n- 466c9c2: feat: refactor create-qiankun cli\n\n## 0.0.1-rc.1\n\n### Patch Changes\n\n- fb91153: fix: include template to publish field\n\n## 0.1.0-rc.0\n\n### Patch Changes\n\n- 4c7a773: feat: introduce qiankun scaffold\n" }, { "path": "packages/create-qiankun/Readme.md", "content": "# @qiankunjs/create-qiankun\n\n`@qiankunjs/create-qiankun` 是一个为 [qiankun](https://github.com/umijs/qiankun) 微前端框架设计的脚手架功能。旨在快速启动示例项目，方便开发者快速上手。\n\n## 功能\n\n- 支持选择一个或多个子应用来创建一个新的项目\n- 支持主,子应用路由模式 `(hash, history)` 选择\n- 支持一键生成 `npm/yarn/pnpm/pnpm workspace` 工程\n- 注入启动应用脚本以及端口冲突检测\n\n## 环境要求\n\n1. 建议使用 Node.js 版本 v18 或更高版本。,推荐使用 [fnm](https://github.com/Schniz/fnm) 管理 node 版本\n\n## 安装\n\n使用 npm:\n\n```bash\nnpx create-qiankun@latest\n```\n\n或使用 yarn:\n\n```bash\nyarn create qiankun@latest\n```\n\n或使用 pnpm:\n\n```bash\npnpm dlx create-qiankun@latest\n```\n\n## 使用\n\n## 模板列表\n\n### 主应用模板\n\n| 模板名称 | |\n| --------------- | --- |\n| React18+Webpack | |\n| Vue3+Webpack | |\n| React18+umi | |\n\n### 子应用模板\n\n| 模板名称 | |\n| --------------- | --------------------------- |\n| React18+Webpack | |\n| React16+Webpack | |\n| Vue3+Webpack | |\n| Vue2+Webpack | ❗ 在 pnpm workspace 有问题 |\n| Vite+Vue3 | 🚧 建设中 |\n| Vite+React18 | 🚧 建设中 |\n\n## 贡献\n\n欢迎任何形式的贡献！请提交 PR 或开启 issue 讨论。\n\n## 许可证\n\nMIT\n" }, { "path": "packages/create-qiankun/package.json", "content": "{\n \"name\": \"create-qiankun\",\n \"version\": \"0.0.1-rc.2\",\n \"description\": \"An easy way to start a qiankun sub-app with Vite\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/umijs/qiankun.git\"\n },\n \"bin\": {\n \"create-qiankun\": \"./dist/index.js\"\n },\n \"main\": \"./dist/index.js\",\n \"scripts\": {\n \"dev\": \"father dev\",\n \"build\": \"father build\",\n \"test\": \"vitest run\",\n \"test:e2e\": \"vitest run --config vitest.e2e.config.ts\"\n },\n \"files\": [\n \"dist\"\n ],\n \"keywords\": [\n \"qiankun\",\n \"micro-frontend\",\n \"vite\",\n \"scaffold\"\n ],\n \"author\": \"\",\n \"license\": \"ISC\",\n \"dependencies\": {\n \"create-vite\": \"^5.2.0\",\n \"execa\": \"^5.1.1\",\n \"fs-extra\": \"^10.1.0\",\n \"kolorist\": \"^1.8.0\",\n \"minimist\": \"^1.2.6\",\n \"prompts\": \"^2.4.2\"\n },\n \"devDependencies\": {\n \"@types/fs-extra\": \"^11.0.2\",\n \"@types/minimist\": \"^1.2.3\",\n \"@types/prompts\": \"^2.4.4\",\n \"cheerio\": \"^1.0.0\",\n \"vitest\": \"^0.34.6\"\n }\n}\n" }, { "path": "packages/create-qiankun/src/index.ts", "content": "#!/usr/bin/env node\n\nimport prompts from 'prompts';\nimport { green, red, bold } from 'kolorist';\nimport path from 'node:path';\nimport minimist from 'minimist';\nimport { isDirectory, detectWorkspaceRoot } from './shared/utils';\nimport { templateOptions, ViteTemplate } from './shared/types';\nimport type { PromptAnswers } from './shared/types';\nimport { generateViteApp } from './shared/generators/createVite';\nimport { patchViteSubApp } from './shared/patchers';\n\nmain().catch((e) => {\n console.error(e);\n process.exit(1);\n});\n\nasync function main() {\n console.log();\n console.log(green('Welcome to create-qiankun!'));\n console.log();\n\n const argv = minimist(process.argv.slice(2));\n const argAppName = argv._[0];\n // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment\n const argTemplate = argv.template || argv.t;\n\n let answers: PromptAnswers;\n\n try {\n answers = (await prompts(\n [\n {\n name: 'appName',\n type: argAppName ? null : 'text',\n message: 'Sub-app name:',\n initial: 'qiankun-sub-app',\n validate: (value: string) => {\n if (!value.trim()) return 'App name is required';\n if (!/^[a-z0-9-]+$/.test(value)) return 'App name can only contain lowercase letters, numbers, and hyphens';\n return true;\n },\n },\n {\n name: 'template',\n type: argTemplate ? null : 'select',\n message: 'Select a framework:',\n choices: templateOptions,\n },\n ],\n {\n onCancel: () => {\n throw new Error('Operation cancelled');\n },\n },\n )) as PromptAnswers;\n } catch {\n console.log(red('Operation cancelled'));\n process.exit(1);\n }\n\n const appName = argAppName || answers.appName;\n const template = (argTemplate || answers.template) as ViteTemplate;\n\n const validTemplates = Object.values(ViteTemplate);\n if (!validTemplates.includes(template)) {\n console.log(red(`Invalid template: ${String(template)}. Valid options: ${validTemplates.join(', ')}`));\n process.exit(1);\n }\n\n const cwd = process.cwd();\n const workspaceRoot = detectWorkspaceRoot(cwd);\n const isInWorkspace = !!workspaceRoot;\n\n let targetDir: string;\n if (isInWorkspace) {\n const packagesDir = path.join(workspaceRoot, 'packages');\n targetDir = packagesDir;\n } else {\n targetDir = cwd;\n }\n\n const appPath = path.join(targetDir, appName);\n\n if (isDirectory(appPath)) {\n console.log(red(`Directory ${appPath} already exists`));\n process.exit(1);\n }\n\n console.log();\n console.log(green(`Creating ${appName} at ${appPath}...`));\n console.log();\n\n await generateViteApp(targetDir, appName, template);\n\n console.log();\n console.log(green('Patching for qiankun...'));\n\n await patchViteSubApp(appPath, appName, template);\n\n console.log();\n console.log(bold(green('Done!')));\n console.log();\n console.log('Next steps:');\n console.log(` cd ${isInWorkspace ? `packages/${appName}` : appName}`);\n console.log(' pnpm install');\n console.log(' pnpm dev # Run standalone');\n console.log(' pnpm build:qiankun # Build for qiankun');\n console.log();\n}\n" }, { "path": "packages/create-qiankun/src/shared/generators/createVite.ts", "content": "import fse from 'fs-extra';\nimport execa from 'execa';\nimport type { ViteTemplate } from '../types';\n\nexport async function generateViteApp(targetDir: string, appName: string, template: ViteTemplate): Promise {\n await fse.ensureDir(targetDir);\n\n const createViteBin = require.resolve('create-vite');\n\n await execa(process.execPath, [createViteBin, appName, '--template', template], {\n cwd: targetDir,\n stdio: 'inherit',\n });\n}\n" }, { "path": "packages/create-qiankun/src/shared/patchers/entryFile.ts", "content": "import path from 'node:path';\nimport fse from 'fs-extra';\nimport type { ViteTemplate } from '../types';\nimport { isReactTemplate, isTypeScriptTemplate } from '../types';\n\nexport async function writeEntryFile(appRoot: string, appName: string, template: ViteTemplate): Promise {\n const isReact = isReactTemplate(template);\n const isTs = isTypeScriptTemplate(template);\n\n if (isReact) {\n await writeReactEntry(appRoot, appName, isTs);\n } else {\n await writeVueEntry(appRoot, appName, isTs);\n }\n}\n\nasync function writeReactEntry(appRoot: string, appName: string, isTs: boolean): Promise {\n const ext = isTs ? 'tsx' : 'jsx';\n const entryPath = path.join(appRoot, `src/main.${ext}`);\n\n const typeAnnotation = isTs ? ': ReactDOM.Root | undefined' : '';\n const propsType = isTs ? ': { container?: Element }' : '';\n const defaultPropsType = isTs ? ': { container?: Element } = {}' : ' = {}';\n\n const content = `import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport App from './App';\nimport './index.css';\n\nconst appName = '${appName}';\nlet root${typeAnnotation};\n\nfunction render(props${defaultPropsType}) {\n const container = props.container?.querySelector('#root') ?? document.getElementById('root');\n if (!container) return;\n\n root = ReactDOM.createRoot(container);\n root.render(\n \n \n ,\n );\n}\n\nexport async function bootstrap() {\n return Promise.resolve();\n}\n\nexport async function mount(props${propsType}) {\n render(props);\n}\n\nexport async function unmount(props${propsType}) {\n if (root) {\n root.unmount();\n root = undefined;\n }\n const container = props.container?.querySelector('#root') ?? document.getElementById('root');\n if (container) {\n container.innerHTML = '';\n }\n}\n\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean;\n [key: string]: unknown;\n }\n}\n\nif (window.__POWERED_BY_QIANKUN__) {\n window[appName] = { bootstrap, mount, unmount };\n} else {\n render();\n}\n`;\n\n await fse.writeFile(entryPath, content, 'utf-8');\n}\n\nasync function writeVueEntry(appRoot: string, appName: string, isTs: boolean): Promise {\n const ext = isTs ? 'ts' : 'js';\n const entryPath = path.join(appRoot, `src/main.${ext}`);\n\n const typeAnnotation = isTs ? ': ReturnType | undefined' : '';\n const propsType = isTs ? ': { container?: Element }' : '';\n const defaultPropsType = isTs ? ': { container?: Element } = {}' : ' = {}';\n const declareGlobal = isTs\n ? `\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean;\n [key: string]: unknown;\n }\n}\n`\n : '';\n\n const content = `import { createApp } from 'vue';\nimport App from './App.vue';\nimport './style.css';\n\nconst appName = '${appName}';\nlet app${typeAnnotation};\n\nfunction render(props${defaultPropsType}) {\n const container = props.container?.querySelector('#app') ?? document.getElementById('app');\n if (!container) return;\n\n app = createApp(App);\n app.mount(container);\n}\n\nexport async function bootstrap() {\n return Promise.resolve();\n}\n\nexport async function mount(props${propsType}) {\n render(props);\n}\n\nexport async function unmount(props${propsType}) {\n if (app) {\n app.unmount();\n app = undefined;\n }\n const container = props.container?.querySelector('#app') ?? document.getElementById('app');\n if (container) {\n container.innerHTML = '';\n }\n}\n${declareGlobal}\nif (window.__POWERED_BY_QIANKUN__) {\n window[appName] = { bootstrap, mount, unmount };\n} else {\n render();\n}\n`;\n\n await fse.writeFile(entryPath, content, 'utf-8');\n}\n" }, { "path": "packages/create-qiankun/src/shared/patchers/index.ts", "content": "import type { ViteTemplate } from '../types';\nimport { patchPackageJson } from './packageJson';\nimport { writeQiankunHtmlPlugin } from './qiankunHtmlPlugin';\nimport { writeViteConfig } from './viteConfig';\nimport { writeEntryFile } from './entryFile';\n\nexport async function patchViteSubApp(appRoot: string, appName: string, template: ViteTemplate): Promise {\n await patchPackageJson(appRoot, appName, template);\n await writeQiankunHtmlPlugin(appRoot, template);\n await writeViteConfig(appRoot, template);\n await writeEntryFile(appRoot, appName, template);\n}\n" }, { "path": "packages/create-qiankun/src/shared/patchers/packageJson.ts", "content": "import path from 'node:path';\nimport fse from 'fs-extra';\nimport type { ViteTemplate } from '../types';\nimport { isReactTemplate } from '../types';\n\nconst LEGACY_PLUGIN_VERSION = '^5.4.2';\nconst CHEERIO_VERSION = '^1.0.0';\nconst QIANKUN_VERSION = '^3.0.0-rc.0';\nconst QIANKUN_REACT_VERSION = '^0.0.1-rc.0';\nconst QIANKUN_VUE_VERSION = '^0.0.1-rc.0';\n\nexport async function patchPackageJson(appRoot: string, appName: string, template: ViteTemplate): Promise {\n const pkgPath = path.join(appRoot, 'package.json');\n const pkg = (await fse.readJson(pkgPath)) as Record;\n\n pkg.name = appName;\n\n pkg.scripts = {\n ...(pkg.scripts || {}),\n 'build:qiankun': 'vite build --mode qiankun',\n 'preview:qiankun': 'vite preview --mode qiankun',\n };\n\n pkg.devDependencies = {\n ...(pkg.devDependencies || {}),\n '@vitejs/plugin-legacy': LEGACY_PLUGIN_VERSION,\n cheerio: CHEERIO_VERSION,\n };\n\n const qiankunBinding = isReactTemplate(template)\n ? { '@qiankunjs/react': QIANKUN_REACT_VERSION }\n : { '@qiankunjs/vue': QIANKUN_VUE_VERSION };\n\n pkg.dependencies = {\n ...(pkg.dependencies || {}),\n qiankun: QIANKUN_VERSION,\n ...qiankunBinding,\n };\n\n await fse.writeJson(pkgPath, pkg, { spaces: 2 });\n}\n" }, { "path": "packages/create-qiankun/src/shared/patchers/qiankunHtmlPlugin.ts", "content": "import path from 'node:path';\nimport fse from 'fs-extra';\nimport type { ViteTemplate } from '../types';\nimport { isTypeScriptTemplate } from '../types';\n\nexport async function writeQiankunHtmlPlugin(appRoot: string, template: ViteTemplate): Promise {\n const configDir = path.join(appRoot, 'config');\n await fse.ensureDir(configDir);\n\n const ext = isTypeScriptTemplate(template) ? 'ts' : 'js';\n const pluginPath = path.join(configDir, `qiankunHtml.${ext}`);\n\n const content = isTypeScriptTemplate(template) ? getTypeScriptPluginContent() : getJavaScriptPluginContent();\n\n await fse.writeFile(pluginPath, content, 'utf-8');\n}\n\nfunction getTypeScriptPluginContent(): string {\n return `import type { IndexHtmlTransformContext, PluginOption } from 'vite';\nimport { load } from 'cheerio';\n\nexport default function qiankunHtmlPlugin(): PluginOption {\n return {\n name: 'qiankun-html-transform',\n enforce: 'post',\n apply: 'build',\n transformIndexHtml(html: string, ctx: IndexHtmlTransformContext) {\n if (!ctx || !isQiankunBuild(ctx)) return html;\n return transformHtml(html);\n },\n };\n}\n\nfunction isQiankunBuild(ctx: IndexHtmlTransformContext): boolean {\n return ctx.bundle !== undefined && ctx.server === undefined;\n}\n\nfunction rewriteSystemImport(script: string): string {\n const parentUrl = 'window.__POWERED_BY_QIANKUN__ ? window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__ : document.baseURI';\n \n if (script.includes(parentUrl)) {\n return script;\n }\n \n const legacyEntryPattern = \"document.getElementById('vite-legacy-entry').getAttribute('data-src')\";\n if (script.includes(legacyEntryPattern)) {\n return script.replace(\n \\`System.import(\\${legacyEntryPattern})\\`,\n \\`System.import(\\${legacyEntryPattern}, \\${parentUrl})\\`\n );\n }\n \n return script;\n}\n\nfunction transformHtml(html: string): string {\n const $ = load(html);\n\n $('script[type=\"module\"]').remove();\n $('link[rel=\"modulepreload\"]').remove();\n\n $('script[nomodule]').each((_, el) => {\n const scriptContent = $(el).html();\n if (!scriptContent || !scriptContent.includes('System.import')) return;\n\n const updated = rewriteSystemImport(scriptContent);\n if (updated !== scriptContent) {\n $(el).text(updated);\n }\n });\n\n return $.html();\n}\n`;\n}\n\nfunction getJavaScriptPluginContent(): string {\n return `import { load } from 'cheerio';\n\nexport default function qiankunHtmlPlugin() {\n return {\n name: 'qiankun-html-transform',\n enforce: 'post',\n apply: 'build',\n transformIndexHtml(html, ctx) {\n if (!ctx || !isQiankunBuild(ctx)) return html;\n return transformHtml(html);\n },\n };\n}\n\nfunction isQiankunBuild(ctx) {\n return ctx.bundle !== undefined && ctx.server === undefined;\n}\n\nfunction rewriteSystemImport(script) {\n const parentUrl = 'window.__POWERED_BY_QIANKUN__ ? window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__ : document.baseURI';\n \n if (script.includes(parentUrl)) {\n return script;\n }\n \n const legacyEntryPattern = \"document.getElementById('vite-legacy-entry').getAttribute('data-src')\";\n if (script.includes(legacyEntryPattern)) {\n return script.replace(\n \\`System.import(\\${legacyEntryPattern})\\`,\n \\`System.import(\\${legacyEntryPattern}, \\${parentUrl})\\`\n );\n }\n \n return script;\n}\n\nfunction transformHtml(html) {\n const $ = load(html);\n\n $('script[type=\"module\"]').remove();\n $('link[rel=\"modulepreload\"]').remove();\n\n $('script[nomodule]').each((_, el) => {\n const scriptContent = $(el).html();\n if (!scriptContent || !scriptContent.includes('System.import')) return;\n\n const updated = rewriteSystemImport(scriptContent);\n if (updated !== scriptContent) {\n $(el).text(updated);\n }\n });\n\n return $.html();\n}\n`;\n}\n" }, { "path": "packages/create-qiankun/src/shared/patchers/viteConfig.ts", "content": "import path from 'node:path';\nimport fse from 'fs-extra';\nimport type { ViteTemplate } from '../types';\nimport { isReactTemplate, isTypeScriptTemplate } from '../types';\n\nexport async function writeViteConfig(appRoot: string, template: ViteTemplate): Promise {\n const ext = isTypeScriptTemplate(template) ? 'ts' : 'js';\n const configPath = path.join(appRoot, `vite.config.${ext}`);\n\n const content = isTypeScriptTemplate(template) ? getTypeScriptConfig(template) : getJavaScriptConfig(template);\n\n await fse.writeFile(configPath, content, 'utf-8');\n}\n\nfunction getTypeScriptConfig(template: ViteTemplate): string {\n const frameworkImport = isReactTemplate(template)\n ? \"import react from '@vitejs/plugin-react';\"\n : \"import vue from '@vitejs/plugin-vue';\";\n const pluginCall = isReactTemplate(template) ? 'react()' : 'vue()';\n\n return `import { defineConfig } from 'vite';\n${frameworkImport}\nimport legacy from '@vitejs/plugin-legacy';\nimport qiankunHtmlPlugin from './config/qiankunHtml';\n\nexport default defineConfig(({ mode }) => {\n const isQiankun = mode === 'qiankun';\n\n return {\n base: isQiankun ? './' : '/',\n plugins: [\n ${pluginCall},\n isQiankun && legacy({ renderLegacyChunks: true }),\n isQiankun && qiankunHtmlPlugin(),\n ].filter(Boolean),\n server: {\n cors: true,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n };\n});\n`;\n}\n\nfunction getJavaScriptConfig(template: ViteTemplate): string {\n const frameworkImport = isReactTemplate(template)\n ? \"import react from '@vitejs/plugin-react';\"\n : \"import vue from '@vitejs/plugin-vue';\";\n const pluginCall = isReactTemplate(template) ? 'react()' : 'vue()';\n\n return `import { defineConfig } from 'vite';\n${frameworkImport}\nimport legacy from '@vitejs/plugin-legacy';\nimport qiankunHtmlPlugin from './config/qiankunHtml';\n\nexport default defineConfig(({ mode }) => {\n const isQiankun = mode === 'qiankun';\n\n return {\n base: isQiankun ? './' : '/',\n plugins: [\n ${pluginCall},\n isQiankun && legacy({ renderLegacyChunks: true }),\n isQiankun && qiankunHtmlPlugin(),\n ].filter(Boolean),\n server: {\n cors: true,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n };\n});\n`;\n}\n" }, { "path": "packages/create-qiankun/src/shared/types.ts", "content": "export enum ViteTemplate {\n ReactTs = 'react-ts',\n React = 'react',\n VueTs = 'vue-ts',\n Vue = 'vue',\n}\n\nexport interface TemplateOption {\n title: string;\n value: ViteTemplate;\n}\n\nexport const templateOptions: TemplateOption[] = [\n { title: 'React + TypeScript', value: ViteTemplate.ReactTs },\n { title: 'React', value: ViteTemplate.React },\n { title: 'Vue + TypeScript', value: ViteTemplate.VueTs },\n { title: 'Vue', value: ViteTemplate.Vue },\n];\n\nexport interface PromptAnswers {\n appName: string;\n template: ViteTemplate;\n}\n\nexport function isReactTemplate(template: ViteTemplate): boolean {\n return template === ViteTemplate.React || template === ViteTemplate.ReactTs;\n}\n\nexport function isTypeScriptTemplate(template: ViteTemplate): boolean {\n return template === ViteTemplate.ReactTs || template === ViteTemplate.VueTs;\n}\n" }, { "path": "packages/create-qiankun/src/shared/utils/index.ts", "content": "import fse from 'fs-extra';\nimport path from 'node:path';\n\nexport function isDirectory(targetPath: string): boolean {\n try {\n return fse.lstatSync(targetPath).isDirectory();\n } catch {\n return false;\n }\n}\n\nexport function isFile(targetPath: string): boolean {\n try {\n return fse.lstatSync(targetPath).isFile();\n } catch {\n return false;\n }\n}\n\nexport function detectWorkspaceRoot(targetDir: string): string | null {\n const parentDir = path.dirname(targetDir);\n if (isFile(path.join(parentDir, 'pnpm-workspace.yaml'))) {\n return parentDir;\n }\n return null;\n}\n" }, { "path": "packages/create-qiankun/tests/e2e.cli.test.ts", "content": "/* eslint-disable @typescript-eslint/no-unsafe-assignment,@typescript-eslint/no-unsafe-member-access */\n\nimport { describe, it, expect, beforeAll, afterAll } from 'vitest';\nimport execa from 'execa';\nimport fse from 'fs-extra';\nimport path from 'node:path';\nimport os from 'node:os';\n\nconst CLI_PATH = path.resolve(__dirname, '../dist/index.js');\nconst FIXTURES_PATH = path.resolve(__dirname, 'fixtures');\nconst E2E_TIMEOUT = process.env.E2E_TIMEOUT ? parseInt(process.env.E2E_TIMEOUT, 10) : 180000;\n\nconst APP_NAME_PLACEHOLDER = '{{APP_NAME}}';\n\nasync function runCli(cwd: string, appName: string, template: string): Promise {\n await execa('node', [CLI_PATH, appName, '--template', template], {\n cwd,\n stdio: 'inherit',\n });\n}\n\nasync function installAndBuild(appPath: string): Promise {\n await execa('pnpm', ['install'], { cwd: appPath, stdio: 'inherit' });\n await execa('pnpm', ['build:qiankun'], { cwd: appPath, stdio: 'inherit' });\n}\n\nfunction normalizeContent(content: string, appName: string): string {\n return content.replace(new RegExp(appName, 'g'), APP_NAME_PLACEHOLDER);\n}\n\nasync function loadFixture(template: string, fileName: string): Promise {\n const fixturePath = path.join(FIXTURES_PATH, template, fileName);\n return fse.readFile(fixturePath, 'utf-8');\n}\n\nasync function assertFileMatchesFixture(\n actualPath: string,\n template: string,\n fixtureFileName: string,\n appName: string,\n): Promise {\n const actualContent = await fse.readFile(actualPath, 'utf-8');\n const expectedContent = await loadFixture(template, fixtureFileName);\n const normalizedActual = normalizeContent(actualContent, appName);\n\n expect(normalizedActual).toBe(expectedContent);\n}\n\nfunction assertQiankunHtml(html: string): void {\n expect(html).not.toMatch(/]*type=[\"']?module[\"']?[^>]*>/);\n expect(html).not.toMatch(/]*rel=[\"']?modulepreload[\"']?[^>]*>/);\n expect(html).toMatch(/id=[\"']?vite-legacy-entry[\"']?/);\n expect(html).toContain('window.__POWERED_BY_QIANKUN__');\n expect(html).toContain('__INJECTED_PUBLIC_PATH_BY_QIANKUN__');\n expect(html).toMatch(/nomodule/);\n expect(html).toMatch(/]*rel=[\"']?stylesheet[\"']?[^>]*>/);\n}\n\ndescribe('create-qiankun CLI e2e', () => {\n const testDir = path.join(os.tmpdir(), `create-qiankun-e2e-${Date.now()}`);\n\n beforeAll(async () => {\n await fse.ensureDir(testDir);\n });\n\n afterAll(async () => {\n await fse.remove(testDir);\n });\n\n describe('React + TypeScript template', () => {\n const appName = 'react-ts-sub';\n const appPath = path.join(testDir, appName);\n const template = 'react-ts';\n\n it(\n 'should scaffold, patch, and build successfully',\n async () => {\n await runCli(testDir, appName, template);\n\n expect(await fse.pathExists(appPath)).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'package.json'))).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'vite.config.ts'))).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'config/qiankunHtml.ts'))).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'src/main.tsx'))).toBe(true);\n\n await installAndBuild(appPath);\n\n expect(await fse.pathExists(path.join(appPath, 'dist/index.html'))).toBe(true);\n },\n E2E_TIMEOUT,\n );\n\n it('should produce valid qiankun HTML output', async () => {\n const html = await fse.readFile(path.join(appPath, 'dist/index.html'), 'utf-8');\n assertQiankunHtml(html);\n });\n\n it('should generate correct entry file', async () => {\n await assertFileMatchesFixture(path.join(appPath, 'src/main.tsx'), template, 'main.tsx.txt', appName);\n });\n\n it('should generate correct vite.config.ts', async () => {\n await assertFileMatchesFixture(path.join(appPath, 'vite.config.ts'), template, 'vite.config.ts.txt', appName);\n });\n\n it('should generate correct qiankunHtml plugin', async () => {\n await assertFileMatchesFixture(\n path.join(appPath, 'config/qiankunHtml.ts'),\n template,\n 'qiankunHtml.ts.txt',\n appName,\n );\n });\n\n it('should have correct package.json scripts and dependencies', async () => {\n const pkg = await fse.readJson(path.join(appPath, 'package.json'));\n\n expect(pkg.name).toBe(appName);\n expect(pkg.scripts['build:qiankun']).toBe('vite build --mode qiankun');\n expect(pkg.devDependencies['@vitejs/plugin-legacy']).toBeDefined();\n expect(pkg.devDependencies['cheerio']).toBeDefined();\n expect(pkg.dependencies['qiankun']).toBeDefined();\n expect(pkg.dependencies['@qiankunjs/react']).toBeDefined();\n });\n });\n\n describe('Vue + TypeScript template', () => {\n const appName = 'vue-ts-sub';\n const appPath = path.join(testDir, appName);\n const template = 'vue-ts';\n\n it(\n 'should scaffold, patch, and build successfully',\n async () => {\n await runCli(testDir, appName, template);\n\n expect(await fse.pathExists(appPath)).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'package.json'))).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'vite.config.ts'))).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'config/qiankunHtml.ts'))).toBe(true);\n expect(await fse.pathExists(path.join(appPath, 'src/main.ts'))).toBe(true);\n\n await installAndBuild(appPath);\n\n expect(await fse.pathExists(path.join(appPath, 'dist/index.html'))).toBe(true);\n },\n E2E_TIMEOUT,\n );\n\n it('should produce valid qiankun HTML output', async () => {\n const html = await fse.readFile(path.join(appPath, 'dist/index.html'), 'utf-8');\n assertQiankunHtml(html);\n });\n\n it('should generate correct entry file', async () => {\n await assertFileMatchesFixture(path.join(appPath, 'src/main.ts'), template, 'main.ts.txt', appName);\n });\n\n it('should generate correct vite.config.ts', async () => {\n await assertFileMatchesFixture(path.join(appPath, 'vite.config.ts'), template, 'vite.config.ts.txt', appName);\n });\n\n it('should generate correct qiankunHtml plugin', async () => {\n await assertFileMatchesFixture(\n path.join(appPath, 'config/qiankunHtml.ts'),\n template,\n 'qiankunHtml.ts.txt',\n appName,\n );\n });\n\n it('should have correct package.json with Vue dependencies', async () => {\n const pkg = await fse.readJson(path.join(appPath, 'package.json'));\n\n expect(pkg.name).toBe(appName);\n expect(pkg.dependencies['@qiankunjs/vue']).toBeDefined();\n expect(pkg.dependencies['vue']).toBeDefined();\n });\n });\n});\n" }, { "path": "packages/create-qiankun/tests/fixtures/react-ts/main.tsx.txt", "content": "import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport App from './App';\nimport './index.css';\n\nconst appName = '{{APP_NAME}}';\nlet root: ReactDOM.Root | undefined;\n\nfunction render(props: { container?: Element } = {}) {\n const container = props.container?.querySelector('#root') ?? document.getElementById('root');\n if (!container) return;\n\n root = ReactDOM.createRoot(container);\n root.render(\n \n \n ,\n );\n}\n\nexport async function bootstrap() {\n return Promise.resolve();\n}\n\nexport async function mount(props: { container?: Element }) {\n render(props);\n}\n\nexport async function unmount(props: { container?: Element }) {\n if (root) {\n root.unmount();\n root = undefined;\n }\n const container = props.container?.querySelector('#root') ?? document.getElementById('root');\n if (container) {\n container.innerHTML = '';\n }\n}\n\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean;\n [key: string]: unknown;\n }\n}\n\nif (window.__POWERED_BY_QIANKUN__) {\n window[appName] = { bootstrap, mount, unmount };\n} else {\n render();\n}\n" }, { "path": "packages/create-qiankun/tests/fixtures/react-ts/qiankunHtml.ts.txt", "content": "import type { IndexHtmlTransformContext, PluginOption } from 'vite';\nimport { load } from 'cheerio';\n\nexport default function qiankunHtmlPlugin(): PluginOption {\n return {\n name: 'qiankun-html-transform',\n enforce: 'post',\n apply: 'build',\n transformIndexHtml(html: string, ctx: IndexHtmlTransformContext) {\n if (!ctx || !isQiankunBuild(ctx)) return html;\n return transformHtml(html);\n },\n };\n}\n\nfunction isQiankunBuild(ctx: IndexHtmlTransformContext): boolean {\n return ctx.bundle !== undefined && ctx.server === undefined;\n}\n\nfunction rewriteSystemImport(script: string): string {\n const parentUrl = 'window.__POWERED_BY_QIANKUN__ ? window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__ : document.baseURI';\n\n if (script.includes(parentUrl)) {\n return script;\n }\n\n const legacyEntryPattern = \"document.getElementById('vite-legacy-entry').getAttribute('data-src')\";\n if (script.includes(legacyEntryPattern)) {\n return script.replace(`System.import(${legacyEntryPattern})`, `System.import(${legacyEntryPattern}, ${parentUrl})`);\n }\n\n return script;\n}\n\nfunction transformHtml(html: string): string {\n const $ = load(html);\n\n $('script[type=\"module\"]').remove();\n $('link[rel=\"modulepreload\"]').remove();\n\n $('script[nomodule]').each((_, el) => {\n const scriptContent = $(el).html();\n if (!scriptContent || !scriptContent.includes('System.import')) return;\n\n const updated = rewriteSystemImport(scriptContent);\n if (updated !== scriptContent) {\n $(el).text(updated);\n }\n });\n\n return $.html();\n}\n" }, { "path": "packages/create-qiankun/tests/fixtures/react-ts/vite.config.ts.txt", "content": "import { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport legacy from '@vitejs/plugin-legacy';\nimport qiankunHtmlPlugin from './config/qiankunHtml';\n\nexport default defineConfig(({ mode }) => {\n const isQiankun = mode === 'qiankun';\n\n return {\n base: isQiankun ? './' : '/',\n plugins: [react(), isQiankun && legacy({ renderLegacyChunks: true }), isQiankun && qiankunHtmlPlugin()].filter(\n Boolean,\n ),\n server: {\n cors: true,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n };\n});\n" }, { "path": "packages/create-qiankun/tests/fixtures/vue-ts/main.ts.txt", "content": "import { createApp } from 'vue';\nimport App from './App.vue';\nimport './style.css';\n\nconst appName = '{{APP_NAME}}';\nlet app: ReturnType | undefined;\n\nfunction render(props: { container?: Element } = {}) {\n const container = props.container?.querySelector('#app') ?? document.getElementById('app');\n if (!container) return;\n\n app = createApp(App);\n app.mount(container);\n}\n\nexport async function bootstrap() {\n return Promise.resolve();\n}\n\nexport async function mount(props: { container?: Element }) {\n render(props);\n}\n\nexport async function unmount(props: { container?: Element }) {\n if (app) {\n app.unmount();\n app = undefined;\n }\n const container = props.container?.querySelector('#app') ?? document.getElementById('app');\n if (container) {\n container.innerHTML = '';\n }\n}\n\ndeclare global {\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean;\n [key: string]: unknown;\n }\n}\n\nif (window.__POWERED_BY_QIANKUN__) {\n window[appName] = { bootstrap, mount, unmount };\n} else {\n render();\n}\n" }, { "path": "packages/create-qiankun/tests/fixtures/vue-ts/qiankunHtml.ts.txt", "content": "import type { IndexHtmlTransformContext, PluginOption } from 'vite';\nimport { load } from 'cheerio';\n\nexport default function qiankunHtmlPlugin(): PluginOption {\n return {\n name: 'qiankun-html-transform',\n enforce: 'post',\n apply: 'build',\n transformIndexHtml(html: string, ctx: IndexHtmlTransformContext) {\n if (!ctx || !isQiankunBuild(ctx)) return html;\n return transformHtml(html);\n },\n };\n}\n\nfunction isQiankunBuild(ctx: IndexHtmlTransformContext): boolean {\n return ctx.bundle !== undefined && ctx.server === undefined;\n}\n\nfunction rewriteSystemImport(script: string): string {\n const parentUrl = 'window.__POWERED_BY_QIANKUN__ ? window.__INJECTED_PUBLIC_PATH_BY_QIANKUN__ : document.baseURI';\n\n if (script.includes(parentUrl)) {\n return script;\n }\n\n const legacyEntryPattern = \"document.getElementById('vite-legacy-entry').getAttribute('data-src')\";\n if (script.includes(legacyEntryPattern)) {\n return script.replace(`System.import(${legacyEntryPattern})`, `System.import(${legacyEntryPattern}, ${parentUrl})`);\n }\n\n return script;\n}\n\nfunction transformHtml(html: string): string {\n const $ = load(html);\n\n $('script[type=\"module\"]').remove();\n $('link[rel=\"modulepreload\"]').remove();\n\n $('script[nomodule]').each((_, el) => {\n const scriptContent = $(el).html();\n if (!scriptContent || !scriptContent.includes('System.import')) return;\n\n const updated = rewriteSystemImport(scriptContent);\n if (updated !== scriptContent) {\n $(el).text(updated);\n }\n });\n\n return $.html();\n}\n" }, { "path": "packages/create-qiankun/tests/fixtures/vue-ts/vite.config.ts.txt", "content": "import { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\nimport legacy from '@vitejs/plugin-legacy';\nimport qiankunHtmlPlugin from './config/qiankunHtml';\n\nexport default defineConfig(({ mode }) => {\n const isQiankun = mode === 'qiankun';\n\n return {\n base: isQiankun ? './' : '/',\n plugins: [vue(), isQiankun && legacy({ renderLegacyChunks: true }), isQiankun && qiankunHtmlPlugin()].filter(\n Boolean,\n ),\n server: {\n cors: true,\n headers: {\n 'Access-Control-Allow-Origin': '*',\n },\n },\n };\n});\n" }, { "path": "packages/create-qiankun/tsconfig.json", "content": "{\n \"extends\": \"../../tsconfig.json\"\n}\n" }, { "path": "packages/create-qiankun/vitest.config.ts", "content": "import { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n test: {\n // Exclude E2E tests from regular test runs - they require built dist\n exclude: ['**/e2e*.test.ts', '**/node_modules/**'],\n passWithNoTests: true,\n },\n});\n" }, { "path": "packages/create-qiankun/vitest.e2e.config.ts", "content": "import { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n test: {\n include: ['**/e2e*.test.ts'],\n testTimeout: Number(process.env.E2E_TIMEOUT) || 180_000,\n },\n});\n" }, { "path": "packages/loader/.fatherrc.js", "content": "export { default } from '../../.fatherrc.cjs';\n" }, { "path": "packages/loader/AGENTS.md", "content": "# @qiankunjs/loader\n\nStreaming HTML entry loader using writable-dom.\n\n## STRUCTURE\n\n```\nloader/\n├── index.ts # loadEntry() - main API\n├── TagTransformStream.ts # → replacement\n├── writable-dom/ # Forked streaming DOM engine\n│ └── index.ts # WritableDOMStream implementation\n└── parser.ts # Static HTML parsing for prefetch\n```\n\n## WHERE TO LOOK\n\n| Task | File | Notes |\n| ------------------- | ----------------------- | -------------------------------------- |\n| Load micro-app | `index.ts` | `loadEntry(url, container, opts)` |\n| Head virtualization | `TagTransformStream.ts` | String-level tag replacement |\n| Streaming DOM | `writable-dom/index.ts` | Incremental parsing + blocking scripts |\n\n## LOADING PIPELINE\n\n```\n1. fetch(entry)\n ↓\n2. TextDecoderStream (bytes → string)\n ↓\n3. TagTransformStream ( → )\n ↓\n4. WritableDOMStream (stream → live DOM)\n ├─ nodeTransformer called per node\n ├─ Blocks on sync scripts/styles\n └─ Preloads other assets while blocked\n ↓\n5. Resolve with sandbox.latestSetProp (app exports)\n```\n\n## KEY PATTERNS\n\n### Entry Script Detection\n\n```typescript\n// Script with `entry` attribute = app's main export point\n\n// Loader resolves promise when entry script loads\n```\n\n### Defer Script Ordering\n\n- Deferred queue ensures correct execution order\n- `prepareDeferredQueue` from @qiankunjs/shared\n\n### Detached Parsing\n\n- HTML parsed in detached document first\n- Nodes transformed before moving to live DOM\n- Prevents premature script execution\n\n## ANTI-PATTERNS\n\n- **NEVER** include >1 `entry` script per HTML entry (throws QiankunError)\n- **FIXME**: Non-standard HTML chunks lacking `` tag\n\n## EXPORTS\n\n```typescript\nexport { loadEntry, type LoaderOpts } from './index';\n```\n" }, { "path": "packages/loader/CHANGELOG.md", "content": "# @qiankunjs/loader\n\n## 0.0.1-rc.21\n\n### Patch Changes\n\n- 57a6129: feat: improve fetch error message by prepending url\n- Updated dependencies [7d8591e]\n- Updated dependencies [57a6129]\n- Updated dependencies [34069e1]\n - @qiankunjs/shared@0.0.1-rc.13\n\n## 0.0.1-rc.20\n\n### Patch Changes\n\n- 7d77699: feat(loader): supports passing Response as entry parameter for loadEntry function\n- Updated dependencies [ea18ce6] [9c56910] [6d252c6]\n - @qiankunjs/shared@0.0.1-rc.12\n - @qiankunjs/sandbox@0.0.1-rc.17\n\n## 0.0.1-rc.19\n\n### Patch Changes\n\n- 99bf65f: feat: support huge inline-script who might be split into multiple chunks during transfer\n- Updated dependencies [56fef69]\n- Updated dependencies [99bf65f]\n - @qiankunjs/shared@0.0.1-rc.11\n - @qiankunjs/sandbox@0.0.1-rc.16\n\n## 0.0.1-rc.18\n\n### Patch Changes\n\n- Updated dependencies [c3416647]\n - @qiankunjs/sandbox@0.0.1-rc.15\n\n## 0.0.1-rc.17\n\n### Patch Changes\n\n- Updated dependencies [8c526255]\n - @qiankunjs/sandbox@0.0.1-rc.14\n\n## 0.0.1-rc.16\n\n### Patch Changes\n\n- feb544f0: fix: dynamic append element should support for the same container between micro apps\n- 2e528c9d: fix: prefer reading script.dataset.src in script load error message\n- Updated dependencies [a826cf5e]\n- Updated dependencies [3e43a111]\n- Updated dependencies [f09c1538]\n- Updated dependencies [d904f5d8]\n- Updated dependencies [b2d2c11a]\n- Updated dependencies [feb544f0]\n- Updated dependencies [9082546e]\n- Updated dependencies [62048537]\n - @qiankunjs/shared@0.0.1-rc.10\n - @qiankunjs/sandbox@0.0.1-rc.13\n\n## 0.0.1-rc.15\n\n### Patch Changes\n\n- bd12dbad: fix: defer scripts should wait until html loaded\n- Updated dependencies [bd12dbad]\n - @qiankunjs/sandbox@0.0.1-rc.12\n - @qiankunjs/shared@0.0.1-rc.9\n\n## 0.0.1-rc.14\n\n### Patch Changes\n\n- 98b071bf: feat: support defer scripts and keep the executing order to consist with browser\n- Updated dependencies [98b071bf]\n - @qiankunjs/sandbox@0.0.1-rc.11\n - @qiankunjs/shared@0.0.1-rc.8\n\n## 0.0.1-rc.13\n\n### Patch Changes\n\n- f2af2e36: feat: extract NodeTransformer type to shared package\n- Updated dependencies [f2af2e36]\n - @qiankunjs/sandbox@0.0.1-rc.10\n - @qiankunjs/shared@0.0.1-rc.7\n\n## 0.0.1-rc.12\n\n### Patch Changes\n\n- 54b0878e: feat(loader): compatible with defer entry script\n- 7ba95cf2: feat: change script src before it execute thus we can be more consistent with the native browser logic\n- Updated dependencies [d3e9872d]\n- Updated dependencies [7cc06bd4]\n- Updated dependencies [54b0878e]\n- Updated dependencies [7ba95cf2]\n- Updated dependencies [312abbc7]\n- Updated dependencies [6f074136]\n - @qiankunjs/sandbox@0.0.1-rc.9\n - @qiankunjs/shared@0.0.1-rc.6\n\n## 0.0.1-rc.11\n\n### Patch Changes\n\n- 43bf37a5: fix(sandbox): should get container from getter function in every accessing\n- Updated dependencies [43bf37a5]\n- Updated dependencies [a34a92a9]\n- Updated dependencies [7cf93b54]\n- Updated dependencies [32106b11]\n - @qiankunjs/sandbox@0.0.1-rc.8\n\n## 0.0.1-rc.10\n\n### Patch Changes\n\n- 8e54e129: feat: add isRuntimeCompatible api to check qiankun3 compatibility\n- Updated dependencies [5f77347b]\n- Updated dependencies [8e54e129]\n - @qiankunjs/sandbox@0.0.1-rc.7\n - @qiankunjs/shared@0.0.1-rc.5\n\n## 0.0.1-rc.9\n\n### Patch Changes\n\n- 1b0ffa2f: fix(loader): we should invoke our script load listener before its own\n\n## 0.0.1-rc.8\n\n### Patch Changes\n\n- Updated dependencies [2aca545c]\n - @qiankunjs/sandbox@0.0.1-rc.6\n\n## 0.0.1-rc.7\n\n### Patch Changes\n\n- 1d9adcaa: fix: transformer should be generated in every load\n\n## 0.0.1-rc.6\n\n### Patch Changes\n\n- Updated dependencies [3d1d3367]\n - @qiankunjs/sandbox@0.0.1-rc.5\n\n## 0.0.1-rc.5\n\n### Patch Changes\n\n- 317961eb: ✨ add transformer options for app loader\n- 76b6bff7: 🐛 compatible with webpack chunk cache logic\n- Updated dependencies [488447ad]\n- Updated dependencies [dc4d9aef]\n- Updated dependencies [e7d788ef]\n- Updated dependencies [76b6bff7]\n - @qiankunjs/sandbox@0.0.1-rc.4\n - @qiankunjs/shared@0.0.1-rc.4\n\n## 0.0.1-rc.4\n\n### Patch Changes\n\n- Updated dependencies [39301f19]\n - @qiankunjs/sandbox@0.0.1-rc.3\n - @qiankunjs/shared@0.0.1-rc.3\n\n## 0.0.1-rc.3\n\n### Patch Changes\n\n- Updated dependencies [b23d3d7b]\n - @qiankunjs/shared@0.0.1-rc.2\n - @qiankunjs/sandbox@0.0.1-rc.2\n\n## 0.0.1-rc.2\n\n### Patch Changes\n\n- Updated dependencies [ebb2bcaa]\n - @qiankunjs/shared@0.0.1-rc.1\n - @qiankunjs/sandbox@0.0.1-rc.1\n\n## 0.0.1-beta.6\n\n### Patch Changes\n\n- ffd77800: ✨support to transform head/body tags to qiankun head/body in stream\n- Updated dependencies [ffd77800]\n - @qiankunjs/sandbox@0.0.1-beta.6\n - @qiankunjs/shared@0.0.1-beta.6\n\n## 0.0.1-alpha.5\n\n### Patch Changes\n\n- Updated dependencies [fcb49aad]\n- Updated dependencies [065d2c54]\n- Updated dependencies [931dc1f7]\n - @qiankunjs/shared@0.0.1-alpha.5\n - @qiankunjs/sandbox@0.0.1-alpha.5\n\n## 0.0.1-alpha.4\n\n### Patch Changes\n\n- 62d3b482: 🏷️ fix typings temporary\n- ⚡️ support preload with dependencies reusing\n- Updated dependencies [62d3b482]\n - @qiankunjs/shared@0.0.1-alpha.4\n - @qiankunjs/sandbox@0.0.1-alpha.4\n\n## 0.0.1-alpha.3\n\n### Patch Changes\n\n- daaa9ccc: ✨support code block in sandbox\n- Updated dependencies [e12d29ae]\n- Updated dependencies [daaa9ccc]\n - @qiankunjs/shared@0.0.1-alpha.3\n - @qiankunjs/sandbox@0.0.1-alpha.3\n\n## 0.0.1-alpha.2\n\n### Patch Changes\n\n- 33e65888: fix: changeset\n- Updated dependencies [33e65888]\n - @qiankunjs/sandbox@0.0.1-alpha.2\n - @qiankunjs/shared@0.0.1-alpha.2\n\n## 0.0.1-alpha.1\n\n### Patch Changes\n\n- Updated dependencies\n - @qiankunjs/sandbox@0.0.1-alpha.1\n - @qiankunjs/shared@0.0.1-alpha.1\n\n## 0.0.1-alpha.0\n\n### Patch Changes\n\n- 3.0 alpha\n- Updated dependencies\n - @qiankunjs/sandbox@0.0.1-alpha.0\n - @qiankunjs/shared@0.0.1-alpha.0\n" }, { "path": "packages/loader/benchmarks/parser/html.js", "content": "export const htmlContent = `金融云控制台
\n`;\n" }, { "path": "packages/loader/benchmarks/parser/huge-html/huge-html.js", "content": "export const hugeHtmlContent = `test1234567890
`;\n" }, { "path": "packages/loader/benchmarks/parser/huge-html/import-html-entry.html", "content": "\n\n \n \n import html entry for huge html\n \n \n \n \n\n" }, { "path": "packages/loader/benchmarks/parser/huge-html/parser.html", "content": "\n\n \n \n parser for huge html\n \n \n \n \n\n" }, { "path": "packages/loader/benchmarks/parser/import-html-entry.html", "content": "\n\n \n \n import html entry for normal html\n \n \n \n \n\n" }, { "path": "packages/loader/benchmarks/parser/parser.html", "content": "\n\n \n \n parser for normal html\n \n\n \n \n \n\n" }, { "path": "packages/loader/benchmarks/parser/tern/html.js", "content": "export const htmlContent = `\n\n\n\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n \n \n \n
\n\n \n\n\n\n`;\n" }, { "path": "packages/loader/benchmarks/parser/tern/import-html-entry.html", "content": "\n\n \n \n import html entry for normal html\n \n \n \n \n\n" }, { "path": "packages/loader/benchmarks/parser/tern/parser.html", "content": "\n\n \n \n parser for normal html\n \n\n \n \n \n\n" }, { "path": "packages/loader/package.json", "content": "{\n \"name\": \"@qiankunjs/loader\",\n \"version\": \"0.0.1-rc.21\",\n \"description\": \"\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/umijs/qiankun.git\"\n },\n \"main\": \"./dist/cjs/index.js\",\n \"module\": \"./dist/esm/index.js\",\n \"types\": \"./dist/esm/index.d.ts\",\n \"sideEffects\": false,\n \"scripts\": {\n \"build\": \"father build\",\n \"bench\": \"npm run build && tachometer ./benchmarks/parser/tern/import-html-entry.html ./benchmarks/parser/tern/parser.html --timeout=1\"\n },\n \"author\": \"Kuitos\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@babel/runtime\": \"^7.26.10\",\n \"@qiankunjs/sandbox\": \"workspace:^\",\n \"@qiankunjs/shared\": \"workspace:^\",\n \"lodash\": \"^4.17.11\"\n },\n \"devDependencies\": {\n \"import-html-entry\": \"^1.12.0\",\n \"tachometer\": \"^0.5.10\"\n },\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\"\n },\n \"files\": [\n \"dist\"\n ]\n}\n" }, { "path": "packages/loader/src/TagTransformStream.ts", "content": "type TagReplacement = {\n // start tag\n tag: string;\n // start tag replacement\n alt: string;\n};\n\ntype AutoCompleteTags = {\n head?: boolean;\n body?: boolean;\n};\n\nexport function createTagTransformStream(\n tagReplacements: TagReplacement[],\n autoCompleteTags: AutoCompleteTags,\n): TransformStream {\n class TagTransformStream extends TransformStream {\n constructor(trs: TagReplacement[], acts: AutoCompleteTags) {\n let buffer = '';\n super({\n async transform(chunk: string, controller: TransformStreamDefaultController) {\n buffer += chunk;\n\n const data = trs.reduce((acc, replacement) => acc.replace(replacement.tag, replacement.alt), buffer);\n\n // while buffer is equal to data, it means that the data has not been replaced, and the data will be written to the buffer for checking next time\n if (buffer === data) {\n return;\n }\n\n controller.enqueue(data);\n buffer = '';\n },\n\n flush(controller: TransformStreamDefaultController) {\n if (buffer) {\n // FIXME It may be a non-standard HTML chunk that does not contain the head tag, in which case you need to manually fill in a head element\n if (buffer.indexOf(``) === -1 && acts.body) {\n buffer = `${buffer}`;\n }\n // if (buffer.indexOf(``) === -1) {\n // buffer = `${buffer}`;\n // }\n\n const data = trs.reduce((acc, replacement) => acc.replace(replacement.tag, replacement.alt), buffer);\n controller.enqueue(data);\n\n buffer = '';\n }\n },\n });\n }\n }\n\n return new TagTransformStream(tagReplacements, autoCompleteTags);\n}\n" }, { "path": "packages/loader/src/index.ts", "content": "import type { Sandbox } from '@qiankunjs/sandbox';\nimport { qiankunHeadTagName } from '@qiankunjs/sandbox';\nimport type {\n AssetsTranspilerOpts,\n BaseTranspilerOpts,\n NodeTransformer,\n ScriptTranspilerOpts,\n} from '@qiankunjs/shared';\nimport { Deferred, prepareDeferredQueue, QiankunError } from '@qiankunjs/shared';\nimport { createTagTransformStream } from './TagTransformStream';\nimport WritableDOMStream from './writable-dom';\n\ntype HTMLEntry = string;\n// type ConfigEntry = { html: string; scripts: [], styles: [] };\n\ntype Entry = HTMLEntry;\n\n// type EntryInstance = {\n// htmlDocument: Document;\n// prefetch: () => Promise;\n// execute: (executor?: Promise) => Promise;\n// };\n//\nexport type LoaderOpts = {\n streamTransformer?: () => TransformStream;\n nodeTransformer?: NodeTransformer;\n} & Omit & { sandbox?: Sandbox };\n\nconst isExternalScript = (script: HTMLScriptElement): boolean => {\n return script.tagName === 'SCRIPT' && !!(script.src || script.dataset.src);\n};\nconst isEntryScript = (script: HTMLScriptElement): boolean => {\n return isExternalScript(script) && script.hasAttribute('entry');\n};\nconst isDeferScript = (script: HTMLScriptElement): boolean => {\n return isExternalScript(script) && script.hasAttribute('defer');\n};\n\n/**\n * @param entry\n * @param container\n * @param opts\n */\nexport async function loadEntry(\n entry: Entry | { url: string; res: Response },\n container: HTMLElement,\n opts: LoaderOpts,\n): Promise {\n const { fetch, streamTransformer, sandbox, nodeTransformer } = opts;\n\n const entryUrl = typeof entry === 'string' ? entry : entry.url;\n const res = typeof entry === 'string' ? await fetch(entry) : entry.res;\n if (res.body) {\n let foundEntryScript = false;\n const entryScriptLoadedDeferred = new Deferred();\n const onEntryLoaded = () => {\n // the latest set prop is the entry script exposed global variable\n if (sandbox?.latestSetProp) {\n // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access\n entryScriptLoadedDeferred.resolve(sandbox.globalThis[sandbox.latestSetProp as number] as T);\n } else {\n // TODO support non sandbox mode?\n entryScriptLoadedDeferred.resolve({} as T);\n }\n };\n\n // defer scripts must wait until the entry HTML loaded\n const deferQueue: Array> = [];\n const { deferred: entryHTMLLoadedDeferred, queue: queueEntryHTMLDeferred } = prepareDeferredQueue(deferQueue);\n queueEntryHTMLDeferred();\n\n let readableStream = res.body.pipeThrough(new TextDecoderStream());\n\n if (streamTransformer) {\n readableStream = readableStream.pipeThrough(streamTransformer());\n }\n\n void readableStream\n .pipeThrough(\n createTagTransformStream(\n [\n { tag: '', alt: `<${qiankunHeadTagName}>` },\n { tag: '', alt: `` },\n // TODO support body replacement\n // { tag: 'body', alt: 'qiankun-body' },\n ],\n // { head: true },\n {},\n ),\n )\n .pipeTo(\n new WritableDOMStream(container, null, (clone) => {\n let transformerOpts: AssetsTranspilerOpts = {\n fetch,\n sandbox,\n };\n\n let queueDeferScript: () => void;\n const deferScriptMode = isDeferScript(clone as unknown as HTMLScriptElement);\n if (deferScriptMode) {\n const { deferred, prevDeferred, queue } = prepareDeferredQueue(deferQueue);\n transformerOpts = {\n ...transformerOpts,\n scriptTranspiledDeferred: deferred,\n prevScriptTranspiledDeferred: prevDeferred,\n } as ScriptTranspilerOpts;\n queueDeferScript = queue;\n }\n\n const transformedNode = nodeTransformer ? nodeTransformer(clone, transformerOpts) : clone;\n\n const script = transformedNode as unknown as HTMLScriptElement;\n\n // the script have no src attribute after transpile, indicating that the script needs to wait for the src to be filled\n if (deferScriptMode && !script.hasAttribute('src')) {\n queueDeferScript!();\n }\n\n /*\n * If the entry script is executed, we can complete the entry process in advance\n * otherwise we need to wait until the last script is executed.\n * Notice that we only support external script as entry script thus we could do resolve the promise after the script is loaded.\n */\n if (isEntryScript(script)) {\n if (foundEntryScript) {\n throw new QiankunError(\n `You should not include more than 1 entry scripts in a single HTML entry ${entryUrl} !`,\n );\n }\n\n foundEntryScript = true;\n\n const onScriptComplete = (\n prevListener: typeof HTMLScriptElement.prototype.onload | typeof HTMLScriptElement.prototype.onerror,\n event: Event,\n ) => {\n script.onload = script.onerror = null;\n\n // entryScriptLoadedDeferred not resolved or rejected yet\n if (!entryScriptLoadedDeferred.isSettled()) {\n if (event.type === 'load') {\n onEntryLoaded();\n } else {\n entryScriptLoadedDeferred.reject(\n new QiankunError(\n `Entry ${entryUrl} load failed as entry script ${script.dataset.src || script.src} execution failed`,\n ),\n );\n }\n }\n\n /*\n In order to avoid the inline script to be executed immediately after the prev onload is executed, resulting in the failure of the sandbox to obtain the latestSetProp\n here we must resolve the entryScriptLoadedDeferred firstly and then execute the prevListener\n */\n prevListener?.call(script, event);\n };\n\n script.onload = onScriptComplete.bind(null, script.onload);\n script.onerror = onScriptComplete.bind(null, script.onerror) as typeof HTMLScriptElement.prototype.onerror;\n }\n\n return transformedNode;\n }),\n )\n .then(() => {\n // while the entry html stream is finished but there is no entry script found\n // we could use the latest set prop in sandbox to resolve the entry promise as fallback\n if (!foundEntryScript) {\n onEntryLoaded();\n }\n\n entryHTMLLoadedDeferred.resolve();\n })\n .catch((e) => {\n entryScriptLoadedDeferred.reject(e);\n entryHTMLLoadedDeferred.reject(e);\n });\n\n return entryScriptLoadedDeferred.promise;\n }\n\n throw new QiankunError(`The response body of entry ${entryUrl} is empty!`);\n}\n" }, { "path": "packages/loader/src/parser.ts", "content": "type NormalizedEntry = {\n stylesheets: NodeListOf;\n scripts: NodeListOf;\n};\n\nfunction getDocResources(container: Document) {\n const links = container.querySelectorAll('link[rel=stylesheet][href]:not([href=\"\"])');\n const scripts = container.querySelectorAll('script[src]:not([src=\"\"])');\n\n return {\n scripts,\n stylesheets: links,\n };\n}\n\nexport function parseHTML(htmlContent: string): NormalizedEntry {\n const domParser = new DOMParser();\n const container = domParser.parseFromString(htmlContent, 'text/html');\n\n const resources = getDocResources(container);\n\n return resources;\n}\n" }, { "path": "packages/loader/src/utils.ts", "content": "export function isUrlHasOwnProtocol(url: string): boolean {\n const protocols = ['http://', 'https://', '//', 'blob:', 'data:'];\n return protocols.some((protocol) => url.startsWith(protocol));\n}\n" }, { "path": "packages/loader/src/writable-dom/README.md", "content": "# Fork from https://github.com/marko-js/writable-dom\n" }, { "path": "packages/loader/src/writable-dom/index.ts", "content": "type Writable = {\n write: (html: string) => void;\n abort: (err: Error) => void;\n close: () => Promise;\n};\n\nconst createHTMLDocument = () => document.implementation.createHTMLDocument('');\nlet createDocument = (target: ParentNode, nextSibling: ChildNode | null): Document => {\n const testDoc = createHTMLDocument();\n testDoc.write('',\n ),\n });\n\n // Mock navigator.onLine\n Object.defineProperty(window, 'navigator', {\n value: {\n onLine: true,\n connection: undefined,\n },\n writable: true,\n configurable: true,\n });\n\n // Mock requestIdleCallback\n vi.stubGlobal('requestIdleCallback', (cb: IdleRequestCallback) => {\n cb({ didTimeout: false, timeRemaining: () => 50 });\n return 1;\n });\n });\n\n afterEach(() => {\n vi.restoreAllMocks();\n vi.unstubAllGlobals();\n vi.resetModules();\n });\n\n it('should prefetch apps with given entries', async () => {\n const { prefetchApps } = await import('../prefetch');\n const apps = [\n { name: 'app1', entry: 'http://localhost:7100/' },\n { name: 'app2', entry: 'http://localhost:7200/' },\n ];\n\n prefetchApps(apps, mockFetch as unknown as typeof fetch);\n\n // Wait for async operations\n await new Promise((resolve) => setTimeout(resolve, 100));\n\n expect(mockFetch).toHaveBeenCalledWith('http://localhost:7100/');\n expect(mockFetch).toHaveBeenCalledWith('http://localhost:7200/');\n });\n\n it('should prefetch external scripts and stylesheets', async () => {\n const { prefetchApps } = await import('../prefetch');\n const apps = [{ name: 'app1', entry: 'http://localhost:7100/' }];\n\n prefetchApps(apps, mockFetch as unknown as typeof fetch);\n\n await new Promise((resolve) => setTimeout(resolve, 100));\n\n // Should fetch the HTML entry\n expect(mockFetch).toHaveBeenCalledWith('http://localhost:7100/');\n // Should also fetch external resources (script and stylesheet)\n expect(mockFetch).toHaveBeenCalledWith('http://localhost:7100/app.js');\n expect(mockFetch).toHaveBeenCalledWith('http://localhost:7100/style.css');\n });\n});\n" }, { "path": "packages/qiankun/src/apis/effects.ts", "content": "/**\n * @author Kuitos\n * @since 2019-02-19\n */\nimport { getMountedApps, navigateToUrl } from 'single-spa';\n\nconst firstMountLogLabel = '[qiankun] first app mounted';\nif (process.env.NODE_ENV === 'development') {\n // eslint-disable-next-line no-console\n console.time(firstMountLogLabel);\n}\n\n/**\n * Set default mount app, will navigate to the default app if no app is mounted\n * @param defaultAppLink - The default app route link\n */\nexport function setDefaultMountApp(defaultAppLink: string): void {\n // can not use addEventListener once option for ie support\n window.addEventListener('single-spa:no-app-change', function listener() {\n const mountedApps = getMountedApps();\n if (!mountedApps.length) {\n navigateToUrl(defaultAppLink);\n }\n\n window.removeEventListener('single-spa:no-app-change', listener);\n });\n}\n\n/**\n * Run a callback function after the first micro app is mounted\n * @param effect - The callback function to run\n */\nexport function runAfterFirstMounted(effect: () => void): void {\n // can not use addEventListener once option for ie support\n window.addEventListener('single-spa:first-mount', function listener() {\n if (process.env.NODE_ENV === 'development') {\n // eslint-disable-next-line no-console\n console.timeEnd(firstMountLogLabel);\n }\n\n effect();\n\n window.removeEventListener('single-spa:first-mount', listener);\n });\n}\n" }, { "path": "packages/qiankun/src/apis/errorHandler.ts", "content": "/**\n * @author Kuitos\n * @since 2020-02-21\n */\n\n// Re-export single-spa error handlers\nexport { addErrorHandler, removeErrorHandler } from 'single-spa';\n" }, { "path": "packages/qiankun/src/apis/isRuntimeCompatible.ts", "content": "export { isRuntimeCompatible } from '@qiankunjs/shared';\n" }, { "path": "packages/qiankun/src/apis/loadMicroApp.ts", "content": "import type { ParcelConfigObject } from 'single-spa';\nimport { mountRootParcel } from 'single-spa';\nimport type { ParcelConfigObjectGetter } from '../core/loadApp';\nimport loadApp from '../core/loadApp';\nimport type { AppConfiguration, LifeCycles, LoadableApp, MicroApp, ObjectType } from '../types';\nimport { getContainerXPath, toArray } from '../utils';\nimport { start, started } from './registerMicroApps';\n\nconst appConfigPromiseGetterMap = new Map>();\nconst containerMicroAppsMap = new Map();\n\nexport function loadMicroApp(\n app: LoadableApp,\n configuration?: AppConfiguration,\n lifeCycles?: LifeCycles,\n): MicroApp {\n const { props, name, container } = app;\n\n // Must compute the container xpath at beginning to keep it consist around app running\n // If we compute it every time, the container dom structure most probably been changed and result in a different xpath value\n const containerXPath = getContainerXPath(container);\n const getContainerXPathKey = (xpath: string) => `${name}-${xpath}`;\n\n let microApp: MicroApp;\n const wrapParcelConfigForRemount = (config: ParcelConfigObject): ParcelConfigObject => {\n let microAppConfig = config;\n if (containerXPath) {\n const appContainerXPathKey = getContainerXPathKey(containerXPath);\n const containerMicroApps = containerMicroAppsMap.get(appContainerXPathKey);\n if (containerMicroApps?.length) {\n const mount = [\n async () => {\n // While there are multiple micro apps mounted on the same container, we must wait until the prev instances all had unmounted\n // Otherwise it will lead some concurrent issues\n const prevLoadMicroApps = containerMicroApps.slice(0, containerMicroApps.indexOf(microApp));\n const prevLoadMicroAppsWhichNotBroken = prevLoadMicroApps.filter(\n (v) => v.getStatus() !== 'LOAD_ERROR' && v.getStatus() !== 'SKIP_BECAUSE_BROKEN',\n );\n await Promise.all(prevLoadMicroAppsWhichNotBroken.map((v) => v.unmountPromise));\n },\n ...toArray(microAppConfig.mount),\n ];\n\n microAppConfig = {\n ...config,\n mount,\n };\n }\n }\n\n return {\n ...microAppConfig,\n // empty bootstrap hook which should not run twice while it calling from cached micro app\n bootstrap: () => Promise.resolve(),\n };\n };\n\n /**\n * using name + container xpath as the micro app instance id,\n * it means if you're rendering a micro app to a dom which have been rendered before,\n * the micro app would not load and evaluate its lifecycles again\n */\n const memorizedLoadingFn = async (): Promise => {\n const userConfiguration = configuration;\n\n if (containerXPath) {\n const appContainerXPathKey = getContainerXPathKey(containerXPath);\n const parcelConfigGetterPromise = appConfigPromiseGetterMap.get(appContainerXPathKey);\n if (parcelConfigGetterPromise) return wrapParcelConfigForRemount((await parcelConfigGetterPromise)(container));\n }\n\n const parcelConfigObjectGetterPromise = loadApp(app, userConfiguration, lifeCycles);\n\n let parcelConfigObjectGetter: ParcelConfigObjectGetter | undefined;\n\n if (containerXPath) {\n const appContainerXPathKey = getContainerXPathKey(containerXPath);\n appConfigPromiseGetterMap.set(appContainerXPathKey, parcelConfigObjectGetterPromise);\n try {\n parcelConfigObjectGetter = await parcelConfigObjectGetterPromise;\n } catch (e) {\n appConfigPromiseGetterMap.delete(appContainerXPathKey);\n throw e;\n }\n }\n\n parcelConfigObjectGetter = parcelConfigObjectGetter || (await parcelConfigObjectGetterPromise);\n return parcelConfigObjectGetter(container);\n };\n\n if (!started) {\n // We need to invoke start method of single-spa as the popstate event should be dispatched while the main app calling pushState/replaceState automatically,\n // but in single-spa it will check the start status before it dispatch popstate\n // see https://github.com/single-spa/single-spa/blob/f28b5963be1484583a072c8145ac0b5a28d91235/src/navigation/navigation-events.js#L101\n // ref https://github.com/umijs/qiankun/pull/1071\n start();\n }\n\n microApp = mountRootParcel(memorizedLoadingFn, { domElement: document.createElement('div'), ...props });\n\n if (containerXPath) {\n const appContainerXPathKey = getContainerXPathKey(containerXPath);\n // Store the microApps which they mounted on the same container\n const microAppsRef = containerMicroAppsMap.get(appContainerXPathKey) || [];\n microAppsRef.push(microApp);\n containerMicroAppsMap.set(appContainerXPathKey, microAppsRef);\n\n const cleanup = () => {\n const index = microAppsRef.indexOf(microApp);\n microAppsRef.splice(index, 1);\n // eslint-disable-next-line @typescript-eslint/ban-ts-comment\n // @ts-ignore\n microApp = null;\n };\n\n // gc after unmount\n microApp.unmountPromise.then(cleanup).catch(cleanup);\n }\n\n return microApp;\n}\n" }, { "path": "packages/qiankun/src/apis/prefetch.ts", "content": "/**\n * @author Kuitos\n * @since 2019-02-26\n */\n\nimport type { AppMetadata } from '../types';\n\ndeclare global {\n interface NetworkInformation {\n saveData: boolean;\n effectiveType: string;\n type: 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';\n }\n\n interface Navigator {\n connection?: NetworkInformation;\n }\n}\n\n// RIC and shim for browsers without requestIdleCallback\nconst requestIdleCallback: typeof window.requestIdleCallback =\n typeof window.requestIdleCallback === 'function'\n ? window.requestIdleCallback.bind(window)\n : function requestIdleCallback(cb: IdleRequestCallback) {\n const start = Date.now();\n return setTimeout(() => {\n cb({\n didTimeout: false,\n timeRemaining() {\n return Math.max(0, 50 - (Date.now() - start));\n },\n });\n }, 1) as unknown as number;\n };\n\nconst isSlowNetwork = navigator.connection\n ? navigator.connection.saveData ||\n (navigator.connection.type !== 'wifi' &&\n navigator.connection.type !== 'ethernet' &&\n /([23])g/.test(navigator.connection.effectiveType))\n : false;\n\n/**\n * prefetch assets, do nothing while in mobile network\n * @param entry\n * @param fetch\n */\nasync function prefetch(entry: string, fetch: typeof window.fetch = window.fetch): Promise {\n if (!navigator.onLine || isSlowNetwork) {\n // Don't prefetch if in a slow network or offline\n return;\n }\n\n requestIdleCallback(() => {\n void (async () => {\n try {\n // Fetch the HTML entry to warm up the cache\n const response = await fetch(entry);\n const html = await response.text();\n\n // Parse HTML to find external resources\n const domParser = new DOMParser();\n const doc = domParser.parseFromString(html, 'text/html');\n\n // Prefetch external scripts\n const scripts = doc.querySelectorAll('script[src]');\n scripts.forEach((script) => {\n const src = script.getAttribute('src');\n if (src) {\n const absoluteSrc = new URL(src, entry).href;\n requestIdleCallback(() => {\n void fetch(absoluteSrc).catch(() => {\n // Ignore prefetch errors\n });\n });\n }\n });\n\n // Prefetch external stylesheets\n const links = doc.querySelectorAll('link[rel=\"stylesheet\"]');\n links.forEach((link) => {\n const href = link.getAttribute('href');\n if (href) {\n const absoluteHref = new URL(href, entry).href;\n requestIdleCallback(() => {\n void fetch(absoluteHref).catch(() => {\n // Ignore prefetch errors\n });\n });\n }\n });\n } catch (e) {\n // Ignore prefetch errors\n if (process.env.NODE_ENV === 'development') {\n // eslint-disable-next-line no-console\n console.warn('[qiankun] prefetch error:', e);\n }\n }\n })();\n });\n}\n\nexport type PrefetchStrategy =\n | boolean\n | 'all'\n | string[]\n | ((apps: AppMetadata[]) => { criticalAppNames: string[]; minorAppsName: string[] });\n\n/**\n * Prefetch micro apps immediately\n * @deprecated This API is deprecated in qiankun 3.0. Micro apps are streamed with automatic preload now.\n * @param apps - Apps to prefetch\n * @param fetch - Custom fetch function\n */\nexport function prefetchApps(apps: AppMetadata[], fetch: typeof window.fetch = window.fetch): void {\n if (process.env.NODE_ENV === 'development') {\n // eslint-disable-next-line no-console\n console.warn('[qiankun] prefetchApps is deprecated in 3.0; streaming loader performs automatic preload.');\n // eslint-disable-next-line no-console\n console.log('[qiankun] prefetch starting for apps...', apps);\n }\n\n apps.forEach(({ entry }) => {\n void prefetch(entry, fetch);\n });\n}\n" }, { "path": "packages/qiankun/src/apis/registerMicroApps.ts", "content": "import { Deferred } from '@qiankunjs/shared';\nimport { noop } from 'lodash';\nimport type { StartOpts } from 'single-spa';\nimport { registerApplication, start as startSingleSpa } from 'single-spa';\nimport loadApp from '../core/loadApp';\nimport type { AppConfiguration, LifeCycles, ObjectType, RegistrableApp } from '../types';\nimport { toArray } from '../utils';\n\nexport let started = false;\n\nexport const microApps: Array>> = [];\nconst frameworkConfiguration: AppConfiguration = {};\n\nconst frameworkStartedDefer = new Deferred();\n\nexport function registerMicroApps(apps: Array>, lifeCycles?: LifeCycles) {\n // Each app only needs to be registered once\n const unregisteredApps = apps.filter((app) => !microApps.some((registeredApp) => registeredApp.name === app.name));\n\n microApps.push(...unregisteredApps);\n\n unregisteredApps.forEach((app) => {\n const { name, activeRule, loader = noop, props, entry, container } = app;\n\n registerApplication({\n name,\n app: async () => {\n loader(true);\n await frameworkStartedDefer.promise;\n\n const { mount, ...otherMicroAppConfigs } = (\n await loadApp({ name, entry, container, props }, frameworkConfiguration, lifeCycles)\n )(container);\n\n return {\n mount: [async () => loader(true), ...toArray(mount), async () => loader(false)],\n ...otherMicroAppConfigs,\n };\n },\n activeWhen: activeRule,\n customProps: props,\n });\n });\n}\n\nexport function start(opts: StartOpts = {}) {\n if (!started) {\n // frameworkConfiguration = { prefetch: true, singular: true, sandbox: true, ...opts };\n // const { prefetch, urlRerouteOnly = defaultUrlRerouteOnly, ...importEntryOpts } = frameworkConfiguration;\n\n // if (prefetch) {\n // doPrefetchStrategy(microApps, prefetch, importEntryOpts);\n // }\n\n // frameworkConfiguration = autoDowngradeForLowVersionBrowser(frameworkConfiguration);\n\n startSingleSpa(opts);\n started = true;\n\n frameworkStartedDefer.resolve();\n }\n}\n" }, { "path": "packages/qiankun/src/core/loadApp.ts", "content": "/**\n * @author Kuitos\n * @since 2023-04-25\n */\nimport type { LoaderOpts } from '@qiankunjs/loader';\nimport { loadEntry } from '@qiankunjs/loader';\nimport type { Sandbox } from '@qiankunjs/sandbox';\nimport { createSandboxContainer, nativeGlobal } from '@qiankunjs/sandbox';\nimport {\n defineProperty,\n hasOwnProperty,\n makeFetchCacheable,\n makeFetchRetryable,\n makeFetchThrowable,\n moduleResolver as defaultModuleResolver,\n transpileAssets,\n warn,\n} from '@qiankunjs/shared';\nimport { concat, isFunction, mergeWith } from 'lodash';\nimport type { ParcelConfigObject } from 'single-spa';\nimport getAddOns from '../addons';\nimport { QiankunError } from '../error';\nimport type { AppConfiguration, LifeCycleFn, LifeCycles, LoadableApp, MicroAppLifeCycles, ObjectType } from '../types';\nimport {\n getPureHTMLStringWithoutScripts,\n performanceGetEntriesByName,\n performanceMark,\n performanceMeasure,\n toArray,\n} from '../utils';\nimport { version } from '../version';\n\nexport type ParcelConfigObjectGetter = (remountContainer: HTMLElement) => ParcelConfigObject;\n\nexport default async function loadApp(\n app: LoadableApp,\n configuration?: AppConfiguration,\n lifeCycles?: LifeCycles,\n): Promise {\n const { name: appName, entry, container } = app;\n const defaultNodeTransformer: AppConfiguration['nodeTransformer'] = (node, opts) => {\n const moduleResolver = (url: string) => defaultModuleResolver(url, microAppDOMContainer, document.head);\n return transpileAssets(node, entry, { ...opts, moduleResolver });\n };\n const {\n fetch = window.fetch,\n sandbox = true,\n globalContext = window,\n nodeTransformer = defaultNodeTransformer,\n ...restConfiguration\n } = configuration || {};\n\n const enhancedFetch = makeFetchCacheable(makeFetchRetryable(makeFetchThrowable(fetch)));\n\n const markName = `[qiankun] App ${appName} Loading`;\n if (process.env.NODE_ENV === 'development') {\n performanceMark(markName);\n }\n\n let global = globalContext;\n let mountSandbox: (container: HTMLElement) => Promise = () => Promise.resolve();\n let unmountSandbox = () => Promise.resolve();\n let sandboxInstance: Sandbox | undefined;\n const instanceId = genInstanceId(appName);\n let mountTimes = 1;\n\n let microAppDOMContainer: HTMLElement = container;\n initContainer(microAppDOMContainer, appName, { sandboxCfg: sandbox, mountTimes, instanceId });\n\n if (sandbox) {\n const sandboxContainer = createSandboxContainer(appName, () => microAppDOMContainer, {\n globalContext,\n extraGlobals: {},\n fetch: enhancedFetch,\n nodeTransformer,\n });\n\n sandboxInstance = sandboxContainer.instance;\n global = sandboxInstance.globalThis;\n\n mountSandbox = (domContainer) => sandboxContainer.mount(domContainer);\n unmountSandbox = () => sandboxContainer.unmount();\n }\n\n if (instanceId > 1) {\n removeWebpackChunkCacheWhenAppHaveMultiInstance(appName);\n }\n\n const containerOpts: LoaderOpts = {\n fetch: enhancedFetch,\n sandbox: sandboxInstance,\n nodeTransformer,\n ...restConfiguration,\n };\n const lifecyclesPromise = loadEntry(entry, microAppDOMContainer, containerOpts);\n\n const assetPublicPath = calcPublicPath(entry);\n const {\n beforeUnmount = [],\n afterUnmount = [],\n afterMount = [],\n beforeMount = [],\n beforeLoad = [],\n } = mergeWith({}, getAddOns(global, assetPublicPath), lifeCycles, (v1, v2) =>\n concat((v1 ?? []) as LifeCycleFn, (v2 ?? []) as LifeCycleFn),\n );\n // FIXME Due to the asynchronous execution of loadEntry, the DOM of the sub-app is inserted synchronously through appendChild, and inline scripts are also executed synchronously. Therefore, the beforeLoad may need to rely on transformer configuration to coordinate and ensure the order of asynchronous operations.\n await execHooksChain(toArray(beforeLoad), app, global);\n\n const lifecycles = await lifecyclesPromise;\n const { bootstrap, mount, unmount, update } = getLifecyclesFromExports(\n lifecycles,\n appName,\n global,\n sandboxInstance?.latestSetProp,\n );\n\n return (mountContainer) => {\n const parcelConfig: ParcelConfigObject = {\n name: appName,\n\n // eslint-disable-next-line @typescript-eslint/ban-ts-comment\n // @ts-ignore\n bootstrap,\n\n mount: [\n async () => {\n if (process.env.NODE_ENV === 'development') {\n const marks = performanceGetEntriesByName(markName, 'mark');\n // mark length is zero means the app is remounting\n if (marks && !marks.length) {\n performanceMark(markName);\n }\n }\n },\n async () => {\n microAppDOMContainer = mountContainer;\n\n // while the micro app is remounting, we need to load the entry manually\n if (mountTimes > 1) {\n initContainer(mountContainer, appName, { sandboxCfg: sandbox, mountTimes, instanceId });\n // html scripts should be removed to avoid repeatedly execute\n const htmlString = await getPureHTMLStringWithoutScripts(entry, enhancedFetch);\n await loadEntry(\n { url: entry, res: new Response(htmlString, { status: 200, statusText: 'OK' }) },\n mountContainer,\n containerOpts,\n );\n }\n },\n async () => {\n await mountSandbox(mountContainer);\n },\n // exec the chain after rendering to keep the behavior with beforeLoad\n async () => execHooksChain(toArray(beforeMount), app, global),\n async (props) => mount({ ...props, container: mountContainer }),\n // finish loading after app mounted\n async () => execHooksChain(toArray(afterMount), app, global),\n async () => {\n if (process.env.NODE_ENV === 'development') {\n const measureName = `[qiankun] App ${appName} Loading Consuming`;\n performanceMeasure(measureName, markName);\n }\n },\n async () => {\n mountTimes++;\n },\n ],\n\n unmount: [\n async () => execHooksChain(toArray(beforeUnmount), app, global),\n async (props) => unmount({ ...props, container: mountContainer }),\n unmountSandbox,\n async () => execHooksChain(toArray(afterUnmount), app, global),\n async () => {\n clearContainer(mountContainer);\n },\n ],\n };\n\n if (typeof update === 'function') {\n // eslint-disable-next-line @typescript-eslint/ban-ts-comment\n // @ts-ignore\n parcelConfig.update = update;\n }\n\n return parcelConfig;\n };\n}\n\nfunction initContainer(\n container: HTMLElement,\n appName: string,\n opts: { sandboxCfg: AppConfiguration['sandbox']; mountTimes: number; instanceId: number },\n): void {\n const { sandboxCfg, mountTimes, instanceId } = opts;\n while (container.firstChild) {\n container.removeChild(container.firstChild);\n }\n\n container.dataset.name = appName;\n container.dataset.version = version;\n container.dataset.sandboxCfg = JSON.stringify(sandboxCfg);\n\n if (mountTimes > 1) {\n container.dataset.mountTimes = String(mountTimes);\n }\n if (instanceId > 1) {\n container.dataset.instanceId = String(instanceId);\n }\n}\n\nfunction clearContainer(container: HTMLElement): void {\n while (container.firstChild) {\n container.removeChild(container.firstChild);\n }\n}\n\nfunction execHooksChain(\n hooks: Array>,\n app: LoadableApp,\n global: WindowProxy = window,\n): Promise {\n if (hooks.length) {\n return hooks.reduce((chain, hook) => chain.then(() => hook(app, global)), Promise.resolve());\n }\n\n return Promise.resolve();\n}\n\nfunction getLifecyclesFromExports(\n scriptExports: MicroAppLifeCycles | undefined,\n appName: string,\n globalContext: WindowProxy,\n globalLatestSetProp?: PropertyKey,\n): MicroAppLifeCycles {\n const validateExportLifecycle = (exports: ObjectType | undefined): exports is MicroAppLifeCycles => {\n const { bootstrap, mount, unmount } = exports ?? {};\n return isFunction(bootstrap) && isFunction(mount) && isFunction(unmount);\n };\n\n if (validateExportLifecycle(scriptExports)) {\n return scriptExports;\n }\n\n // fallback to sandbox latest set property if it had\n if (globalLatestSetProp) {\n const lifecycles = (globalContext as unknown as ObjectType)[globalLatestSetProp as never] as MicroAppLifeCycles;\n if (validateExportLifecycle(lifecycles)) {\n return lifecycles;\n }\n }\n\n if (process.env.NODE_ENV === 'development') {\n warn(`lifecycle not found from ${appName} entry exports, fallback to get from window['${appName}']`);\n }\n\n // fallback to globalContext variable who named with ${appName} while module exports not found\n const globalVariableExports = (globalContext as unknown as ObjectType)[appName as never] as MicroAppLifeCycles;\n\n if (validateExportLifecycle(globalVariableExports)) {\n return globalVariableExports;\n }\n\n throw new QiankunError(\n `You need to export lifecycle functions in ${appName} entry as neither globalLatestSetProp ${String(\n globalLatestSetProp,\n )} nor window['${appName}'] export correctly`,\n );\n}\n\nfunction calcPublicPath(entry: string): string {\n try {\n const { origin, pathname } = new URL(entry, location.href);\n const paths = pathname.split('/');\n paths.pop();\n return `${origin}${paths.join('/')}/`;\n } catch (e) {\n console.warn(e);\n return '';\n }\n}\n\n/**\n * To prevent webpack from skipping reload logic and causing the js not to re-execute when a micro app is loaded multiple times on the same viewport,\n * the data-webpack attribute of the script must be removed.\n * see https://github.com/webpack/webpack/blob/1f13ff9fe587e094df59d660b4611b1bd19aed4c/lib/runtime/LoadScriptRuntimeModule.js#L131-L136\n */\nfunction removeWebpackChunkCacheWhenAppHaveMultiInstance(appName: string): void {\n const mountedSameNameApps = document.querySelectorAll(`[data-name^=\"${appName}\"]`);\n if (mountedSameNameApps.length > 1) {\n mountedSameNameApps.forEach((appContainerElement) => {\n appContainerElement.querySelectorAll('script[src]').forEach((script) => {\n script.removeAttribute('data-webpack');\n });\n });\n }\n}\n\nconst globalAppInstanceStoreKey = '__agii__';\ndeclare global {\n interface Window {\n // app global instance id\n [globalAppInstanceStoreKey]?: Record;\n }\n}\n\nfunction genInstanceId(appName: string): number {\n if (!hasOwnProperty(nativeGlobal, globalAppInstanceStoreKey)) {\n defineProperty(nativeGlobal, globalAppInstanceStoreKey, {\n enumerable: false,\n configurable: false,\n writable: true,\n value: {},\n });\n }\n nativeGlobal[globalAppInstanceStoreKey]![appName] = nativeGlobal[globalAppInstanceStoreKey]![appName]\n ? nativeGlobal[globalAppInstanceStoreKey]![appName] + 1\n : 1;\n return nativeGlobal[globalAppInstanceStoreKey]![appName];\n}\n" }, { "path": "packages/qiankun/src/error.ts", "content": "export class QiankunError extends Error {\n constructor(message: string) {\n super(`[qiankun]: ${message}`);\n }\n}\n" }, { "path": "packages/qiankun/src/index.ts", "content": "export * from './apis/loadMicroApp';\nexport * from './apis/registerMicroApps';\nexport * from './apis/isRuntimeCompatible';\nexport * from './apis/prefetch';\nexport * from './apis/effects';\nexport * from './apis/errorHandler';\nexport * from './types';\n" }, { "path": "packages/qiankun/src/types.ts", "content": "/**\n * @author Kuitos\n * @since 2023-04-25\n */\nimport type { LoaderOpts } from '@qiankunjs/loader';\nimport type { LifeCycles as ParcelLifeCycles, Parcel, RegisterApplicationConfig } from 'single-spa';\n\ndeclare global {\n // eslint-disable-next-line @typescript-eslint/consistent-type-definitions\n interface Window {\n __POWERED_BY_QIANKUN__?: boolean;\n __INJECTED_PUBLIC_PATH_BY_QIANKUN__?: string;\n __QIANKUN_DEVELOPMENT__?: boolean;\n Zone?: CallableFunction;\n __zone_symbol__setTimeout?: Window['setTimeout'];\n }\n}\n\nexport type ObjectType = Record;\n\nexport type HTMLEntry = string;\n\nexport type AppMetadata = {\n // app name\n name: string;\n // app entry\n entry: HTMLEntry;\n};\n\n// just for manual loaded apps, in single-spa it called parcel\nexport type LoadableApp = AppMetadata & {\n // where the app mount to\n container: HTMLElement;\n // props pass to app\n props?: T;\n};\n\n// for the route-based apps\nexport type RegistrableApp = LoadableApp & {\n loader?: (loading: boolean) => void;\n activeRule: RegisterApplicationConfig['activeWhen'];\n};\n\nexport type AppConfiguration = Partial> & {\n sandbox?: boolean;\n globalContext?: WindowProxy;\n};\n\nexport type LifeCycleFn = (app: LoadableApp, global: WindowProxy) => Promise;\nexport type LifeCycles = {\n beforeLoad?: LifeCycleFn | Array>; // function before app load\n beforeMount?: LifeCycleFn | Array>; // function before app mount\n afterMount?: LifeCycleFn | Array>; // function after app mount\n beforeUnmount?: LifeCycleFn | Array>; // function before app unmount\n afterUnmount?: LifeCycleFn | Array>; // function after app unmount\n};\n\nexport type MicroApp = Parcel;\n\ntype ExtraProps = {\n container: HTMLElement;\n};\ntype FlattenArray = T extends Array ? U : T;\ntype FlattenArrayValue = {\n [P in keyof T]: FlattenArray;\n};\n\nexport type MicroAppLifeCycles = FlattenArrayValue>;\n" }, { "path": "packages/qiankun/src/utils.ts", "content": "/**\n * @author Kuitos\n * @since 2023-04-25\n */\nexport function toArray(array: T | T[]): T[] {\n return Array.isArray(array) ? array : [array];\n}\n\n/**\n * copy from https://developer.mozilla.org/zh-CN/docs/Using_XPath\n * @param el\n * @param document\n */\nfunction getXPathForElement(el: Node, document: Document): string | void {\n // not support that if el not existed in document yet(such as it not append to document before it mounted)\n if (!document.body.contains(el)) {\n return undefined;\n }\n\n let xpath = '';\n let pos;\n let tmpEle;\n let element = el;\n\n while (element !== document.documentElement) {\n pos = 0;\n tmpEle = element;\n while (tmpEle) {\n if (tmpEle.nodeType === 1 && tmpEle.nodeName === element.nodeName) {\n // If it is ELEMENT_NODE of the same name\n pos += 1;\n }\n tmpEle = tmpEle.previousSibling;\n }\n\n xpath = `*[name()='${element.nodeName}'][${pos}]/${xpath}`;\n\n element = element.parentNode!;\n }\n\n xpath = `/*[name()='${document.documentElement.nodeName}']/${xpath}`;\n xpath = xpath.replace(/\\/$/, '');\n\n return xpath;\n}\n\nexport function getContainerXPath(container: HTMLElement): string | void {\n return getXPathForElement(container, document);\n}\n\nconst supportsUserTiming =\n typeof performance !== 'undefined' &&\n typeof performance.mark === 'function' &&\n typeof performance.clearMarks === 'function' &&\n typeof performance.measure === 'function' &&\n typeof performance.clearMeasures === 'function' &&\n typeof performance.getEntriesByName === 'function';\n\nexport function performanceGetEntriesByName(markName: string, type?: string) {\n let marks = null;\n if (supportsUserTiming) {\n marks = performance.getEntriesByName(markName, type);\n }\n return marks;\n}\n\nexport function performanceMark(markName: string) {\n if (supportsUserTiming) {\n performance.mark(markName);\n }\n}\n\nexport function performanceMeasure(measureName: string, markName: string) {\n if (supportsUserTiming && performance.getEntriesByName(markName, 'mark').length) {\n performance.measure(measureName, markName);\n performance.clearMarks(markName);\n performance.clearMeasures(measureName);\n }\n}\n\nexport async function getPureHTMLStringWithoutScripts(entry: string, fetch: typeof window.fetch): Promise {\n const htmlString = await fetch(entry).then((r) => r.text());\n\n const domParser = new DOMParser();\n const htmlDOM = domParser.parseFromString(htmlString, 'text/html');\n // remove all script tags who are been loaded before\n htmlDOM.querySelectorAll('script').forEach((script) => script.remove());\n htmlDOM.querySelectorAll('link[rel=prefetch],link[rel=preload]').forEach((link) => link.remove());\n\n return htmlDOM.documentElement.outerHTML;\n}\n" }, { "path": "packages/sandbox/.fatherrc.js", "content": "import { writeFileSync } from 'fs';\nimport globals from 'globals';\nimport { join } from 'path';\n\nconsole.log('generate globals.ts...');\n// generate globals.ts\nconst globalsFilePath = join(__dirname, './src/core/globals.ts');\nwriteFileSync(\n globalsFilePath,\n `// generated from https://github.com/sindresorhus/globals/blob/main/globals.json es2015 part\n// only init its values while Proxy is supported\n// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\nexport const globalsInES2015 = window.Proxy ? ${JSON.stringify(\n Object.keys(globals.es2015),\n null,\n 2,\n )}.filter(p => /* just keep the available properties in current window context */ p in window) : [];\n\nexport const globalsInBrowser = ${JSON.stringify(Object.keys(globals.browser), null, 2)};\n `,\n);\n\nconsole.log('generate globals.ts succeed...');\n\nexport { default } from '../../.fatherrc.cjs';\n" }, { "path": "packages/sandbox/AGENTS.md", "content": "# @qiankunjs/sandbox\n\nJS isolation engine using Proxy-based Membrane + Compartment execution model.\n\n## STRUCTURE\n\n```\nsandbox/\n├── core/\n│ ├── sandbox/ # StandardSandbox, createSandboxContainer\n│ ├── membrane/ # Proxy wrapper for global isolation\n│ ├── compartment/ # Code evaluation with `with(this)` binding\n│ └── globals.ts # Global property definitions\n├── patchers/\n│ ├── dynamicAppend/ # DOM appendChild/insertBefore interception\n│ ├── windowListener.ts # Event listener tracking\n│ ├── interval.ts # Timer tracking\n│ └── historyListener.ts\n└── consts.ts # qiankunHeadTagName, etc.\n```\n\n## WHERE TO LOOK\n\n| Task | File | Notes |\n| --- | --- | --- |\n| Create sandbox | `core/sandbox/index.ts` | `createSandboxContainer()` returns mount/unmount |\n| Proxy logic | `core/membrane/index.ts` | Write → local target, Read → target → endowments → host |\n| Code execution | `core/compartment/index.ts` | `with(this)` scope binding |\n| DOM interception | `patchers/dynamicAppend/forStandardSandbox.ts` | Redirects to app container |\n| Side effect cleanup | `patchers/*.ts` | Each returns `free()` function |\n\n## KEY PATTERNS\n\n### Membrane (Proxy)\n\n- **Writes**: Trapped and stored in local `target` object\n- **Reads**: Check local → endowments → fallback to host window\n- **Native rebinding**: `fetch`, `console` rebound to avoid \"Illegal invocation\"\n\n### Patcher/Free Pattern\n\n```typescript\n// Every patcher returns cleanup function\nconst free = patchWindowListener(sandbox);\n// On unmount:\nfree(); // Removes all listeners added by micro-app\n```\n\n### WeakMap Metadata\n\n- `sandboxConfigWeakMap`: Sandbox config per instance\n- `elementAttachSandboxConfigMap`: Tracks which app owns which DOM node\n\n## ANTI-PATTERNS\n\n- **NEVER** access real `window.document.head` directly - use proxied version\n- **FIXME**: Indirect `eval` in membrane causes System.js scope escape\n- **FIXME**: Global variable for runtime container may miss monkey-patched logic\n\n## EXPORTS\n\n```typescript\nexport { createSandboxContainer } from './core/sandbox';\nexport { StandardSandbox } from './core/sandbox/StandardSandbox';\nexport { Compartment } from './core/compartment';\nexport { qiankunHeadTagName } from './consts';\n```\n" }, { "path": "packages/sandbox/CHANGELOG.md", "content": "# @qiankunjs/sandbox\n\n## 0.0.1-rc.17\n\n### Patch Changes\n\n- 9c56910: feat: support addEventListener with once options to avoid memory leak\n- 6d252c6: chore: optimize code\n- Updated dependencies [ea18ce6]\n - @qiankunjs/shared@0.0.1-rc.12\n\n## 0.0.1-rc.16\n\n### Patch Changes\n\n- 99bf65f: feat: support huge inline-script who might be split into multiple chunks during transfer\n- Updated dependencies [56fef69]\n- Updated dependencies [99bf65f]\n - @qiankunjs/shared@0.0.1-rc.11\n\n## 0.0.1-rc.15\n\n### Patch Changes\n\n- c3416647: fix: double quote link element href as selector\n\n## 0.0.1-rc.14\n\n### Patch Changes\n\n- 8c526255: Revert \"fix(sandbox): non-hijacking elements should be appended to global document (#2861)\"\n\n## 0.0.1-rc.13\n\n### Patch Changes\n\n- f09c1538: feat: pass container with parameters rather than getter function\n- d904f5d8: fix(sandbox): compatible with dynamically appending stylesheets to detached containers\n- b2d2c11a: feat: optimize lifecycle validate log\n- feb544f0: fix: dynamic append element should support for the same container between micro apps\n- 9082546e: fix(sandbox): compatible with dynamically appending scripts to detached containers\n- 62048537: fix(sandbox): non-hijacking elements should be appended to global document\n- Updated dependencies [a826cf5e]\n- Updated dependencies [3e43a111]\n- Updated dependencies [feb544f0]\n - @qiankunjs/shared@0.0.1-rc.10\n\n## 0.0.1-rc.12\n\n### Patch Changes\n\n- bd12dbad: fix: defer scripts should wait until html loaded\n- Updated dependencies [bd12dbad]\n - @qiankunjs/shared@0.0.1-rc.9\n\n## 0.0.1-rc.11\n\n### Patch Changes\n\n- 98b071bf: feat: support defer scripts and keep the executing order to consist with browser\n- Updated dependencies [98b071bf]\n - @qiankunjs/shared@0.0.1-rc.8\n\n## 0.0.1-rc.10\n\n### Patch Changes\n\n- f2af2e36: feat: extract NodeTransformer type to shared package\n- Updated dependencies [f2af2e36]\n - @qiankunjs/shared@0.0.1-rc.7\n\n## 0.0.1-rc.9\n\n### Patch Changes\n\n- d3e9872d: feat(sandbox): use cloneNode api instead of importNode for compatible\n- 7cc06bd4: feat(loader): add lru cache for assets fetch by default\n- Updated dependencies [54b0878e]\n- Updated dependencies [7ba95cf2]\n- Updated dependencies [312abbc7]\n- Updated dependencies [6f074136]\n - @qiankunjs/shared@0.0.1-rc.6\n\n## 0.0.1-rc.8\n\n### Patch Changes\n\n- 43bf37a5: fix(sandbox): should get container from getter function in every accessing\n- a34a92a9: feat(sandbox): micro app mounting should wait unit rebuilding link element loaded to avoid unstyleed content flash\n- 7cf93b54: fix(sandbox): createElement hijack must be paired to avoid rewriting leak\n- 32106b11: fix(sandbox): dynamic async script order should calculate on the fly\n\n## 0.0.1-rc.7\n\n### Patch Changes\n\n- 5f77347b: feat(sandbox): support dynamic sync scripts executed by order in sandbox\n- Updated dependencies [5f77347b]\n- Updated dependencies [8e54e129]\n - @qiankunjs/shared@0.0.1-rc.5\n\n## 0.0.1-rc.6\n\n### Patch Changes\n\n- 2aca545c: fix: should invoke getContainer method to get container every time to avoid reference misordering\n\n## 0.0.1-rc.5\n\n### Patch Changes\n\n- 3d1d3367: fix: should patch the container head/body element immediately rather than patch its functions with proxy\n\n## 0.0.1-rc.4\n\n### Patch Changes\n\n- 488447ad: ✨ set proxy appendChild/insertBefore method for every sandbox rather than modify prototype on HTMLElement\n- dc4d9aef: 🐛parallel sandbox should use different compartment id\n- e7d788ef: feat: not rebind non-native global properties\n- 76b6bff7: 🐛 compatible with webpack chunk cache logic\n- Updated dependencies [76b6bff7]\n - @qiankunjs/shared@0.0.1-rc.4\n\n## 0.0.1-rc.3\n\n### Patch Changes\n\n- 39301f19: 🔀 merge master\n - @qiankunjs/shared@0.0.1-rc.3\n\n## 0.0.1-rc.2\n\n### Patch Changes\n\n- Updated dependencies [b23d3d7b]\n - @qiankunjs/shared@0.0.1-rc.2\n\n## 0.0.1-rc.1\n\n### Patch Changes\n\n- Updated dependencies [ebb2bcaa]\n - @qiankunjs/shared@0.0.1-rc.1\n\n## 0.0.1-beta.6\n\n### Patch Changes\n\n- ffd77800: ✨support to transform head/body tags to qiankun head/body in stream\n- Updated dependencies [ffd77800]\n - @qiankunjs/shared@0.0.1-beta.6\n\n## 0.0.1-alpha.5\n\n### Patch Changes\n\n- Updated dependencies [fcb49aad]\n- Updated dependencies [065d2c54]\n- Updated dependencies [931dc1f7]\n - @qiankunjs/shared@0.0.1-alpha.5\n\n## 0.0.1-alpha.4\n\n### Patch Changes\n\n- Updated dependencies [62d3b482]\n - @qiankunjs/shared@0.0.1-alpha.4\n\n## 0.0.1-alpha.3\n\n### Patch Changes\n\n- daaa9ccc: ✨support code block in sandbox\n- Updated dependencies [e12d29ae]\n- Updated dependencies [daaa9ccc]\n - @qiankunjs/shared@0.0.1-alpha.3\n\n## 0.0.1-alpha.2\n\n### Patch Changes\n\n- 33e65888: fix: changeset\n- Updated dependencies [33e65888]\n - @qiankunjs/shared@0.0.1-alpha.2\n\n## 0.0.1-alpha.1\n\n### Patch Changes\n\n- Updated dependencies\n - @qiankunjs/shared@0.0.1-alpha.1\n\n## 0.0.1-alpha.0\n\n### Patch Changes\n\n- 3.0 alpha\n- Updated dependencies\n - @qiankunjs/shared@0.0.1-alpha.0\n" }, { "path": "packages/sandbox/package.json", "content": "{\n \"name\": \"@qiankunjs/sandbox\",\n \"version\": \"0.0.1-rc.17\",\n \"description\": \"qiankun sandbox\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/umijs/qiankun.git\"\n },\n \"main\": \"./dist/cjs/index.js\",\n \"module\": \"./dist/esm/index.js\",\n \"types\": \"./dist/esm/index.d.ts\",\n \"sideEffects\": false,\n \"scripts\": {\n \"build\": \"father build\"\n },\n \"files\": [\n \"dist\"\n ],\n \"author\": \"Kuitos\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@babel/runtime\": \"^7.26.10\",\n \"@qiankunjs/shared\": \"workspace:^\",\n \"lodash\": \"^4.17.11\"\n },\n \"devDependencies\": {\n \"globals\": \"^13.20.0\"\n },\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\"\n }\n}\n" }, { "path": "packages/sandbox/src/consts.ts", "content": "/**\n * @author Kuitos\n * @since 2023-03-16\n */\n\nexport const nativeGlobal = document.defaultView!;\n\nexport const nativeDocument = nativeGlobal.document;\n\nexport const qiankunHeadTagName = 'qiankun-head';\nexport const qiankunBodyTagName = 'qiankun-body';\n" }, { "path": "packages/sandbox/src/core/compartment/globalProps.ts", "content": "import { hasOwnProperty } from '@qiankunjs/shared';\n\nlet firstGlobalProp: string | undefined, secondGlobalProp: string | undefined, lastGlobalProp: string | undefined;\n\nexport function getGlobalProp(global: WindowProxy, useFirstGlobalProp = false) {\n let cnt = 0;\n let foundLastProp, result;\n let hasIframe = false;\n for (const p in global) {\n // do not check frames because it could be removed during import\n if (shouldSkipProperty(global, p)) continue;\n\n // 遍历 iframe，检查 window 上的属性值是否是 iframe，是则跳过后面的 first 和 second 判断\n for (let i = 0; i < window.frames.length && !hasIframe; i++) {\n const frame = window.frames[i];\n if (frame === global[p as unknown as number]) {\n hasIframe = true;\n break;\n }\n }\n\n if ((!hasIframe && cnt === 0 && p !== firstGlobalProp) || (cnt === 1 && p !== secondGlobalProp)) return p;\n if (foundLastProp) {\n lastGlobalProp = p;\n result = (useFirstGlobalProp && result) || p;\n } else {\n foundLastProp = p === lastGlobalProp;\n }\n cnt++;\n }\n return result;\n}\n\nexport function noteGlobalProps(global: WindowProxy) {\n // alternatively Object.keys(global).pop()\n // but this may be faster (pending benchmarks)\n firstGlobalProp = secondGlobalProp = undefined;\n for (const p in global) {\n // do not check frames because it could be removed during import\n if (shouldSkipProperty(global, p)) continue;\n if (!firstGlobalProp) firstGlobalProp = p;\n else if (!secondGlobalProp) secondGlobalProp = p;\n lastGlobalProp = p;\n }\n\n return lastGlobalProp;\n}\n\nconst isIE11 = () => typeof navigator !== 'undefined' && navigator.userAgent.indexOf('Trident') !== -1;\nfunction shouldSkipProperty(global: WindowProxy, p: string | number): boolean {\n if (!hasOwnProperty(global, p) || (!isNaN(p as number) && (p as number) < global.length)) return true;\n\n if (isIE11()) {\n // https://github.com/kuitos/import-html-entry/pull/32，最小化 try 范围\n try {\n return !!global[p as keyof WindowProxy] && typeof window !== 'undefined' && global[p as number].parent === window;\n } catch (err) {\n return true;\n }\n } else {\n return false;\n }\n}\n" }, { "path": "packages/sandbox/src/core/compartment/index.ts", "content": "// type Transform = (source: string) => string;\n// type ModuleMap = Record;\n//\n// interface CompartmentOptions {\n// transforms?: Transform[];\n// }\n\nimport { nativeGlobal } from '../../consts';\n\nconst compartmentGlobalIdPrefix = '__compartment_globalThis__';\nconst compartmentGlobalIdSuffix = '__';\nconst getCompartmentGlobalId = (id: number): CompartmentGlobalId =>\n `${compartmentGlobalIdPrefix}${String(id)}${compartmentGlobalIdSuffix}`;\ntype CompartmentGlobalId = `${typeof compartmentGlobalIdPrefix}${string}${typeof compartmentGlobalIdSuffix}`;\n\ndeclare global {\n interface Window {\n [p: CompartmentGlobalId]: WindowProxy | undefined;\n }\n}\n\nlet compartmentCounter = 0;\n\nexport class Compartment {\n /**\n * Since the time of execution of the code in Compartment is determined by the browser, a unique compartmentSpecifier should be generated in Compartment\n */\n private readonly id: CompartmentGlobalId;\n\n private readonly _globalThis: WindowProxy;\n\n private constantIntrinsicNames: string[] = [];\n\n constructor(globalProxy: WindowProxy) {\n this._globalThis = globalProxy;\n\n // make sure the compartmentSpecifier is unique\n while (nativeGlobal[getCompartmentGlobalId(compartmentCounter)]) {\n compartmentCounter++;\n }\n this.id = getCompartmentGlobalId(compartmentCounter);\n nativeGlobal[this.id] = globalProxy;\n }\n\n get globalThis(): WindowProxy {\n return this._globalThis;\n }\n\n protected addConstantIntrinsicNames(intrinsics: string[]): void {\n this.constantIntrinsicNames = [...intrinsics, ...this.constantIntrinsicNames];\n }\n\n makeEvaluateFactory(source: string, sourceURL?: string): string {\n const sourceMapURL = sourceURL ? `//# sourceURL=${sourceURL}\\n` : '';\n\n const globalObjectOptimizer = this.constantIntrinsicNames.length\n ? `const {${this.constantIntrinsicNames.join(',')}} = this;`\n : '';\n\n // eslint-disable-next-line max-len\n return `;(function(){with(this){${globalObjectOptimizer}${source}\\n${sourceMapURL}}}).bind(window.${this.id})();`;\n }\n\n // TODO add return value\n // evaluate(code: string, options?: CompartmentOptions): void {\n // const { transforms } = options || {};\n // const transformedCode = transforms?.reduce((acc, transform) => transform(acc), code) || code;\n // const codeFactory = this.makeEvaluateFactory(transformedCode);\n //\n // const script = document.createElement('script');\n // script.textContent = codeFactory;\n // document.head.appendChild(script);\n // }\n}\n" }, { "path": "packages/sandbox/src/core/globals.ts", "content": "// generated from https://github.com/sindresorhus/globals/blob/main/globals.json es2015 part\n// only init its values while Proxy is supported\n// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\nexport const globalsInES2015 = window.Proxy ? [\n \"Array\",\n \"ArrayBuffer\",\n \"Boolean\",\n \"constructor\",\n \"DataView\",\n \"Date\",\n \"decodeURI\",\n \"decodeURIComponent\",\n \"encodeURI\",\n \"encodeURIComponent\",\n \"Error\",\n \"escape\",\n \"eval\",\n \"EvalError\",\n \"Float32Array\",\n \"Float64Array\",\n \"Function\",\n \"hasOwnProperty\",\n \"Infinity\",\n \"Int16Array\",\n \"Int32Array\",\n \"Int8Array\",\n \"isFinite\",\n \"isNaN\",\n \"isPrototypeOf\",\n \"JSON\",\n \"Map\",\n \"Math\",\n \"NaN\",\n \"Number\",\n \"Object\",\n \"parseFloat\",\n \"parseInt\",\n \"Promise\",\n \"propertyIsEnumerable\",\n \"Proxy\",\n \"RangeError\",\n \"ReferenceError\",\n \"Reflect\",\n \"RegExp\",\n \"Set\",\n \"String\",\n \"Symbol\",\n \"SyntaxError\",\n \"toLocaleString\",\n \"toString\",\n \"TypeError\",\n \"Uint16Array\",\n \"Uint32Array\",\n \"Uint8Array\",\n \"Uint8ClampedArray\",\n \"undefined\",\n \"unescape\",\n \"URIError\",\n \"valueOf\",\n \"WeakMap\",\n \"WeakSet\"\n].filter(p => /* just keep the available properties in current window context */ p in window) : [];\n\nexport const globalsInBrowser = [\n \"AbortController\",\n \"AbortSignal\",\n \"addEventListener\",\n \"alert\",\n \"AnalyserNode\",\n \"Animation\",\n \"AnimationEffectReadOnly\",\n \"AnimationEffectTiming\",\n \"AnimationEffectTimingReadOnly\",\n \"AnimationEvent\",\n \"AnimationPlaybackEvent\",\n \"AnimationTimeline\",\n \"applicationCache\",\n \"ApplicationCache\",\n \"ApplicationCacheErrorEvent\",\n \"atob\",\n \"Attr\",\n \"Audio\",\n \"AudioBuffer\",\n \"AudioBufferSourceNode\",\n \"AudioContext\",\n \"AudioDestinationNode\",\n \"AudioListener\",\n \"AudioNode\",\n \"AudioParam\",\n \"AudioProcessingEvent\",\n \"AudioScheduledSourceNode\",\n \"AudioWorkletGlobalScope\",\n \"AudioWorkletNode\",\n \"AudioWorkletProcessor\",\n \"BarProp\",\n \"BaseAudioContext\",\n \"BatteryManager\",\n \"BeforeUnloadEvent\",\n \"BiquadFilterNode\",\n \"Blob\",\n \"BlobEvent\",\n \"blur\",\n \"BroadcastChannel\",\n \"btoa\",\n \"BudgetService\",\n \"ByteLengthQueuingStrategy\",\n \"Cache\",\n \"caches\",\n \"CacheStorage\",\n \"cancelAnimationFrame\",\n \"cancelIdleCallback\",\n \"CanvasCaptureMediaStreamTrack\",\n \"CanvasGradient\",\n \"CanvasPattern\",\n \"CanvasRenderingContext2D\",\n \"ChannelMergerNode\",\n \"ChannelSplitterNode\",\n \"CharacterData\",\n \"clearInterval\",\n \"clearTimeout\",\n \"clientInformation\",\n \"ClipboardEvent\",\n \"ClipboardItem\",\n \"close\",\n \"closed\",\n \"CloseEvent\",\n \"Comment\",\n \"CompositionEvent\",\n \"confirm\",\n \"console\",\n \"ConstantSourceNode\",\n \"ConvolverNode\",\n \"CountQueuingStrategy\",\n \"createImageBitmap\",\n \"Credential\",\n \"CredentialsContainer\",\n \"crypto\",\n \"Crypto\",\n \"CryptoKey\",\n \"CSS\",\n \"CSSConditionRule\",\n \"CSSFontFaceRule\",\n \"CSSGroupingRule\",\n \"CSSImportRule\",\n \"CSSKeyframeRule\",\n \"CSSKeyframesRule\",\n \"CSSMatrixComponent\",\n \"CSSMediaRule\",\n \"CSSNamespaceRule\",\n \"CSSPageRule\",\n \"CSSPerspective\",\n \"CSSRotate\",\n \"CSSRule\",\n \"CSSRuleList\",\n \"CSSScale\",\n \"CSSSkew\",\n \"CSSSkewX\",\n \"CSSSkewY\",\n \"CSSStyleDeclaration\",\n \"CSSStyleRule\",\n \"CSSStyleSheet\",\n \"CSSSupportsRule\",\n \"CSSTransformValue\",\n \"CSSTranslate\",\n \"CustomElementRegistry\",\n \"customElements\",\n \"CustomEvent\",\n \"DataTransfer\",\n \"DataTransferItem\",\n \"DataTransferItemList\",\n \"defaultstatus\",\n \"defaultStatus\",\n \"DelayNode\",\n \"DeviceMotionEvent\",\n \"DeviceOrientationEvent\",\n \"devicePixelRatio\",\n \"dispatchEvent\",\n \"document\",\n \"Document\",\n \"DocumentFragment\",\n \"DocumentType\",\n \"DOMError\",\n \"DOMException\",\n \"DOMImplementation\",\n \"DOMMatrix\",\n \"DOMMatrixReadOnly\",\n \"DOMParser\",\n \"DOMPoint\",\n \"DOMPointReadOnly\",\n \"DOMQuad\",\n \"DOMRect\",\n \"DOMRectList\",\n \"DOMRectReadOnly\",\n \"DOMStringList\",\n \"DOMStringMap\",\n \"DOMTokenList\",\n \"DragEvent\",\n \"DynamicsCompressorNode\",\n \"Element\",\n \"ErrorEvent\",\n \"event\",\n \"Event\",\n \"EventSource\",\n \"EventTarget\",\n \"external\",\n \"fetch\",\n \"File\",\n \"FileList\",\n \"FileReader\",\n \"find\",\n \"focus\",\n \"FocusEvent\",\n \"FontFace\",\n \"FontFaceSetLoadEvent\",\n \"FormData\",\n \"FormDataEvent\",\n \"frameElement\",\n \"frames\",\n \"GainNode\",\n \"Gamepad\",\n \"GamepadButton\",\n \"GamepadEvent\",\n \"getComputedStyle\",\n \"getSelection\",\n \"HashChangeEvent\",\n \"Headers\",\n \"history\",\n \"History\",\n \"HTMLAllCollection\",\n \"HTMLAnchorElement\",\n \"HTMLAreaElement\",\n \"HTMLAudioElement\",\n \"HTMLBaseElement\",\n \"HTMLBodyElement\",\n \"HTMLBRElement\",\n \"HTMLButtonElement\",\n \"HTMLCanvasElement\",\n \"HTMLCollection\",\n \"HTMLContentElement\",\n \"HTMLDataElement\",\n \"HTMLDataListElement\",\n \"HTMLDetailsElement\",\n \"HTMLDialogElement\",\n \"HTMLDirectoryElement\",\n \"HTMLDivElement\",\n \"HTMLDListElement\",\n \"HTMLDocument\",\n \"HTMLElement\",\n \"HTMLEmbedElement\",\n \"HTMLFieldSetElement\",\n \"HTMLFontElement\",\n \"HTMLFormControlsCollection\",\n \"HTMLFormElement\",\n \"HTMLFrameElement\",\n \"HTMLFrameSetElement\",\n \"HTMLHeadElement\",\n \"HTMLHeadingElement\",\n \"HTMLHRElement\",\n \"HTMLHtmlElement\",\n \"HTMLIFrameElement\",\n \"HTMLImageElement\",\n \"HTMLInputElement\",\n \"HTMLLabelElement\",\n \"HTMLLegendElement\",\n \"HTMLLIElement\",\n \"HTMLLinkElement\",\n \"HTMLMapElement\",\n \"HTMLMarqueeElement\",\n \"HTMLMediaElement\",\n \"HTMLMenuElement\",\n \"HTMLMetaElement\",\n \"HTMLMeterElement\",\n \"HTMLModElement\",\n \"HTMLObjectElement\",\n \"HTMLOListElement\",\n \"HTMLOptGroupElement\",\n \"HTMLOptionElement\",\n \"HTMLOptionsCollection\",\n \"HTMLOutputElement\",\n \"HTMLParagraphElement\",\n \"HTMLParamElement\",\n \"HTMLPictureElement\",\n \"HTMLPreElement\",\n \"HTMLProgressElement\",\n \"HTMLQuoteElement\",\n \"HTMLScriptElement\",\n \"HTMLSelectElement\",\n \"HTMLShadowElement\",\n \"HTMLSlotElement\",\n \"HTMLSourceElement\",\n \"HTMLSpanElement\",\n \"HTMLStyleElement\",\n \"HTMLTableCaptionElement\",\n \"HTMLTableCellElement\",\n \"HTMLTableColElement\",\n \"HTMLTableElement\",\n \"HTMLTableRowElement\",\n \"HTMLTableSectionElement\",\n \"HTMLTemplateElement\",\n \"HTMLTextAreaElement\",\n \"HTMLTimeElement\",\n \"HTMLTitleElement\",\n \"HTMLTrackElement\",\n \"HTMLUListElement\",\n \"HTMLUnknownElement\",\n \"HTMLVideoElement\",\n \"IDBCursor\",\n \"IDBCursorWithValue\",\n \"IDBDatabase\",\n \"IDBFactory\",\n \"IDBIndex\",\n \"IDBKeyRange\",\n \"IDBObjectStore\",\n \"IDBOpenDBRequest\",\n \"IDBRequest\",\n \"IDBTransaction\",\n \"IDBVersionChangeEvent\",\n \"IdleDeadline\",\n \"IIRFilterNode\",\n \"Image\",\n \"ImageBitmap\",\n \"ImageBitmapRenderingContext\",\n \"ImageCapture\",\n \"ImageData\",\n \"indexedDB\",\n \"innerHeight\",\n \"innerWidth\",\n \"InputEvent\",\n \"IntersectionObserver\",\n \"IntersectionObserverEntry\",\n \"Intl\",\n \"isSecureContext\",\n \"KeyboardEvent\",\n \"KeyframeEffect\",\n \"KeyframeEffectReadOnly\",\n \"length\",\n \"localStorage\",\n \"location\",\n \"Location\",\n \"locationbar\",\n \"matchMedia\",\n \"MediaDeviceInfo\",\n \"MediaDevices\",\n \"MediaElementAudioSourceNode\",\n \"MediaEncryptedEvent\",\n \"MediaError\",\n \"MediaKeyMessageEvent\",\n \"MediaKeySession\",\n \"MediaKeyStatusMap\",\n \"MediaKeySystemAccess\",\n \"MediaList\",\n \"MediaMetadata\",\n \"MediaQueryList\",\n \"MediaQueryListEvent\",\n \"MediaRecorder\",\n \"MediaSettingsRange\",\n \"MediaSource\",\n \"MediaStream\",\n \"MediaStreamAudioDestinationNode\",\n \"MediaStreamAudioSourceNode\",\n \"MediaStreamEvent\",\n \"MediaStreamTrack\",\n \"MediaStreamTrackEvent\",\n \"menubar\",\n \"MessageChannel\",\n \"MessageEvent\",\n \"MessagePort\",\n \"MIDIAccess\",\n \"MIDIConnectionEvent\",\n \"MIDIInput\",\n \"MIDIInputMap\",\n \"MIDIMessageEvent\",\n \"MIDIOutput\",\n \"MIDIOutputMap\",\n \"MIDIPort\",\n \"MimeType\",\n \"MimeTypeArray\",\n \"MouseEvent\",\n \"moveBy\",\n \"moveTo\",\n \"MutationEvent\",\n \"MutationObserver\",\n \"MutationRecord\",\n \"name\",\n \"NamedNodeMap\",\n \"NavigationPreloadManager\",\n \"navigator\",\n \"Navigator\",\n \"NavigatorUAData\",\n \"NetworkInformation\",\n \"Node\",\n \"NodeFilter\",\n \"NodeIterator\",\n \"NodeList\",\n \"Notification\",\n \"OfflineAudioCompletionEvent\",\n \"OfflineAudioContext\",\n \"offscreenBuffering\",\n \"OffscreenCanvas\",\n \"OffscreenCanvasRenderingContext2D\",\n \"onabort\",\n \"onafterprint\",\n \"onanimationend\",\n \"onanimationiteration\",\n \"onanimationstart\",\n \"onappinstalled\",\n \"onauxclick\",\n \"onbeforeinstallprompt\",\n \"onbeforeprint\",\n \"onbeforeunload\",\n \"onblur\",\n \"oncancel\",\n \"oncanplay\",\n \"oncanplaythrough\",\n \"onchange\",\n \"onclick\",\n \"onclose\",\n \"oncontextmenu\",\n \"oncuechange\",\n \"ondblclick\",\n \"ondevicemotion\",\n \"ondeviceorientation\",\n \"ondeviceorientationabsolute\",\n \"ondrag\",\n \"ondragend\",\n \"ondragenter\",\n \"ondragleave\",\n \"ondragover\",\n \"ondragstart\",\n \"ondrop\",\n \"ondurationchange\",\n \"onemptied\",\n \"onended\",\n \"onerror\",\n \"onfocus\",\n \"ongotpointercapture\",\n \"onhashchange\",\n \"oninput\",\n \"oninvalid\",\n \"onkeydown\",\n \"onkeypress\",\n \"onkeyup\",\n \"onlanguagechange\",\n \"onload\",\n \"onloadeddata\",\n \"onloadedmetadata\",\n \"onloadstart\",\n \"onlostpointercapture\",\n \"onmessage\",\n \"onmessageerror\",\n \"onmousedown\",\n \"onmouseenter\",\n \"onmouseleave\",\n \"onmousemove\",\n \"onmouseout\",\n \"onmouseover\",\n \"onmouseup\",\n \"onmousewheel\",\n \"onoffline\",\n \"ononline\",\n \"onpagehide\",\n \"onpageshow\",\n \"onpause\",\n \"onplay\",\n \"onplaying\",\n \"onpointercancel\",\n \"onpointerdown\",\n \"onpointerenter\",\n \"onpointerleave\",\n \"onpointermove\",\n \"onpointerout\",\n \"onpointerover\",\n \"onpointerup\",\n \"onpopstate\",\n \"onprogress\",\n \"onratechange\",\n \"onrejectionhandled\",\n \"onreset\",\n \"onresize\",\n \"onscroll\",\n \"onsearch\",\n \"onseeked\",\n \"onseeking\",\n \"onselect\",\n \"onstalled\",\n \"onstorage\",\n \"onsubmit\",\n \"onsuspend\",\n \"ontimeupdate\",\n \"ontoggle\",\n \"ontransitionend\",\n \"onunhandledrejection\",\n \"onunload\",\n \"onvolumechange\",\n \"onwaiting\",\n \"onwheel\",\n \"open\",\n \"openDatabase\",\n \"opener\",\n \"Option\",\n \"origin\",\n \"OscillatorNode\",\n \"outerHeight\",\n \"outerWidth\",\n \"OverconstrainedError\",\n \"PageTransitionEvent\",\n \"pageXOffset\",\n \"pageYOffset\",\n \"PannerNode\",\n \"parent\",\n \"Path2D\",\n \"PaymentAddress\",\n \"PaymentRequest\",\n \"PaymentRequestUpdateEvent\",\n \"PaymentResponse\",\n \"performance\",\n \"Performance\",\n \"PerformanceEntry\",\n \"PerformanceLongTaskTiming\",\n \"PerformanceMark\",\n \"PerformanceMeasure\",\n \"PerformanceNavigation\",\n \"PerformanceNavigationTiming\",\n \"PerformanceObserver\",\n \"PerformanceObserverEntryList\",\n \"PerformancePaintTiming\",\n \"PerformanceResourceTiming\",\n \"PerformanceTiming\",\n \"PeriodicWave\",\n \"Permissions\",\n \"PermissionStatus\",\n \"personalbar\",\n \"PhotoCapabilities\",\n \"Plugin\",\n \"PluginArray\",\n \"PointerEvent\",\n \"PopStateEvent\",\n \"postMessage\",\n \"Presentation\",\n \"PresentationAvailability\",\n \"PresentationConnection\",\n \"PresentationConnectionAvailableEvent\",\n \"PresentationConnectionCloseEvent\",\n \"PresentationConnectionList\",\n \"PresentationReceiver\",\n \"PresentationRequest\",\n \"print\",\n \"ProcessingInstruction\",\n \"ProgressEvent\",\n \"PromiseRejectionEvent\",\n \"prompt\",\n \"PushManager\",\n \"PushSubscription\",\n \"PushSubscriptionOptions\",\n \"queueMicrotask\",\n \"RadioNodeList\",\n \"Range\",\n \"ReadableStream\",\n \"registerProcessor\",\n \"RemotePlayback\",\n \"removeEventListener\",\n \"reportError\",\n \"Request\",\n \"requestAnimationFrame\",\n \"requestIdleCallback\",\n \"resizeBy\",\n \"ResizeObserver\",\n \"ResizeObserverEntry\",\n \"resizeTo\",\n \"Response\",\n \"RTCCertificate\",\n \"RTCDataChannel\",\n \"RTCDataChannelEvent\",\n \"RTCDtlsTransport\",\n \"RTCIceCandidate\",\n \"RTCIceGatherer\",\n \"RTCIceTransport\",\n \"RTCPeerConnection\",\n \"RTCPeerConnectionIceEvent\",\n \"RTCRtpContributingSource\",\n \"RTCRtpReceiver\",\n \"RTCRtpSender\",\n \"RTCSctpTransport\",\n \"RTCSessionDescription\",\n \"RTCStatsReport\",\n \"RTCTrackEvent\",\n \"screen\",\n \"Screen\",\n \"screenLeft\",\n \"ScreenOrientation\",\n \"screenTop\",\n \"screenX\",\n \"screenY\",\n \"ScriptProcessorNode\",\n \"scroll\",\n \"scrollbars\",\n \"scrollBy\",\n \"scrollTo\",\n \"scrollX\",\n \"scrollY\",\n \"SecurityPolicyViolationEvent\",\n \"Selection\",\n \"self\",\n \"ServiceWorker\",\n \"ServiceWorkerContainer\",\n \"ServiceWorkerRegistration\",\n \"sessionStorage\",\n \"setInterval\",\n \"setTimeout\",\n \"ShadowRoot\",\n \"SharedWorker\",\n \"SourceBuffer\",\n \"SourceBufferList\",\n \"speechSynthesis\",\n \"SpeechSynthesisEvent\",\n \"SpeechSynthesisUtterance\",\n \"StaticRange\",\n \"status\",\n \"statusbar\",\n \"StereoPannerNode\",\n \"stop\",\n \"Storage\",\n \"StorageEvent\",\n \"StorageManager\",\n \"structuredClone\",\n \"styleMedia\",\n \"StyleSheet\",\n \"StyleSheetList\",\n \"SubmitEvent\",\n \"SubtleCrypto\",\n \"SVGAElement\",\n \"SVGAngle\",\n \"SVGAnimatedAngle\",\n \"SVGAnimatedBoolean\",\n \"SVGAnimatedEnumeration\",\n \"SVGAnimatedInteger\",\n \"SVGAnimatedLength\",\n \"SVGAnimatedLengthList\",\n \"SVGAnimatedNumber\",\n \"SVGAnimatedNumberList\",\n \"SVGAnimatedPreserveAspectRatio\",\n \"SVGAnimatedRect\",\n \"SVGAnimatedString\",\n \"SVGAnimatedTransformList\",\n \"SVGAnimateElement\",\n \"SVGAnimateMotionElement\",\n \"SVGAnimateTransformElement\",\n \"SVGAnimationElement\",\n \"SVGCircleElement\",\n \"SVGClipPathElement\",\n \"SVGComponentTransferFunctionElement\",\n \"SVGDefsElement\",\n \"SVGDescElement\",\n \"SVGDiscardElement\",\n \"SVGElement\",\n \"SVGEllipseElement\",\n \"SVGFEBlendElement\",\n \"SVGFEColorMatrixElement\",\n \"SVGFEComponentTransferElement\",\n \"SVGFECompositeElement\",\n \"SVGFEConvolveMatrixElement\",\n \"SVGFEDiffuseLightingElement\",\n \"SVGFEDisplacementMapElement\",\n \"SVGFEDistantLightElement\",\n \"SVGFEDropShadowElement\",\n \"SVGFEFloodElement\",\n \"SVGFEFuncAElement\",\n \"SVGFEFuncBElement\",\n \"SVGFEFuncGElement\",\n \"SVGFEFuncRElement\",\n \"SVGFEGaussianBlurElement\",\n \"SVGFEImageElement\",\n \"SVGFEMergeElement\",\n \"SVGFEMergeNodeElement\",\n \"SVGFEMorphologyElement\",\n \"SVGFEOffsetElement\",\n \"SVGFEPointLightElement\",\n \"SVGFESpecularLightingElement\",\n \"SVGFESpotLightElement\",\n \"SVGFETileElement\",\n \"SVGFETurbulenceElement\",\n \"SVGFilterElement\",\n \"SVGForeignObjectElement\",\n \"SVGGElement\",\n \"SVGGeometryElement\",\n \"SVGGradientElement\",\n \"SVGGraphicsElement\",\n \"SVGImageElement\",\n \"SVGLength\",\n \"SVGLengthList\",\n \"SVGLinearGradientElement\",\n \"SVGLineElement\",\n \"SVGMarkerElement\",\n \"SVGMaskElement\",\n \"SVGMatrix\",\n \"SVGMetadataElement\",\n \"SVGMPathElement\",\n \"SVGNumber\",\n \"SVGNumberList\",\n \"SVGPathElement\",\n \"SVGPatternElement\",\n \"SVGPoint\",\n \"SVGPointList\",\n \"SVGPolygonElement\",\n \"SVGPolylineElement\",\n \"SVGPreserveAspectRatio\",\n \"SVGRadialGradientElement\",\n \"SVGRect\",\n \"SVGRectElement\",\n \"SVGScriptElement\",\n \"SVGSetElement\",\n \"SVGStopElement\",\n \"SVGStringList\",\n \"SVGStyleElement\",\n \"SVGSVGElement\",\n \"SVGSwitchElement\",\n \"SVGSymbolElement\",\n \"SVGTextContentElement\",\n \"SVGTextElement\",\n \"SVGTextPathElement\",\n \"SVGTextPositioningElement\",\n \"SVGTitleElement\",\n \"SVGTransform\",\n \"SVGTransformList\",\n \"SVGTSpanElement\",\n \"SVGUnitTypes\",\n \"SVGUseElement\",\n \"SVGViewElement\",\n \"TaskAttributionTiming\",\n \"Text\",\n \"TextDecoder\",\n \"TextEncoder\",\n \"TextEvent\",\n \"TextMetrics\",\n \"TextTrack\",\n \"TextTrackCue\",\n \"TextTrackCueList\",\n \"TextTrackList\",\n \"TimeRanges\",\n \"toolbar\",\n \"top\",\n \"Touch\",\n \"TouchEvent\",\n \"TouchList\",\n \"TrackEvent\",\n \"TransformStream\",\n \"TransitionEvent\",\n \"TreeWalker\",\n \"UIEvent\",\n \"URL\",\n \"URLSearchParams\",\n \"ValidityState\",\n \"visualViewport\",\n \"VisualViewport\",\n \"VTTCue\",\n \"WaveShaperNode\",\n \"WebAssembly\",\n \"WebGL2RenderingContext\",\n \"WebGLActiveInfo\",\n \"WebGLBuffer\",\n \"WebGLContextEvent\",\n \"WebGLFramebuffer\",\n \"WebGLProgram\",\n \"WebGLQuery\",\n \"WebGLRenderbuffer\",\n \"WebGLRenderingContext\",\n \"WebGLSampler\",\n \"WebGLShader\",\n \"WebGLShaderPrecisionFormat\",\n \"WebGLSync\",\n \"WebGLTexture\",\n \"WebGLTransformFeedback\",\n \"WebGLUniformLocation\",\n \"WebGLVertexArrayObject\",\n \"WebSocket\",\n \"WheelEvent\",\n \"window\",\n \"Window\",\n \"Worker\",\n \"WritableStream\",\n \"XMLDocument\",\n \"XMLHttpRequest\",\n \"XMLHttpRequestEventTarget\",\n \"XMLHttpRequestUpload\",\n \"XMLSerializer\",\n \"XPathEvaluator\",\n \"XPathExpression\",\n \"XPathResult\",\n \"XSLTProcessor\"\n];\n " }, { "path": "packages/sandbox/src/core/membrane/index.ts", "content": "/* eslint-disable no-param-reassign */\nimport {\n create,\n defineProperty,\n freeze,\n getOwnPropertyDescriptor,\n getOwnPropertyNames,\n hasOwnProperty,\n keys,\n} from '@qiankunjs/shared';\nimport { nativeGlobal } from '../../consts';\nimport { isPropertyFrozen } from '../../utils';\nimport { globalsInBrowser } from '../globals';\nimport { array2TruthyObject } from '../utils';\nimport { rebindTarget2Fn } from './utils';\n\ndeclare global {\n interface Window {\n __QIANKUN_DEVELOPMENT__?: boolean;\n }\n}\n\nexport type MembraneTarget = Record;\nexport type Endowments = Record;\n\ntype SymbolTarget = 'target' | 'globalContext';\n\nconst variableWhiteListInDev =\n process.env.NODE_ENV === 'test' || process.env.NODE_ENV === 'development' || window.__QIANKUN_DEVELOPMENT__\n ? [\n // for react hot reload\n // see https://github.com/facebook/create-react-app/blob/66bf7dfc43350249e2f09d138a20840dae8a0a4a/packages/react-error-overlay/src/index.js#L180\n '__REACT_ERROR_OVERLAY_GLOBAL_HOOK__',\n // for react development event issue, see https://github.com/umijs/qiankun/issues/2375\n 'event',\n ]\n : [];\n// who could escape the sandbox\nconst globalVariableWhiteList: string[] = [\n // FIXME System.js used a indirect call with eval, which would make it scope escape to global\n // To make System.js works well, we write it back to global window temporary\n // see https://github.com/systemjs/systemjs/blob/457f5b7e8af6bd120a279540477552a07d5de086/src/evaluate.js#L106\n 'System',\n\n // see https://github.com/systemjs/systemjs/blob/457f5b7e8af6bd120a279540477552a07d5de086/src/instantiate.js#L357\n '__cjsWrapper',\n ...variableWhiteListInDev,\n];\n\nconst useNativeWindowForBindingsProps = new Map([\n ['fetch', true],\n ['mockDomAPIInBlackList', process.env.NODE_ENV === 'test'],\n]);\n\nconst isPropertyDescriptor = (v: unknown): boolean => {\n return (\n typeof v === 'object' &&\n v !== null &&\n ['value', 'writable', 'get', 'set', 'configurable', 'enumerable'].some((p) => p in v)\n );\n};\n\nconst cachedGlobalsInBrowser = array2TruthyObject(\n globalsInBrowser.concat(process.env.NODE_ENV === 'test' ? ['mockNativeWindowFunction'] : []),\n);\nconst isNativeGlobalProp = (prop: string): boolean => {\n return prop in cachedGlobalsInBrowser;\n};\n\nexport class Membrane {\n private locking = false;\n\n modifications = new Set();\n\n realmGlobal: WindowProxy;\n\n target: MembraneTarget;\n\n latestSetProp: PropertyKey | undefined;\n\n constructor(\n incubatorContext: WindowProxy,\n unscopables: Record,\n opts?: {\n whitelist?: string[];\n endowments?: Endowments;\n },\n ) {\n const { endowments = {} } = opts || {};\n const whitelistVars = [...(opts?.whitelist || []), ...globalVariableWhiteList];\n const descriptorTargetMap = new Map();\n\n const { target, propertiesWithGetter } = createMembraneTarget(endowments, incubatorContext);\n\n this.target = target;\n\n this.realmGlobal = new Proxy(this.target, {\n set: (membraneTarget, p, value: never) => {\n if (!this.locking) {\n // sync the property to incubatorContext\n if (typeof p === 'string' && whitelistVars.indexOf(p) !== -1) {\n // this.globalWhitelistPrevDescriptor[p] = Object.getOwnPropertyDescriptor(incubatorContext, p);\n incubatorContext[p as never] = value;\n } else {\n // We must keep its description while the property existed in incubatorContext before\n if (!hasOwnProperty(membraneTarget, p) && hasOwnProperty(incubatorContext, p)) {\n const descriptor = getOwnPropertyDescriptor(incubatorContext, p);\n const { writable, configurable, enumerable } = descriptor!;\n // only writable property can be overwritten\n // here we ignored accessor descriptor of incubatorContext as it makes no sense to trigger its logic(which might make sandbox escaping instead)\n // we force to set value by data descriptor\n if (writable || hasOwnProperty(descriptor, 'set')) {\n defineProperty(membraneTarget, p, { configurable, enumerable, writable: true, value });\n }\n } else {\n membraneTarget[p] = value;\n }\n }\n\n this.modifications.add(p);\n\n this.latestSetProp = p;\n\n return true;\n }\n\n if (process.env.NODE_ENV === 'development') {\n // console.warn(`[qiankun] Set window.${p.toString()} while sandbox destroyed or inactive in ${name}!`);\n console.warn(`[qiankun] Set window.${p.toString()} while sandbox destroyed or inactive!`);\n }\n\n // 在 strict-mode 下，Proxy 的 handler.set 返回 false 会抛出 TypeError，在沙箱卸载的情况下应该忽略错误\n return true;\n },\n\n get: (membraneTarget, p, receiver) => {\n if (p === Symbol.unscopables) return unscopables;\n\n // properties in endowments returns directly\n if (hasOwnProperty(endowments, p)) {\n return membraneTarget[p];\n }\n\n if (p === 'string' && whitelistVars.indexOf(p) !== -1) {\n return incubatorContext[p as never];\n }\n\n const actualTarget = propertiesWithGetter.has(p)\n ? incubatorContext\n : p in membraneTarget\n ? membraneTarget\n : incubatorContext;\n const value = actualTarget[p as never];\n\n // frozen value should return directly, see https://github.com/umijs/qiankun/issues/2015\n if (isPropertyFrozen(actualTarget, p)) {\n return value;\n }\n\n // non-native property return directly to avoid rebind\n if (!isNativeGlobalProp(p as string) && !useNativeWindowForBindingsProps.has(p)) {\n return value;\n }\n\n /* Some dom api must be bound to native window, otherwise it would cause exception like 'TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation'\n See this code:\n const proxy = new Proxy(window, {});\n const proxyFetch = fetch.bind(proxy);\n proxyFetch('https://qiankun.com');\n */\n const boundTarget = useNativeWindowForBindingsProps.get(p) ? nativeGlobal : incubatorContext;\n return rebindTarget2Fn(boundTarget, value, receiver);\n },\n\n // trap in operator\n // see https://github.com/styled-components/styled-components/blob/master/packages/styled-components/src/constants.js#L12\n has(membraneTarget: MembraneTarget, p: string | number | symbol): boolean {\n return p in membraneTarget || p in incubatorContext;\n },\n\n getOwnPropertyDescriptor(\n membraneTarget: MembraneTarget,\n p: string | number | symbol,\n ): PropertyDescriptor | undefined {\n /*\n as the descriptor of top/self/window/mockTop in raw window are configurable but not in proxy membraneTarget, we need to get it from membraneTarget to avoid TypeError\n see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/handler/getOwnPropertyDescriptor\n > A property cannot be reported as non-configurable, if it does not exist as an own property of the membraneTarget object or if it exists as a configurable own property of the membraneTarget object.\n */\n if (hasOwnProperty(membraneTarget, p)) {\n const descriptor = getOwnPropertyDescriptor(membraneTarget, p);\n descriptorTargetMap.set(p, 'target');\n return descriptor;\n }\n\n if (hasOwnProperty(incubatorContext, p)) {\n const descriptor = getOwnPropertyDescriptor(incubatorContext, p);\n descriptorTargetMap.set(p, 'globalContext');\n // A property cannot be reported as non-configurable, if it does not exist as an own property of the membraneTarget object\n if (descriptor && !descriptor.configurable) {\n descriptor.configurable = true;\n }\n return descriptor;\n }\n\n return undefined;\n },\n\n // trap to support iterator with sandbox\n ownKeys(membraneTarget: MembraneTarget): ArrayLike {\n return uniq(Reflect.ownKeys(incubatorContext).concat(Reflect.ownKeys(membraneTarget)));\n },\n\n defineProperty: (membraneTarget, p, attributes) => {\n const from = descriptorTargetMap.get(p);\n /*\n Descriptor must be defined to native window while it comes from native window via Object.getOwnPropertyDescriptor(window, p),\n otherwise it would cause a TypeError with illegal invocation.\n */\n switch (from) {\n case 'globalContext':\n return Reflect.defineProperty(incubatorContext, p, attributes);\n default:\n return Reflect.defineProperty(membraneTarget, p, attributes);\n }\n },\n\n deleteProperty: (membraneTarget, p) => {\n if (hasOwnProperty(membraneTarget, p)) {\n delete membraneTarget[p];\n this.modifications.delete(p);\n\n return true;\n }\n\n return true;\n },\n\n // makes sure `window instanceof Window` returns truthy in micro app\n getPrototypeOf() {\n return Reflect.getPrototypeOf(incubatorContext);\n },\n }) as unknown as WindowProxy;\n }\n\n addIntrinsics(\n intrinsics:\n | Record\n | ((rawTarget: MembraneTarget) => Record),\n ): void {\n const intrinsicsObj = typeof intrinsics === 'function' ? intrinsics(this.target) : intrinsics;\n keys(intrinsicsObj).forEach((key) => {\n defineProperty(this.target, key, intrinsicsObj[key]);\n });\n }\n\n lock() {\n this.locking = true;\n }\n\n unlock() {\n this.locking = false;\n }\n}\n\nfunction createMembraneTarget(\n endowments: Endowments = {},\n incubatorContext: WindowProxy,\n): {\n target: MembraneTarget;\n propertiesWithGetter: Map;\n} {\n // map always has the best performance in `has` check scenario\n // see https://jsperf.com/array-indexof-vs-set-has/23\n const propertiesWithGetter = new Map();\n const target: MembraneTarget = keys(endowments).reduce((acc, key) => {\n const value = endowments[key];\n if (isPropertyDescriptor(value)) {\n defineProperty(acc, key, value);\n } else {\n acc[key] = value;\n }\n return acc;\n }, {} as MembraneTarget);\n\n /*\n copy the non-configurable property of incubatorContext to membrane target to avoid TypeError\n see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/handler/getOwnPropertyDescriptor\n > A property cannot be reported as non-configurable, if it does not exist as an own property of the target object or if it exists as a configurable own property of the target object.\n */\n getOwnPropertyNames(incubatorContext)\n .filter((p) => {\n const descriptor = getOwnPropertyDescriptor(incubatorContext, p);\n return !hasOwnProperty(endowments, p) && !descriptor?.configurable;\n })\n .forEach((p) => {\n const descriptor = getOwnPropertyDescriptor(incubatorContext, p);\n if (descriptor) {\n const hasGetter = hasOwnProperty(descriptor, 'get');\n if (hasGetter) {\n propertiesWithGetter.set(p, true);\n }\n\n defineProperty(\n target,\n p,\n // freeze the descriptor to avoid being modified by zone.js\n // see https://github.com/angular/zone.js/blob/a5fe09b0fac27ac5df1fa746042f96f05ccb6a00/lib/browser/define-property.ts#L71\n freeze(descriptor),\n );\n }\n });\n\n return {\n target,\n propertiesWithGetter,\n };\n}\n\n/**\n * fastest(at most time) unique array method\n * @see https://jsperf.com/array-filter-unique/30\n */\nfunction uniq(array: Array) {\n return array.filter(function (this: Record, element) {\n return element in this ? false : (this[element] = true);\n }, create(null));\n}\n" }, { "path": "packages/sandbox/src/core/membrane/utils.ts", "content": "import { defineProperty, getOwnPropertyDescriptor, getOwnPropertyNames, hasOwnProperty } from '@qiankunjs/shared';\nimport { isBoundedFunction, isCallable, isConstructable } from '../../utils';\n\nconst functionBoundedValueMap = new WeakMap();\n\nexport function rebindTarget2Fn(target: unknown, fn: T, receiver: unknown): T {\n /*\n 仅绑定 isCallable && !isBoundedFunction && !isConstructable 的函数对象，如 window.console、window.atob 这类，不然微应用中调用时会抛出 Illegal invocation 异常\n 目前没有完美的检测方式，这里通过 prototype 中是否还有可枚举的拓展方法的方式来判断\n @warning 这里不要随意替换成别的判断方式，因为可能触发一些 edge case（比如在 lodash.isFunction 在 iframe 上下文中可能由于调用了 top window 对象触发的安全异常）\n */\n if (isCallable(fn) && !isBoundedFunction(fn) && !isConstructable(fn as CallableFunction)) {\n const typedValue = fn as CallableFunction;\n const cachedBoundFunction = functionBoundedValueMap.get(typedValue);\n if (cachedBoundFunction) {\n return cachedBoundFunction as T;\n }\n\n const boundValue = function proxyFunction(...args: unknown[]): unknown {\n return Function.prototype.apply.call(\n typedValue,\n target,\n args.map((arg) => (arg === receiver ? target : arg)),\n );\n };\n\n // some callable function has custom fields, we need to copy the own props to boundValue. such as moment function.\n getOwnPropertyNames(typedValue).forEach((key) => {\n // boundValue might be a proxy, we need to check the key whether exist in it\n if (!hasOwnProperty(boundValue, key)) {\n defineProperty(boundValue, key, getOwnPropertyDescriptor(typedValue, key)!);\n }\n });\n\n // copy prototype if bound function not have but target one have\n // as prototype is non-enumerable mostly, we need to copy it from target function manually\n if (hasOwnProperty(typedValue, 'prototype') && !hasOwnProperty(boundValue, 'prototype')) {\n // we should not use assignment operator to set boundValue prototype like `boundValue.prototype = typedValue.prototype`\n // as the assignment will also look up prototype chain while it hasn't own prototype property,\n // when the lookup succeed, the assignment will throw an TypeError like `Cannot assign to read only property 'prototype' of function` if its descriptor configured with writable false or just have a getter accessor\n // see https://github.com/umijs/qiankun/issues/1121\n defineProperty(boundValue, 'prototype', {\n value: typedValue.prototype as unknown,\n enumerable: false,\n writable: true,\n });\n }\n\n // Some util, like `function isNative() { return typeof Ctor === 'function' && /native code/.test(Ctor.toString()) }` relies on the original `toString()` result\n // but bound functions will always return \"function() {[native code]}\" for `toString`, which is misleading\n if (typeof typedValue.toString === 'function') {\n const valueHasInstanceToString =\n hasOwnProperty(typedValue, 'toString') && !hasOwnProperty(boundValue, 'toString');\n const boundValueHasPrototypeToString = boundValue.toString === Function.prototype.toString;\n\n if (valueHasInstanceToString || boundValueHasPrototypeToString) {\n const originToStringDescriptor = getOwnPropertyDescriptor(\n valueHasInstanceToString ? fn : Function.prototype,\n 'toString',\n );\n\n Object.defineProperty(\n boundValue,\n 'toString',\n Object.assign(\n {},\n originToStringDescriptor,\n originToStringDescriptor?.get ? null : { value: () => typedValue.toString() },\n ),\n );\n }\n }\n\n functionBoundedValueMap.set(fn, boundValue);\n return boundValue as T;\n }\n\n return fn;\n}\n" }, { "path": "packages/sandbox/src/core/sandbox/StandardSandbox.ts", "content": "import { hasOwnProperty } from '@qiankunjs/shared';\nimport { without } from 'lodash';\nimport { Compartment } from '../compartment';\nimport { globalsInES2015 } from '../globals';\nimport type { Endowments } from '../membrane';\nimport { Membrane } from '../membrane';\nimport { array2TruthyObject } from '../utils';\nimport type { Sandbox } from './types';\nimport { SandboxType } from './types';\n\nconst whitelistBOMAPIs = ['requestAnimationFrame', 'cancelAnimationFrame'];\n\nexport class StandardSandbox extends Compartment implements Sandbox {\n private readonly membrane: Membrane;\n\n readonly type = SandboxType.Standard;\n\n readonly name: string;\n\n constructor(name: string, globals: Endowments, incubatorContext: WindowProxy = window) {\n const getRealmGlobal = () => realmGlobal;\n const getTopValue = (p: 'top' | 'parent'): WindowProxy => {\n // if your master app in an iframe context, allow these props escape the sandbox\n if (incubatorContext === incubatorContext.parent) {\n return realmGlobal;\n }\n return incubatorContext[p]!;\n };\n\n const intrinsics: Record = {\n // avoid who using window.window or window.self to escape the sandbox environment to touch the real window\n // see https://github.com/eligrey/FileSaver.js/blob/master/src/FileSaver.js#L13\n window: { get: getRealmGlobal, enumerable: true, configurable: false },\n self: { get: getRealmGlobal, enumerable: true, configurable: false },\n globalThis: { get: getRealmGlobal, enumerable: false, configurable: true },\n\n // proxy.hasOwnProperty would invoke getter firstly, then its value represented as incubatorContext.hasOwnProperty\n hasOwnProperty: {\n value: function hasOwnPropertyImpl(this: unknown, key: PropertyKey): boolean {\n // calling from hasOwnProperty.call(obj, key)\n if (this !== realmGlobal && this !== null && typeof this === 'object') {\n return hasOwnProperty(this, key);\n }\n\n return hasOwnProperty(target, key) || hasOwnProperty(incubatorContext, key);\n },\n writable: true,\n enumerable: false,\n configurable: true,\n },\n\n // eslint-disable-next-line no-eval\n eval: { value: eval, writable: true, enumerable: false, configurable: true },\n\n top: {\n get() {\n return getTopValue('top');\n },\n configurable: false,\n enumerable: true,\n },\n parent: {\n get() {\n return getTopValue('parent');\n },\n configurable: false,\n enumerable: true,\n },\n\n // Temporarily occupy the document as it may be modified later\n document: { value: document, writable: true, enumerable: true, configurable: true },\n };\n if (process.env.NODE_ENV === 'test') {\n ['mockSafariTop', 'mockTop', 'mockGlobalThis'].forEach((key) => {\n intrinsics[key] = { get: getRealmGlobal, enumerable: false, configurable: true };\n });\n }\n\n const constantNames = Array.from(new Set(Object.keys(intrinsics).concat(globalsInES2015).concat(whitelistBOMAPIs)));\n // intrinsics should not be escaped from sandbox\n const unscopables = array2TruthyObject(without(constantNames, ...Object.keys(intrinsics)));\n const membrane = new Membrane(incubatorContext, unscopables, {\n whitelist: [],\n endowments: { ...intrinsics, ...globals },\n });\n\n const { realmGlobal, target } = membrane;\n\n super(realmGlobal);\n\n this.name = name;\n this.membrane = membrane;\n\n this.addConstantIntrinsicNames(constantNames);\n }\n\n get latestSetProp() {\n return this.membrane.latestSetProp;\n }\n\n addIntrinsics(intrinsics: Record) {\n this.membrane.addIntrinsics(intrinsics);\n }\n\n active() {\n this.membrane.unlock();\n }\n\n inactive() {\n if (process.env.NODE_ENV === 'development') {\n console.info(`[qiankun:sandbox] ${this.name} modified global properties restore...`, [\n ...this.membrane.modifications.keys(),\n ]);\n }\n\n this.membrane.lock();\n }\n\n // TODO\n // destroy() {\n //\n // }\n}\n" }, { "path": "packages/sandbox/src/core/sandbox/index.ts", "content": "/**\n * @author Kuitos\n * @since 2019-04-11\n */\nimport { patchAtBootstrapping, patchAtMounting } from '../../patchers';\nimport type { SandboxConfig } from '../../patchers/dynamicAppend/types';\nimport type { Free, Rebuild } from '../../patchers/types';\nimport type { Endowments } from '../membrane';\nimport { StandardSandbox } from './StandardSandbox';\nimport type { Sandbox } from './types';\n\nexport type { Sandbox };\n\n/**\n * @param appName\n * @param getContainer\n * @param opts\n */\nexport function createSandboxContainer(\n appName: string,\n getContainer: () => HTMLElement,\n opts: {\n globalContext?: WindowProxy;\n extraGlobals?: Endowments;\n } & Pick,\n) {\n const { globalContext, extraGlobals = {}, ...sandboxCfg } = opts;\n let sandbox: Sandbox;\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n if (window.Proxy) {\n sandbox = new StandardSandbox(appName, extraGlobals, globalContext);\n } else {\n // TODO snapshot sandbox\n sandbox = new StandardSandbox(appName, extraGlobals, globalContext);\n }\n\n // some side effect could be invoked while bootstrapping, such as dynamic stylesheet injection with style-loader, especially during the development phase\n const bootstrappingFrees = patchAtBootstrapping(appName, getContainer, { sandbox, ...sandboxCfg });\n // mounting frees are one-off and should be re-init at every mounting time\n let mountingFrees: Free[] = [];\n\n let sideEffectsRebuilds: Rebuild[] = [];\n\n return {\n instance: sandbox,\n\n /**\n * 沙箱被 mount\n * 可能是从 bootstrap 状态进入的 mount\n * 也可能是从 unmount 之后再次唤醒进入 mount\n */\n async mount(container: HTMLElement) {\n /* ------------------------------------------ 因为有上下文依赖（window），以下代码执行顺序不能变 ------------------------------------------ */\n\n /* ------------------------------------------ 1. 启动/恢复 沙箱------------------------------------------ */\n sandbox.active();\n\n const sideEffectsRebuildsAtBootstrapping = sideEffectsRebuilds.slice(0, bootstrappingFrees.length);\n const sideEffectsRebuildsAtMounting = sideEffectsRebuilds.slice(bootstrappingFrees.length);\n\n // must rebuild the side effects which added at bootstrapping firstly to recovery to nature state\n if (sideEffectsRebuildsAtBootstrapping.length) {\n for (const rebuildSideEffects of sideEffectsRebuildsAtBootstrapping) {\n await rebuildSideEffects(container);\n }\n }\n\n /* ------------------------------------------ 2. 开启全局变量补丁 ------------------------------------------*/\n // render 沙箱启动时开始劫持各类全局监听，尽量不要在应用初始化阶段有 事件监听/定时器 等副作用\n mountingFrees = patchAtMounting(appName, getContainer, { sandbox, ...sandboxCfg });\n\n /* ------------------------------------------ 3. 重置一些初始化时的副作用 ------------------------------------*/\n // 存在 rebuilds 则表明有些副作用需要重建\n if (sideEffectsRebuildsAtMounting.length) {\n for (const rebuildSideEffects of sideEffectsRebuildsAtMounting) {\n await rebuildSideEffects(container);\n }\n }\n\n // clean up rebuilds\n sideEffectsRebuilds = [];\n },\n\n /**\n * 恢复 global 状态，使其能回到应用加载之前的状态\n */\n async unmount() {\n // record the rebuilds of window side effects (event listeners or timers)\n // note that the frees of mounting phase are one-off as it will be re-init at next mounting\n sideEffectsRebuilds = [...bootstrappingFrees, ...mountingFrees].map((free) => free());\n\n sandbox.inactive();\n },\n };\n}\n" }, { "path": "packages/sandbox/src/core/sandbox/types.ts", "content": "/**\n * @author Kuitos\n * @since 2023-05-04\n */\n\nimport type { Compartment } from '../compartment';\n\nexport enum SandboxType {\n Standard = 'Standard',\n Snapshot = 'Snapshot',\n}\n\nexport interface Sandbox extends Compartment {\n name: string;\n type: SandboxType;\n latestSetProp?: PropertyKey;\n\n active(): void;\n\n inactive(): void;\n\n addIntrinsics: (intrinsics: Record) => void;\n\n // TODO for gc\n // destroy(): void;\n}\n" }, { "path": "packages/sandbox/src/core/utils.ts", "content": "/**\n * @author Kuitos\n * @since 2023-11-15\n */\n/**\n * transform the array to a truthy object for better performance with in operator check later\n * @param array\n */\nexport function array2TruthyObject(array: string[]): Record {\n return array.reduce(\n (obj, key) => {\n obj[key] = true;\n return obj;\n },\n // Notes that babel will transpile spread operator to Object.assign({}, ...args), which will keep the prototype of Object in merged object,\n // while this result used as Symbol.unscopables, it will make properties in Object.prototype always be escaped from proxy sandbox as unscopables check will look up prototype chain as well,\n // such as hasOwnProperty, toString, valueOf, etc.\n // so we should use Object.create(null) to create a pure object without prototype chain here.\n Object.create(null) as Record,\n );\n}\n" }, { "path": "packages/sandbox/src/index.ts", "content": "export * from './core/sandbox';\nexport * from './core/compartment';\nexport * from './consts';\n" }, { "path": "packages/sandbox/src/patchers/consts.ts", "content": "" }, { "path": "packages/sandbox/src/patchers/dynamicAppend/common.ts", "content": "/* eslint-disable @typescript-eslint/unbound-method */\nimport type { AssetsTranspilerOpts, ScriptTranspilerOpts } from '@qiankunjs/shared';\n/**\n * @author Kuitos\n * @since 2019-10-21\n */\nimport { prepareDeferredQueue, warn } from '@qiankunjs/shared';\nimport { qiankunHeadTagName } from '../../consts';\nimport type { SandboxConfig } from './types';\n\nconst SCRIPT_TAG_NAME = 'SCRIPT';\nconst LINK_TAG_NAME = 'LINK';\nconst STYLE_TAG_NAME = 'STYLE';\n\nexport const styleElementTargetSymbol = Symbol('target');\nexport const styleElementRefNodeNo = Symbol('refNodeNo');\nconst overwrittenSymbol = Symbol('qiankun-overwritten');\n\ntype DynamicDomMutationTarget = 'head' | 'body';\n\ndeclare global {\n interface HTMLLinkElement {\n [styleElementTargetSymbol]: DynamicDomMutationTarget;\n [styleElementRefNodeNo]?: Exclude;\n }\n\n interface HTMLStyleElement {\n [styleElementTargetSymbol]: DynamicDomMutationTarget;\n [styleElementRefNodeNo]?: Exclude;\n }\n\n interface Function {\n [overwrittenSymbol]: boolean;\n }\n}\n\nexport const getContainerHeadElement = (container: Element): HTMLHeadElement | null => {\n return container.querySelector(qiankunHeadTagName);\n};\n\nexport const getContainerBodyElement = (container: Element): HTMLBodyElement => {\n return container as HTMLBodyElement;\n};\n\nexport function isHijackingTag(tagName?: string) {\n return (\n tagName?.toUpperCase() === LINK_TAG_NAME ||\n tagName?.toUpperCase() === STYLE_TAG_NAME ||\n tagName?.toUpperCase() === SCRIPT_TAG_NAME\n );\n}\n\n/**\n * Check if a style element is a styled-component liked.\n * A styled-components liked element is which not have textContext but keep the rules in its styleSheet.cssRules.\n * Such as the style element generated by styled-components and emotion.\n * @param element\n */\nexport function isStyledComponentsLike(element: HTMLStyleElement): boolean {\n return Boolean(!element.textContent && (element.sheet?.cssRules.length || getStyledElementCSSRules(element)?.length));\n}\n\nconst appsCounterMap = new Map();\n\nexport function calcAppCount(\n appName: string,\n calcType: 'increase' | 'decrease',\n status: 'bootstrapping' | 'mounting',\n): void {\n const appCount = appsCounterMap.get(appName) || { bootstrappingPatchCount: 0, mountingPatchCount: 0 };\n switch (calcType) {\n case 'increase':\n appCount[`${status}PatchCount`] += 1;\n break;\n case 'decrease':\n // bootstrap patch just called once but its freer will be called multiple times\n if (appCount[`${status}PatchCount`] > 0) {\n appCount[`${status}PatchCount`] -= 1;\n }\n break;\n }\n appsCounterMap.set(appName, appCount);\n}\n\nexport function isAllAppsUnmounted(): boolean {\n return Array.from(appsCounterMap.entries()).every(\n ([, { bootstrappingPatchCount: bpc, mountingPatchCount: mpc }]) => bpc === 0 && mpc === 0,\n );\n}\n\nconst defineNonEnumerableProperty = (target: unknown, key: string | symbol, value: unknown) => {\n Object.defineProperty(target, key, {\n configurable: true,\n enumerable: false,\n writable: true,\n value,\n });\n};\n\nconst styledComponentCSSRulesMap = new WeakMap();\n\nexport function recordStyledComponentsCSSRules(styleElements: HTMLStyleElement[]): void {\n styleElements.forEach((styleElement) => {\n /*\n With a styled-components generated style element, we need to record its cssRules for restore next re-mounting time.\n We're doing this because the sheet of style element is going to be cleaned automatically by browser after the style element dom removed from document.\n see https://www.w3.org/TR/cssom-1/#associated-css-style-sheet\n */\n if (styleElement instanceof HTMLStyleElement && isStyledComponentsLike(styleElement)) {\n if (styleElement.sheet) {\n // record the original css rules of the style element for restore\n styledComponentCSSRulesMap.set(styleElement, styleElement.sheet.cssRules);\n }\n }\n });\n}\n\nexport function getStyledElementCSSRules(styledElement: HTMLStyleElement): CSSRuleList | undefined {\n return styledComponentCSSRulesMap.get(styledElement);\n}\n\nexport function getOverwrittenAppendChildOrInsertBefore(\n nativeFn: typeof HTMLElement.prototype.appendChild | typeof HTMLElement.prototype.insertBefore,\n getSandboxConfig: (element: HTMLElement) => SandboxConfig | undefined,\n target: DynamicDomMutationTarget = 'body',\n) {\n function appendChildInSandbox(\n this: HTMLHeadElement | HTMLBodyElement,\n newChild: T,\n refChild: Node | null = null,\n ): T {\n const appendChild = nativeFn;\n\n const element = newChild as unknown as HTMLElement;\n const sandboxConfig = getSandboxConfig(element);\n\n // no attached sandbox config means the element is not created from the sandbox environment\n if (!isHijackingTag(element.tagName) || !sandboxConfig) {\n return appendChild.call(this, element, refChild) as T;\n }\n\n if (element.tagName) {\n switch (element.tagName) {\n case LINK_TAG_NAME:\n case STYLE_TAG_NAME: {\n const stylesheetElement = element as HTMLLinkElement | HTMLStyleElement;\n Object.defineProperty(stylesheetElement, styleElementTargetSymbol, {\n value: target,\n writable: true,\n configurable: true,\n });\n\n const referenceNode = this.contains(refChild) ? refChild : null;\n let refNo: number | undefined;\n if (referenceNode) {\n refNo = Array.from(this.childNodes).indexOf(referenceNode as ChildNode);\n }\n\n const { sandbox, nodeTransformer, fetch } = sandboxConfig;\n const transpiledStyleSheetElement = nodeTransformer(stylesheetElement, {\n fetch,\n sandbox,\n });\n\n const stylesheetTargetDetached = !document.contains(this);\n if (stylesheetTargetDetached) {\n warn(\n `Trying to append stylesheet element ${\n ('href' in transpiledStyleSheetElement && transpiledStyleSheetElement.href) ||\n transpiledStyleSheetElement.dataset.href\n } to a detached container which may cause unexpected behaviors!`,\n );\n }\n // FIXME we have to set the target container to global document to trigger style rendering while the real container was detached\n const targetContainerDOM = stylesheetTargetDetached ? document[target] : this;\n const result = appendChild.call(targetContainerDOM, transpiledStyleSheetElement, referenceNode);\n\n // record refNo thus we can keep order while remounting\n if (typeof refNo === 'number' && refNo !== -1) {\n defineNonEnumerableProperty(transpiledStyleSheetElement, styleElementRefNodeNo, refNo);\n }\n const { dynamicStyleSheetElements } = sandboxConfig;\n // record dynamic style elements after insert succeed\n dynamicStyleSheetElements.push(transpiledStyleSheetElement);\n\n return result as T;\n }\n\n case SCRIPT_TAG_NAME: {\n const scriptElement = element as HTMLScriptElement;\n const { sandbox, dynamicExternalSyncScriptDeferredList, nodeTransformer, fetch } = sandboxConfig;\n\n const externalSyncMode = scriptElement.hasAttribute('src') && !scriptElement.hasAttribute('async');\n\n let transformerOpts: AssetsTranspilerOpts = {\n fetch,\n sandbox,\n };\n\n let queueSyncScript: () => void;\n if (externalSyncMode) {\n const { deferred, prevDeferred, queue } = prepareDeferredQueue(dynamicExternalSyncScriptDeferredList);\n transformerOpts = {\n ...transformerOpts,\n scriptTranspiledDeferred: deferred,\n prevScriptTranspiledDeferred: prevDeferred,\n } as ScriptTranspilerOpts;\n queueSyncScript = queue;\n }\n\n const transpiledScriptElement = nodeTransformer(scriptElement, transformerOpts);\n\n /*\n The target container of script element might be removed from current document.\n For example, the main application clears the DOM first during route switching, and then trigger unmount,\n at this time, the micro app may still be processing the logic of the route switching, and try to add nodes to the detached container,\n in this scenario, we have to append the script to global document head to trigger script evaluation\n */\n const scriptTargetDetached = !document.contains(this);\n if (scriptTargetDetached) {\n warn(\n `Trying to append script element ${\n transpiledScriptElement.src || transpiledScriptElement.dataset.src\n } to a detached container which may cause unexpected behaviors!`,\n );\n }\n /*\n FIXME we have to set the target container to global document to trigger script evaluation while the real container was detached,\n as dynamic append script element to detached element will not trigger script evaluation automatically\n */\n const targetContainerDOM = scriptTargetDetached ? document[target] : this;\n const result = appendChild.call(targetContainerDOM, transpiledScriptElement, refChild) as T;\n\n // the script have no src attribute after transpile, indicating that the script needs to wait for the src to be filled\n if (externalSyncMode && !transpiledScriptElement.hasAttribute('src')) {\n queueSyncScript!();\n }\n\n return result;\n }\n\n default:\n break;\n }\n }\n\n return appendChild.call(this, element, refChild) as T;\n }\n\n appendChildInSandbox[overwrittenSymbol] = true;\n\n return appendChildInSandbox;\n}\n\nexport function getNewRemoveChild(\n nativeFn: typeof HTMLElement.prototype.removeChild,\n containerConfigGetter: (element: HTMLElement) => SandboxConfig | undefined,\n) {\n function removeChildInSandbox(this: HTMLHeadElement | HTMLBodyElement, child: T): T {\n const removeChild = nativeFn;\n\n const childElement = child as unknown as HTMLElement;\n const { tagName } = childElement;\n const containerConfig = containerConfigGetter(childElement);\n\n if (!isHijackingTag(tagName) || !containerConfig) {\n return removeChild.call(this, childElement) as T;\n }\n\n try {\n const { dynamicStyleSheetElements } = containerConfig;\n\n switch (tagName) {\n case STYLE_TAG_NAME:\n case LINK_TAG_NAME: {\n // try to remove the dynamic style sheet\n const dynamicElementIndex = dynamicStyleSheetElements.indexOf(\n childElement as HTMLLinkElement | HTMLStyleElement,\n );\n if (dynamicElementIndex !== -1) {\n dynamicStyleSheetElements.splice(dynamicElementIndex, 1);\n }\n\n break;\n }\n\n default: {\n break;\n }\n }\n\n // container might have been removed while app unmounting if the removeChild action was async\n if (this.contains(childElement)) {\n return removeChild.call(this, childElement) as T;\n }\n } catch (e) {\n console.warn(e);\n }\n\n return removeChild.call(this, childElement) as T;\n }\n\n removeChildInSandbox[overwrittenSymbol] = true;\n return removeChildInSandbox;\n}\n\nexport function rebuildCSSRules(\n styleSheetElements: Array,\n reAppendElement: (stylesheetElement: HTMLStyleElement | HTMLLinkElement) => Promise,\n): Array> {\n return styleSheetElements.map(async (styleSheetElement) => {\n // re-append the dynamic stylesheet to sub-app container\n const appendSuccess = await reAppendElement(styleSheetElement);\n if (appendSuccess) {\n /*\n get the stored css rules from styled-components generated element, and the re-insert rules for them.\n note that we must do this after style element had been added to document, which stylesheet would be associated to the document automatically.\n check the spec https://www.w3.org/TR/cssom-1/#associated-css-style-sheet\n */\n if (styleSheetElement instanceof HTMLStyleElement && isStyledComponentsLike(styleSheetElement)) {\n const cssRules = getStyledElementCSSRules(styleSheetElement);\n if (cssRules) {\n // eslint-disable-next-line no-plusplus\n for (let i = 0; i < cssRules.length; i++) {\n const cssRule = cssRules[i];\n const cssStyleSheetElement = styleSheetElement.sheet as CSSStyleSheet;\n cssStyleSheetElement.insertRule(cssRule.cssText, cssStyleSheetElement.cssRules.length);\n }\n }\n }\n }\n });\n}\n" }, { "path": "packages/sandbox/src/patchers/dynamicAppend/forStandardSandbox.ts", "content": "/* eslint-disable */\n/**\n * @author Kuitos\n * @since 2020-10-13\n */\n\nimport { Deferred, QiankunError } from '@qiankunjs/shared';\nimport type { noop } from 'lodash';\nimport { nativeDocument, nativeGlobal, qiankunHeadTagName } from '../../consts';\nimport { rebindTarget2Fn } from '../../core/membrane/utils';\nimport type { Sandbox } from '../../core/sandbox';\nimport type { Free } from '../types';\nimport {\n calcAppCount,\n getContainerBodyElement,\n getContainerHeadElement,\n getNewRemoveChild,\n getOverwrittenAppendChildOrInsertBefore,\n isAllAppsUnmounted,\n rebuildCSSRules,\n recordStyledComponentsCSSRules,\n styleElementRefNodeNo,\n styleElementTargetSymbol,\n} from './common';\nimport type { SandboxConfig } from './types';\n\nconst elementAttachedSymbol = Symbol('attachedApp');\ndeclare global {\n interface HTMLElement {\n [elementAttachedSymbol]: string;\n }\n\n interface Window {\n __currentLockingSandbox__?: Sandbox;\n }\n\n interface Document {\n [p: string]: unknown;\n }\n}\n\n// Get native global window with a sandbox disgusted way, thus we could share it between qiankun instances🤪\nObject.defineProperty(nativeGlobal, '__sandboxConfigWeakMap__', { enumerable: false, writable: true });\n\nObject.defineProperty(nativeGlobal, '__currentLockingSandbox__', {\n enumerable: false,\n writable: true,\n configurable: true,\n});\n\nconst sandboxConfigWeakMap = new WeakMap();\n\nconst elementAttachSandboxConfigMap = new WeakMap();\nconst patchCacheWeakMap = new WeakMap();\n\nconst getSandboxConfig = (element: HTMLElement) => elementAttachSandboxConfigMap.get(element);\n\nfunction patchDocument(sandbox: Sandbox, getContainer: () => HTMLElement): CallableFunction {\n const container = getContainer();\n // dom container might be reused by multiple apps,\n // thus we check its attached sandbox is same with current to avoid duplicate patch\n if (patchCacheWeakMap.get(container) === sandbox) {\n return () => {};\n }\n\n const unpatch = patchDocumentHeadAndBodyMethods(container);\n\n const attachElementToSandbox = (element: HTMLElement) => {\n const sandboxConfig = sandboxConfigWeakMap.get(sandbox);\n if (sandboxConfig) {\n elementAttachSandboxConfigMap.set(element, sandboxConfig);\n }\n };\n const getDocumentHeadElement = () => {\n const container = getContainer();\n const containerHeadElement = getContainerHeadElement(container);\n if (!containerHeadElement) {\n throw new QiankunError(`${sandbox.name} head element not existed while accessing document.head!`);\n }\n return containerHeadElement;\n };\n const getDocumentBodyElement = () => {\n const container = getContainer();\n return getContainerBodyElement(container);\n };\n const modificationFns: {\n createElement?: typeof document.createElement;\n querySelector?: typeof document.querySelector;\n } = {};\n const proxyDocument = new Proxy(document, {\n /**\n * Read and write must be paired, otherwise the write operation will leak to the global\n */\n set: (target, p, value) => {\n switch (p) {\n case 'createElement': {\n modificationFns.createElement = value;\n break;\n }\n case 'querySelector': {\n modificationFns.querySelector = value;\n break;\n }\n default:\n target[p as keyof Document] = value;\n break;\n }\n\n return true;\n },\n get: (target, p, receiver) => {\n switch (p) {\n case 'createElement': {\n // Must store the original createElement function to avoid error in nested sandbox\n const targetCreateElement = modificationFns.createElement || target.createElement;\n return function createElement(...args: Parameters) {\n if (!nativeGlobal.__currentLockingSandbox__) {\n nativeGlobal.__currentLockingSandbox__ = sandbox;\n }\n\n const element = targetCreateElement.call(target, ...args);\n\n // only record the element which is created by the current sandbox, thus we can avoid the element created by nested sandboxes\n if (nativeGlobal.__currentLockingSandbox__ === sandbox) {\n attachElementToSandbox(element);\n delete nativeGlobal.__currentLockingSandbox__;\n }\n\n return element;\n };\n }\n\n case 'querySelector': {\n const targetQuerySelector = modificationFns.querySelector || target.querySelector;\n return function querySelector(...args: Parameters) {\n const selector = args[0];\n switch (selector) {\n case 'head': {\n return getDocumentHeadElement();\n }\n\n case 'body': {\n return getDocumentBodyElement();\n }\n }\n\n return targetQuerySelector.call(target, ...args);\n };\n }\n\n case 'head': {\n return getDocumentHeadElement();\n }\n\n case 'body': {\n return getDocumentBodyElement();\n }\n\n default:\n break;\n }\n\n const value = target[p as keyof Document];\n // must rebind the function to the target otherwise it will cause illegal invocation error\n return rebindTarget2Fn(target, value, receiver);\n },\n });\n\n sandbox.addIntrinsics({\n document: { value: proxyDocument, writable: false, enumerable: true, configurable: true },\n });\n\n patchCacheWeakMap.set(container, sandbox);\n\n return () => {\n unpatch();\n };\n}\n\nfunction patchDocumentHeadAndBodyMethods(container: HTMLElement): typeof noop {\n const patchHeadElementMethod = (headElement: HTMLHeadElement) => {\n headElement.appendChild = getOverwrittenAppendChildOrInsertBefore(\n document.head.appendChild,\n getSandboxConfig,\n 'head',\n );\n headElement.insertBefore = getOverwrittenAppendChildOrInsertBefore(\n document.head.insertBefore,\n getSandboxConfig,\n 'head',\n );\n headElement.removeChild = getNewRemoveChild(document.head.removeChild, getSandboxConfig);\n };\n let containerHeadElement = getContainerHeadElement(container);\n if (!containerHeadElement) {\n // patch container head element after it is mounted\n const observer = new MutationObserver(() => {\n containerHeadElement = getContainerHeadElement(container);\n if (containerHeadElement) {\n patchHeadElementMethod(containerHeadElement);\n observer.disconnect();\n }\n });\n observer.observe(container, { subtree: true, childList: true });\n } else {\n patchHeadElementMethod(containerHeadElement);\n }\n\n const containerBodyElement = container;\n containerBodyElement.appendChild = getOverwrittenAppendChildOrInsertBefore(\n document.body.appendChild,\n getSandboxConfig,\n 'body',\n );\n containerBodyElement.insertBefore = getOverwrittenAppendChildOrInsertBefore(\n document.head.insertBefore,\n getSandboxConfig,\n 'body',\n );\n containerBodyElement.removeChild = getNewRemoveChild(document.body.removeChild, getSandboxConfig);\n\n return () => {\n if (containerHeadElement) {\n // @ts-ignore\n delete containerHeadElement.appendChild;\n // @ts-ignore\n delete containerHeadElement.insertBefore;\n // @ts-ignore\n delete containerHeadElement.removeChild;\n }\n\n // @ts-ignore\n delete containerBodyElement.appendChild;\n // @ts-ignore\n delete containerBodyElement.insertBefore;\n // @ts-ignore\n delete containerBodyElement.removeChild;\n };\n}\n\nfunction patchDOMPrototypeFns(): typeof noop {\n // patch MutationObserver.prototype.observe to avoid type error\n // https://github.com/umijs/qiankun/issues/2406\n const nativeMutationObserverObserveFn = MutationObserver.prototype.observe;\n if (!patchCacheWeakMap.has(nativeMutationObserverObserveFn)) {\n const observe = function observe(this: MutationObserver, target: Node, options: MutationObserverInit) {\n const realTarget = target instanceof Document ? nativeDocument : target;\n return nativeMutationObserverObserveFn.call(this, realTarget, options);\n };\n\n MutationObserver.prototype.observe = observe;\n patchCacheWeakMap.set(nativeMutationObserverObserveFn, observe);\n }\n\n // patch Node.prototype.compareDocumentPosition to avoid type error\n const prevCompareDocumentPosition = Node.prototype.compareDocumentPosition;\n if (!patchCacheWeakMap.has(prevCompareDocumentPosition)) {\n Node.prototype.compareDocumentPosition = function compareDocumentPosition(this: Node, node) {\n const realNode = node instanceof Document ? nativeDocument : node;\n return prevCompareDocumentPosition.call(this, realNode);\n };\n patchCacheWeakMap.set(prevCompareDocumentPosition, Node.prototype.compareDocumentPosition);\n }\n\n // TODO https://github.com/umijs/qiankun/pull/2415 Not support yet as getCurrentRunningApp api is not reliable\n // patch parentNode getter to avoid document === html.parentNode\n // https://github.com/umijs/qiankun/issues/2408#issuecomment-1446229105\n // const parentNodeDescriptor = Object.getOwnPropertyDescriptor(Node.prototype, 'parentNode');\n // if (parentNodeDescriptor && !patchCacheWeakMap.has(parentNodeDescriptor)) {\n // const { get: parentNodeGetter, configurable } = parentNodeDescriptor;\n // if (parentNodeGetter && configurable) {\n // const patchedParentNodeDescriptor = {\n // ...parentNodeDescriptor,\n // get(this: Node) {\n // const parentNode = parentNodeGetter.call(this) as HTMLElement;\n // if (parentNode instanceof Document) {\n // const proxy = getCurrentRunningApp()?.window;\n // if (proxy) {\n // return proxy.document;\n // }\n // }\n //\n // return parentNode;\n // },\n // };\n // Object.defineProperty(Node.prototype, 'parentNode', patchedParentNodeDescriptor);\n //\n // patchCacheWeakMap.set(parentNodeDescriptor, patchedParentNodeDescriptor);\n // }\n // }\n\n return () => {\n MutationObserver.prototype.observe = nativeMutationObserverObserveFn;\n patchCacheWeakMap.delete(nativeMutationObserverObserveFn);\n\n Node.prototype.compareDocumentPosition = prevCompareDocumentPosition;\n patchCacheWeakMap.delete(prevCompareDocumentPosition);\n\n // if (parentNodeDescriptor) {\n // Object.defineProperty(Node.prototype, 'parentNode', parentNodeDescriptor);\n // patchCacheWeakMap.delete(parentNodeDescriptor);\n // }\n };\n}\n\n// FIXME should not use global variable, should get it every time it is used, otherwise it may miss the runtime container or the business itself monkey patch logic\nconst rawHeadInsertBefore = HTMLHeadElement.prototype.insertBefore;\nconst rawHeadAppendChild = HTMLHeadElement.prototype.appendChild;\n\nexport function patchStandardSandbox(\n appName: string,\n getContainer: () => HTMLElement,\n opts: {\n sandbox: Sandbox;\n mounting?: boolean;\n } & Pick,\n): Free {\n const { sandbox, mounting = true, nodeTransformer, fetch } = opts;\n let sandboxConfig = sandboxConfigWeakMap.get(sandbox);\n if (!sandboxConfig) {\n sandboxConfig = {\n appName,\n sandbox,\n fetch,\n nodeTransformer,\n dynamicStyleSheetElements: [],\n dynamicExternalSyncScriptDeferredList: [],\n };\n sandboxConfigWeakMap.set(sandbox, sandboxConfig);\n }\n // all dynamic style sheets are stored in proxy container\n const { dynamicStyleSheetElements } = sandboxConfig;\n\n const unpatchDocument = patchDocument(sandbox, getContainer);\n const unpatchDOMPrototype = patchDOMPrototypeFns();\n\n if (!mounting) calcAppCount(appName, 'increase', 'bootstrapping');\n if (mounting) calcAppCount(appName, 'increase', 'mounting');\n\n return function free() {\n if (!mounting) calcAppCount(appName, 'decrease', 'bootstrapping');\n if (mounting) calcAppCount(appName, 'decrease', 'mounting');\n\n // release the overwritten document\n unpatchDocument();\n\n // release the overwritten prototype after all the micro apps unmounted\n if (isAllAppsUnmounted()) {\n unpatchDOMPrototype();\n }\n\n recordStyledComponentsCSSRules(dynamicStyleSheetElements as HTMLStyleElement[]);\n\n // As now the sub app content all wrapped with a special id container,\n // the dynamic style sheet could be removed automatically while unmounting\n return async function rebuild(container: HTMLElement) {\n const isElementExisted = (element: HTMLStyleElement | HTMLLinkElement) => {\n if (container.contains(element)) return true;\n if ('rel' in element && element.rel === 'stylesheet' && element.href)\n return !!container.querySelector(`link[rel=stylesheet][href=\"${element.href}\"]`);\n return false;\n };\n\n await Promise.all(\n rebuildCSSRules(dynamicStyleSheetElements, async (stylesheetElement) => {\n if (!isElementExisted(stylesheetElement)) {\n const mountDom =\n stylesheetElement[styleElementTargetSymbol] === 'head'\n ? (() => {\n const containerHeadElement = getContainerHeadElement(container);\n if (!containerHeadElement) {\n throw new QiankunError(\n `${appName} container ${qiankunHeadTagName} element not ready while rebuilding!`,\n );\n }\n return containerHeadElement;\n })()\n : container;\n\n let styleElement = stylesheetElement;\n\n const deferred = new Deferred();\n if ('rel' in styleElement && styleElement.rel === 'stylesheet' && styleElement.href) {\n // micro app rendering should wait unit the rebuilding link element is loaded, otherwise it may cause style blink\n // As one external link element will just trigger loaded event once, although we append it multiple times, we need to clone it before every appending\n styleElement = styleElement.cloneNode(true) as HTMLLinkElement;\n styleElement.onload = () => deferred.resolve(true);\n styleElement.onerror = () => deferred.resolve(false);\n } else {\n deferred.resolve(true);\n }\n\n const refNo = stylesheetElement[styleElementRefNodeNo];\n if (typeof refNo === 'number' && refNo !== -1) {\n // the reference node may be dynamic script comment which is not rebuilt while remounting thus reference node no longer exists\n // in this case, we should append the style element to the end of mountDom\n const refNode = mountDom.childNodes[refNo];\n rawHeadInsertBefore.call(mountDom, styleElement, refNode);\n } else {\n rawHeadAppendChild.call(mountDom, styleElement);\n }\n\n return deferred.promise;\n }\n\n return false;\n }),\n );\n };\n };\n}\n" }, { "path": "packages/sandbox/src/patchers/dynamicAppend/index.ts", "content": "/**\n * @author Kuitos\n * @since 2020-10-13\n */\n\nexport { patchStandardSandbox } from './forStandardSandbox';\n" }, { "path": "packages/sandbox/src/patchers/dynamicAppend/types.ts", "content": "/**\n * @author Kuitos\n * @since 2023-05-04\n */\nimport type { BaseLoaderOpts, NodeTransformer } from '@qiankunjs/shared';\nimport type { Deferred } from '@qiankunjs/shared';\nimport type { Sandbox } from '../../core/sandbox';\n\nexport type SandboxConfig = {\n appName: string;\n sandbox: Sandbox;\n dynamicStyleSheetElements: Array;\n dynamicExternalSyncScriptDeferredList: Array>;\n nodeTransformer: NodeTransformer;\n} & BaseLoaderOpts;\n" }, { "path": "packages/sandbox/src/patchers/historyListener.ts", "content": "/**\n * @author Kuitos\n * @since 2019-04-11\n */\n\nimport { isFunction, noop } from 'lodash';\n\ndeclare global {\n interface Window {\n g_history?: {\n listen: (listener: typeof noop) => () => void;\n };\n }\n}\n\nexport default function patch() {\n // FIXME umi unmount feature request\n let rawHistoryListen = (_: unknown) => noop;\n const historyListeners: Array = [];\n const historyUnListens: Array = [];\n\n if (window.g_history && isFunction(window.g_history.listen)) {\n rawHistoryListen = window.g_history.listen.bind(window.g_history) as typeof rawHistoryListen;\n\n window.g_history.listen = (listener: typeof noop) => {\n historyListeners.push(listener);\n\n const unListen = rawHistoryListen(listener);\n historyUnListens.push(unListen);\n\n return () => {\n unListen();\n historyUnListens.splice(historyUnListens.indexOf(unListen), 1);\n historyListeners.splice(historyListeners.indexOf(listener), 1);\n };\n };\n }\n\n return function free() {\n let rebuild = () => Promise.resolve();\n\n /*\n 还存在余量 listener 表明未被卸载，存在两种情况\n 1. 应用在 unmount 时未正确卸载 listener\n 2. listener 是应用 mount 之前绑定的，\n 第二种情况下应用在下次 mount 之前需重新绑定该 listener\n */\n if (historyListeners.length) {\n rebuild = async () => {\n // 必须使用 window.g_history.listen 的方式重新绑定 listener，从而能保证 rebuild 这部分也能被捕获到，否则在应用卸载后无法正确的移除这部分副作用\n historyListeners.forEach((listener) => window.g_history?.listen(listener));\n };\n }\n\n // 卸载余下的 listener\n historyUnListens.forEach((unListen) => unListen());\n\n // restore\n if (window.g_history && isFunction(window.g_history.listen)) {\n window.g_history.listen = rawHistoryListen;\n }\n\n return rebuild;\n };\n}\n" }, { "path": "packages/sandbox/src/patchers/index.ts", "content": "/**\n * @author Kuitos\n * @since 2019-04-11\n */\n\nimport { SandboxType } from '../core/sandbox/types';\nimport { patchStandardSandbox } from './dynamicAppend';\nimport type { SandboxConfig } from './dynamicAppend/types';\nimport patchHistoryListener from './historyListener';\nimport patchInterval from './interval';\nimport type { Free } from './types';\nimport patchWindowListener from './windowListener';\n\nexport function patchAtBootstrapping(\n appName: string,\n getContainer: () => HTMLElement,\n opts: Pick,\n): Free[] {\n const patchersInSandbox = {\n [SandboxType.Standard]: [() => patchStandardSandbox(appName, getContainer, { mounting: false, ...opts })],\n [SandboxType.Snapshot]: [],\n } as const;\n const { sandbox } = opts;\n\n return patchersInSandbox[sandbox.type].map((patch) => patch());\n}\n\nexport function patchAtMounting(\n appName: string,\n getContainer: () => HTMLElement,\n opts: Pick,\n): Free[] {\n const { sandbox } = opts;\n const basePatchers = [\n () => patchInterval(sandbox.globalThis),\n () => patchWindowListener(sandbox.globalThis),\n () => patchHistoryListener(),\n ];\n\n const patchersInSandbox = {\n [SandboxType.Standard]: [\n ...basePatchers,\n () => patchStandardSandbox(appName, getContainer, { mounting: true, ...opts }),\n ],\n [SandboxType.Snapshot]: basePatchers,\n };\n\n return patchersInSandbox[sandbox.type].map((patch) => patch());\n}\n" }, { "path": "packages/sandbox/src/patchers/interval.ts", "content": "/**\n * @author Kuitos\n * @since 2019-04-11\n */\n\nconst rawWindowInterval = window.setInterval;\nconst rawWindowClearInterval = window.clearInterval;\n\nexport default function patch(global: Window) {\n let intervals: number[] = [];\n\n global.clearInterval = (intervalId: number) => {\n intervals = intervals.filter((id) => id !== intervalId);\n return rawWindowClearInterval.call(window, intervalId);\n };\n\n global.setInterval = (handler: CallableFunction, timeout?: number, ...args: unknown[]) => {\n const intervalId = rawWindowInterval(handler, timeout, ...args);\n intervals = [...intervals, intervalId];\n return intervalId;\n };\n\n return function free() {\n intervals.forEach((id) => global.clearInterval(id));\n global.setInterval = rawWindowInterval;\n global.clearInterval = rawWindowClearInterval;\n\n return () => Promise.resolve();\n };\n}\n" }, { "path": "packages/sandbox/src/patchers/types.ts", "content": "/**\n * @author Kuitos\n * @since 2023-05-04\n */\nexport type Rebuild = (container: HTMLElement) => Promise;\nexport type Free = () => Rebuild;\nexport type Patch = () => Free;\n" }, { "path": "packages/sandbox/src/patchers/windowListener.ts", "content": "/**\n * @author Kuitos\n * @since 2019-04-11\n */\nimport { type Free } from './types';\n\nconst rawAddEventListener = window.addEventListener.bind(window);\nconst rawRemoveEventListener = window.removeEventListener.bind(window);\n\ntype ListenerMapObject = {\n listener: EventListenerOrEventListenerObject;\n options: AddEventListenerOptions;\n rawListener: EventListenerOrEventListenerObject;\n};\n\nconst DEFAULT_OPTIONS: AddEventListenerOptions = { capture: false, once: false, passive: false };\n\nconst normalizeOptions = (rawOptions?: boolean | AddEventListenerOptions | null): AddEventListenerOptions => {\n if (typeof rawOptions === 'object') {\n return rawOptions ?? DEFAULT_OPTIONS;\n }\n return { capture: !!rawOptions, once: false, passive: false };\n};\n\nconst findListenerIndex = (\n listeners: ListenerMapObject[],\n rawListener: EventListenerOrEventListenerObject,\n options: AddEventListenerOptions,\n): number =>\n listeners.findIndex((item) => item.rawListener === rawListener && item.options.capture === options.capture);\n\nconst removeCacheListener = (\n listenerMap: Map,\n type: string,\n rawListener: EventListenerOrEventListenerObject,\n rawOptions?: boolean | AddEventListenerOptions,\n): ListenerMapObject => {\n const options = normalizeOptions(rawOptions);\n const cachedTypeListeners = listenerMap.get(type) || [];\n\n const findIndex = findListenerIndex(cachedTypeListeners, rawListener, options);\n if (findIndex > -1) {\n return cachedTypeListeners.splice(findIndex, 1)[0];\n }\n\n return { listener: rawListener, rawListener, options };\n};\n\nconst addCacheListener = (\n listenerMap: Map,\n type: string,\n rawListener: EventListenerOrEventListenerObject,\n rawOptions?: boolean | AddEventListenerOptions,\n): ListenerMapObject | undefined => {\n const options = normalizeOptions(rawOptions);\n const cachedTypeListeners = listenerMap.get(type) || [];\n\n const findIndex = findListenerIndex(cachedTypeListeners, rawListener, options);\n // avoid duplicated listener in the listener list\n if (findIndex > -1) return;\n\n let listener: EventListenerOrEventListenerObject = rawListener;\n if (options.once) {\n listener = (event: Event) => {\n (rawListener as EventListener)(event);\n removeCacheListener(listenerMap, type, rawListener, options);\n };\n }\n\n const cacheListener = { listener, options, rawListener };\n listenerMap.set(type, [...cachedTypeListeners, cacheListener]);\n return cacheListener;\n};\n\nexport default function patch(global: WindowProxy): Free {\n const listenerMap = new Map();\n\n global.addEventListener = (\n type: string,\n rawListener: EventListenerOrEventListenerObject,\n rawOptions?: boolean | AddEventListenerOptions,\n ) => {\n const addListener = addCacheListener(listenerMap, type, rawListener, rawOptions);\n\n if (!addListener) return;\n return rawAddEventListener(type, addListener.listener, addListener.options);\n };\n\n global.removeEventListener = (\n type: string,\n rawListener: EventListenerOrEventListenerObject,\n rawOptions?: boolean | AddEventListenerOptions,\n ) => {\n const { listener, options } = removeCacheListener(listenerMap, type, rawListener, rawOptions);\n return rawRemoveEventListener(type, listener, options);\n };\n\n return function free() {\n listenerMap.forEach((listeners, type) => {\n listeners.forEach(({ rawListener, options }) => {\n global.removeEventListener(type, rawListener, options);\n });\n });\n listenerMap.clear();\n global.addEventListener = rawAddEventListener;\n global.removeEventListener = rawRemoveEventListener;\n return () => Promise.resolve();\n };\n}\n" }, { "path": "packages/sandbox/src/utils.ts", "content": "import { getOwnPropertyDescriptor, hasOwnProperty } from '@qiankunjs/shared';\n\nconst fnRegexCheckCacheMap = new WeakMap();\n\n/**\n * 1. has prototype and prototype has defined a series of non-constructor attributes\n * 2. The function name starts with a capital letter\n * 3. class function\n * If one of them is satisfied, it can be regarded as a constructor function\n * @param fn\n */\nexport function isConstructable(fn: CallableFunction): fn is CallableFunction {\n // prototype methods might be changed while code running, so we need check it every time\n const hasPrototypeMethods =\n (fn.prototype)?.constructor === fn && Object.getOwnPropertyNames(fn.prototype).length > 1;\n\n if (hasPrototypeMethods) return true;\n\n const cachedResult = fnRegexCheckCacheMap.get(fn);\n if (typeof cachedResult !== 'undefined') {\n return cachedResult;\n }\n\n // fn.toString has a significant performance overhead, if hasPrototypeMethods check not passed, we will check the function string with regex\n const fnString = fn.toString();\n const constructableFunctionRegex = /^function\\b\\s[A-Z].*/;\n const classRegex = /^class\\b/;\n const constructable = constructableFunctionRegex.test(fnString) || classRegex.test(fnString);\n\n fnRegexCheckCacheMap.set(fn, constructable);\n return constructable;\n}\n\nconst callableFnCacheMap = new WeakMap();\n\nexport function isCallable(fn: unknown): fn is CallableFunction {\n if (callableFnCacheMap.has(fn as CallableFunction)) {\n return true;\n }\n\n /*\n * We can not use typeof to confirm it is function as in some safari version\n * typeof document.all === 'undefined' // true\n * typeof document.all === 'function' // true\n */\n const callable = typeof fn === 'function' && fn instanceof Function;\n if (callable) {\n callableFnCacheMap.set(fn, callable);\n }\n return callable;\n}\n\nconst frozenPropertyCacheMap = new WeakMap>();\n\nexport function isPropertyFrozen(target: object, p?: PropertyKey): boolean {\n if (!p) {\n return false;\n }\n\n const targetPropertiesFromCache = frozenPropertyCacheMap.get(target) || {};\n\n if (targetPropertiesFromCache[p]) {\n return targetPropertiesFromCache[p];\n }\n\n const propertyDescriptor = getOwnPropertyDescriptor(target, p);\n const frozen = Boolean(\n propertyDescriptor &&\n propertyDescriptor.configurable === false &&\n (propertyDescriptor.writable === false || (propertyDescriptor.get && !propertyDescriptor.set)),\n );\n\n targetPropertiesFromCache[p] = frozen;\n frozenPropertyCacheMap.set(target, targetPropertiesFromCache);\n\n return frozen;\n}\n\nconst boundedMap = new WeakMap();\n\nexport function isBoundedFunction(fn: CallableFunction): fn is CallableFunction {\n const cachedValue = boundedMap.get(fn);\n if (typeof cachedValue !== 'undefined') {\n return cachedValue;\n }\n /*\n indexOf is faster than startsWith\n see https://jsperf.com/string-startswith/72\n */\n const bounded = fn.name.indexOf('bound ') === 0 && !hasOwnProperty(fn, 'prototype');\n boundedMap.set(fn, bounded);\n return bounded;\n}\n" }, { "path": "packages/shared/.fatherrc.js", "content": "export { default } from '../../.fatherrc.cjs';\n" }, { "path": "packages/shared/AGENTS.md", "content": "# @qiankunjs/shared\n\nInternal utilities for fetch, asset transpilation, and module resolution.\n\n## STRUCTURE\n\n```\nshared/\n├── assets-transpilers/ # Script/link DOM node transformation\n│ ├── script.ts # Blob URL wrapping, sandbox execution\n│ └── link.ts # Preload optimization, URL rewriting\n├── fetch-utils/ # Enhanced fetch wrappers\n│ ├── makeFetchCacheable.ts # LRU cache (50 entries)\n│ ├── makeFetchRetryable.ts # Automatic retries\n│ └── makeFetchThrowable.ts # Non-2xx throws error\n├── module-resolver/ # Shared dependency resolution\n├── reporter/ # QiankunError, logger\n├── deferred-queue/ # Async task sequencing\n└── utils.ts # Deferred, resolveUrl, etc.\n```\n\n## WHERE TO LOOK\n\n| Task | File | Notes |\n| ------------------ | ----------------------------------- | --------------------------------------------------- |\n| Script sandboxing | `assets-transpilers/script.ts` | Creates Blob URL with sandbox scope |\n| Link preload fix | `assets-transpilers/link.ts` | Changes `as=\"script\"` to `as=\"fetch\"` for sandbox |\n| Fetch with cache | `fetch-utils/makeFetchCacheable.ts` | Clones responses, prunes failed |\n| Dependency sharing | `module-resolver/index.ts` | Semver matching via ` will be resolved to http://localhost:8000/foo.js while read script.src\n const srcAttribute = script.getAttribute('src');\n const { sandbox, scriptTranspiledDeferred } = opts;\n\n try {\n const { mode, result } = preTranspile(\n {\n src: srcAttribute || undefined,\n type: script.type,\n textContent: script.textContent,\n },\n baseURI,\n opts,\n );\n\n switch (mode) {\n case Mode.REMOTE_ASSETS_IN_SANDBOX: {\n const { fetch } = opts;\n const { src } = result;\n\n // We must remove script src to avoid self execution as we need to fetch the script content and transpile it\n script.removeAttribute('src');\n script.dataset.src = src;\n\n const syncMode = !script.hasAttribute('async');\n const priority: Priority = syncMode ? 'high' : 'low';\n const credentials = getCredentials(script.crossOrigin);\n\n void fetch(src, { credentials, priority })\n .then((res) => res.text())\n .then(async (code) => {\n const { prevScriptTranspiledDeferred } = opts;\n\n // add preprocess code to dispatch a CustomEvent before the script is executed\n const beforeScriptExecuteEvent = 'q:bse';\n const beforeExecutedListenerScript = `;(function(){var s=document.currentScript;var e=new CustomEvent('${beforeScriptExecuteEvent}',{detail:{s:s}});window.dispatchEvent(e);})();`;\n\n const codeFactory = beforeExecutedListenerScript + sandbox!.makeEvaluateFactory(code, src);\n\n if (syncMode) {\n // if it's a sync script and there is a previous sync script(mainly there are multiple defer scripts), we should wait it until loaded to consistent with the browser behavior\n if (prevScriptTranspiledDeferred && !prevScriptTranspiledDeferred.isSettled()) {\n await waitUntilSettled(prevScriptTranspiledDeferred.promise);\n }\n\n // HTMLScriptElement default fetchPriority is 'auto', we should set it to 'high' to make it execute earlier while it's not async script\n script.fetchPriority = 'high';\n }\n\n // change the script src to the blob url to make it executed in the sandbox\n script.src = URL.createObjectURL(new Blob([codeFactory], { type: 'text/javascript' }));\n\n window.addEventListener(beforeScriptExecuteEvent, function listener(evt: CustomEventInit) {\n const { s } = evt.detail as { s: HTMLScriptElement };\n if (s === script) {\n URL.revokeObjectURL(s.src);\n // change the script src to the original src while the script is executing\n // thus the script behavior can be more consistent with the native browser logic\n s.src = src;\n s.dataset.consumed = 'true';\n delete s.dataset.src;\n\n window.removeEventListener(beforeScriptExecuteEvent, listener);\n }\n });\n\n scriptTranspiledDeferred?.resolve();\n })\n .catch((e) => {\n scriptTranspiledDeferred?.reject();\n throw e;\n });\n\n return script;\n }\n\n case Mode.INLINE_CODE_IN_SANDBOX: {\n const { code } = result;\n script.textContent = sandbox!.makeEvaluateFactory(code);\n // mark the script have consumed\n script.dataset.consumed = 'true';\n\n scriptTranspiledDeferred?.resolve();\n\n return script;\n }\n\n case Mode.REUSED_DEP_IN_SANDBOX:\n case Mode.REUSED_DEP: {\n const { url, version, src } = result;\n\n script.dataset.src = src;\n script.dataset.version = version;\n\n const syncMode = !script.getAttribute('async');\n // HTMLScriptElement default fetchPriority is 'auto', we should set it to 'high' to make it execute earlier while it's not async script\n if (syncMode) {\n script.fetchPriority = 'high';\n }\n\n // When the script hits the dependency reuse logic, the current script is not executed, and an empty script is returned directly\n script.src = createReusingObjectUrl(src, url, 'text/javascript');\n\n const onScriptComplete = (\n prevListener: typeof HTMLScriptElement.prototype.onload | typeof HTMLScriptElement.prototype.onerror,\n event: Event,\n ) => {\n script.onload = script.onerror = null;\n\n script.src = src;\n script.dataset.consumed = 'true';\n script.dataset.src = url;\n\n prevListener?.call(script, event);\n };\n script.onload = onScriptComplete.bind(null, script.onload);\n script.onerror = onScriptComplete.bind(null, script.onerror) as typeof HTMLScriptElement.prototype.onerror;\n\n scriptTranspiledDeferred?.resolve();\n\n return script;\n }\n\n case Mode.REMOTE_ASSETS:\n case Mode.NONE:\n default: {\n if (result?.src) {\n script.src = result.src;\n }\n\n scriptTranspiledDeferred?.resolve();\n\n return script;\n }\n }\n } catch (e) {\n scriptTranspiledDeferred?.reject(e);\n throw e;\n }\n}\n" }, { "path": "packages/shared/src/assets-transpilers/types.ts", "content": "/**\n * @author Kuitos\n * @since 2023-08-26\n */\nimport type { BaseLoaderOpts } from '../common';\nimport type { MatchResult } from '../module-resolver';\nimport type { Deferred } from '../utils';\n\nexport type BaseTranspilerOpts = BaseLoaderOpts & {\n moduleResolver?: (url: string) => MatchResult | undefined;\n sandbox?: {\n makeEvaluateFactory(source: string, sourceURL?: string): string;\n };\n};\n\nexport type AssetsTranspilerOpts = BaseTranspilerOpts;\n\nexport type NodeTransformer = (node: T, opts: Omit) => T;\n\nexport type ScriptTranspilerOpts = AssetsTranspilerOpts &\n (\n | { prevScriptTranspiledDeferred: Deferred; scriptTranspiledDeferred: Deferred }\n | { prevScriptTranspiledDeferred?: undefined; scriptTranspiledDeferred?: undefined }\n );\n\nexport enum Mode {\n REMOTE_ASSETS_IN_SANDBOX = 'RAIS',\n REMOTE_ASSETS = 'RA',\n REUSED_DEP_IN_SANDBOX = 'RDIS',\n REUSED_DEP = 'RD',\n INLINE_CODE_IN_SANDBOX = 'ICIS',\n NONE = 'NONE',\n}\n" }, { "path": "packages/shared/src/assets-transpilers/utils.ts", "content": "/**\n * @author Kuitos\n * @since 2023-10-09\n */\nimport { memoize } from 'lodash';\n\nexport const createReusingObjectUrl = memoize(\n (src: string, url: string, type: 'text/javascript' | 'text/css'): string => {\n return URL.createObjectURL(\n new Blob([`/* ${src} is reusing the execution result of ${url} */`], {\n type,\n }),\n );\n },\n (src, url, type) => `${src}#${url}#${type}`,\n);\n\nexport const isValidJavaScriptType = (type?: string): boolean => {\n const handleTypes = [\n 'text/javascript',\n 'module',\n 'application/javascript',\n 'text/ecmascript',\n 'application/ecmascript',\n ];\n return !type || handleTypes.indexOf(type) !== -1;\n};\n" }, { "path": "packages/shared/src/common.ts", "content": "export type BaseLoaderOpts = {\n fetch: typeof window.fetch;\n};\n" }, { "path": "packages/shared/src/deferred-queue/index.ts", "content": "import { Deferred, waitUntilSettled } from '../utils';\n\nexport function prepareDeferredQueue(deferredQueue: Array>): {\n deferred: Deferred;\n prevDeferred?: Deferred;\n queue: () => void;\n} {\n const queueLength = deferredQueue.length;\n const prevDeferred = queueLength ? deferredQueue[deferredQueue.length - 1] : undefined;\n const deferred = new Deferred();\n\n return {\n deferred,\n prevDeferred,\n queue: () => {\n deferredQueue.push(deferred);\n // clear the memory regardless the script loaded or failed\n void waitUntilSettled(deferred.promise).then(() => {\n const scriptIndex = deferredQueue.indexOf(deferred);\n deferredQueue.splice(scriptIndex, 1);\n });\n },\n };\n}\n" }, { "path": "packages/shared/src/fetch-utils/__tests__/makeFetchCacheable.test.ts", "content": "// @vitest-environment edge-runtime\n\nimport { expect, it, vi } from 'vitest';\nimport { makeFetchCacheable } from '../makeFetchCacheable';\n\nconst slogan = 'Hello Qiankun 3.0';\n\nit('should just call fetch once while multiple request invoked parallel', () => {\n const fetch = vi.fn(() => {\n return Promise.resolve(new Response(slogan, { status: 200, statusText: 'OK' }));\n });\n const wrappedFetch = makeFetchCacheable(fetch);\n const url = 'https://success.qiankun.org';\n wrappedFetch(url);\n wrappedFetch(url);\n wrappedFetch(url);\n\n expect(fetch).toHaveBeenCalledOnce();\n});\n\nit('should support read response body as a stream multi times', async () => {\n const fetch = vi.fn(() => {\n return Promise.resolve(new Response(slogan, { status: 200, statusText: 'OK' }));\n });\n const wrappedFetch = makeFetchCacheable(fetch);\n\n const url = 'https://stream.qiankun.org';\n const response1 = await wrappedFetch(url);\n const bodyStream1 = response1.body!;\n expect(bodyStream1.locked).toBe(false);\n const reader = bodyStream1.getReader();\n const { done, value } = await reader.read();\n expect(done).toBe(false);\n expect(value).toStrictEqual(new TextEncoder().encode('Hello Qiankun 3.0'));\n expect(bodyStream1.locked).toBe(true);\n\n const response2 = await wrappedFetch(url);\n const bodyStream2 = response2.body!;\n expect(bodyStream2.locked).toBe(false);\n});\n\nit('should clear cache while respond error with invalid status code', async () => {\n const fetch = vi.fn(() => {\n return Promise.resolve(new Response(slogan, { status: 400 }));\n });\n const wrappedFetch = makeFetchCacheable(fetch);\n const url = 'https://errorStatusCode.qiankun.org';\n\n const response1 = await wrappedFetch(url);\n const result1 = await response1.text();\n expect(result1).toBe(slogan);\n\n const response2 = await wrappedFetch(url);\n const result2 = await response2.text();\n expect(result2).toBe(slogan);\n\n expect(fetch).toHaveBeenCalledTimes(2);\n});\n\nit('should clear cache while respond error', async () => {\n const fetch = vi.fn(() => {\n return Promise.reject(new Error('error'));\n });\n const wrappedFetch = makeFetchCacheable(fetch);\n\n const url = 'https://error.qiankun.org';\n await expect(wrappedFetch(url)).rejects.toThrow('error');\n await expect(wrappedFetch(url)).rejects.toThrow('error');\n\n expect(fetch).toHaveBeenCalledTimes(2);\n});\n" }, { "path": "packages/shared/src/fetch-utils/__tests__/makeFetchRetryable.test.ts", "content": "// @vitest-environment edge-runtime\nimport { expect, it, vi } from 'vitest';\nimport { makeFetchRetryable } from '../makeFetchRetryable';\n\nconst slogan = 'Hello Qiankun 3.0';\n\nit('should retry automatically while fetch throw error', async () => {\n const retryTimes = 3;\n let count = 0;\n const fetch = vi.fn(() => {\n if (count < retryTimes) {\n count++;\n throw new Error('network error');\n }\n return Promise.resolve(new Response(slogan, { status: 201 }));\n });\n const wrappedFetch = makeFetchRetryable(fetch, retryTimes);\n const url = 'https://success.qiankun.org';\n const res = await wrappedFetch(url);\n expect(res.status).toBe(201);\n expect(fetch).toHaveBeenCalledTimes(4);\n});\n\nit('should work well while response status is 200', async () => {\n const fetch = vi.fn(() => {\n return Promise.resolve(new Response(slogan, { status: 200 }));\n });\n const wrappedFetch = makeFetchRetryable(fetch);\n const url = 'https://success.qiankun.org';\n const res = await wrappedFetch(url);\n expect(res.status).toBe(200);\n expect(fetch).toHaveBeenCalledTimes(1);\n});\n" }, { "path": "packages/shared/src/fetch-utils/__tests__/makeFetchThrowable.test.ts", "content": "/**\n * @author Kuitos\n * @since 2024-03-05\n */\nimport { expect, it, vi } from 'vitest';\nimport { makeFetchThrowable } from '../makeFetchThrowable';\n\nconst slogan = 'Hello Qiankun 3.0';\n\nit('should throw error while response status is not 200~400', async () => {\n expect.assertions(2);\n const fetch = vi.fn(() => {\n return Promise.resolve(new Response(slogan, { status: 400 }));\n });\n const wrappedFetch = makeFetchThrowable(fetch);\n const url = 'https://success.qiankun.org';\n try {\n await wrappedFetch(url);\n } catch (e) {\n const error = e as unknown as Error;\n expect(error.message).include('RESPONSE_ERROR_AS_STATUS_INVALID');\n expect(error.message).include(url);\n }\n});\n\nit('should prepend url to error message while fetch failed', async () => {\n expect.assertions(1);\n const fetch = vi.fn(() => {\n return Promise.reject(new Error('Failed to fetch'));\n });\n const wrappedFetch = makeFetchThrowable(fetch);\n const url = 'https://fail.qiankun.org';\n try {\n await wrappedFetch(url);\n } catch (e) {\n const error = e as unknown as Error;\n expect(error.message).toBe(`${url} Failed to fetch`);\n }\n});\n\nit('should work well while response status is 200', async () => {\n const fetch = vi.fn(() => {\n return Promise.resolve(new Response(slogan, { status: 200 }));\n });\n const wrappedFetch = makeFetchThrowable(fetch);\n const url = 'https://success.qiankun.org';\n const res = await wrappedFetch(url);\n expect(res.status).toBe(200);\n});\n\nit('should still throw error when error.message is readonly', async () => {\n expect.assertions(1);\n const readonlyError = new TypeError('Network error');\n Object.defineProperty(readonlyError, 'message', {\n value: 'Network error',\n writable: false,\n configurable: false,\n });\n const fetch = vi.fn(() => {\n return Promise.reject(readonlyError);\n });\n const wrappedFetch = makeFetchThrowable(fetch);\n const url = 'https://readonly.qiankun.org';\n try {\n await wrappedFetch(url);\n } catch (e) {\n // The error should still be thrown even if message is readonly\n expect(e).toBe(readonlyError);\n }\n});\n\nit('should prepend url when url is a URL object', async () => {\n expect.assertions(1);\n const fetch = vi.fn(() => {\n return Promise.reject(new Error('Failed to fetch'));\n });\n const wrappedFetch = makeFetchThrowable(fetch);\n const url = new URL('https://url-object.qiankun.org/path');\n try {\n await wrappedFetch(url);\n } catch (e) {\n const error = e as unknown as Error;\n expect(error.message).toBe(`${url.href} Failed to fetch`);\n }\n});\n\nit('should prepend url when url is a Request object', async () => {\n expect.assertions(1);\n const fetch = vi.fn(() => {\n return Promise.reject(new Error('Failed to fetch'));\n });\n const wrappedFetch = makeFetchThrowable(fetch);\n const request = new Request('https://request-object.qiankun.org/path');\n try {\n await wrappedFetch(request);\n } catch (e) {\n const error = e as unknown as Error;\n expect(error.message).toBe(`${request.url} Failed to fetch`);\n }\n});\n" }, { "path": "packages/shared/src/fetch-utils/makeFetchCacheable.ts", "content": "/**\n * @author Kuitos\n * @since 2023-11-06\n * wrap fetch with lru cache\n */\nimport { once } from 'lodash';\nimport { LRUCache } from './miniLruCache';\nimport { type Fetch, isValidResponse } from './utils';\n\nconst getCacheKey = (input: Parameters[0]): string => {\n return typeof input === 'string' ? input : 'url' in input ? input.url : input.href;\n};\n\nconst getGlobalCache = once(() => {\n return new LRUCache>(50);\n});\n\nexport const makeFetchCacheable: (fetch: Fetch) => Fetch = (fetch) => {\n const lruCache = getGlobalCache();\n\n const cachedFetch: Fetch = (input, init) => {\n const fetchInput = input;\n const cacheKey = getCacheKey(fetchInput);\n const wrapFetchPromise = async (promise: Promise): Promise => {\n try {\n const res = await promise;\n\n const { status } = res;\n if (!isValidResponse(status)) {\n lruCache.delete(cacheKey);\n }\n\n // must clone the response as one response body can only be read once as a stream\n return res.clone();\n } catch (e) {\n lruCache.delete(cacheKey);\n throw e;\n }\n };\n\n const cachedFetchPromise = lruCache.get(cacheKey);\n if (cachedFetchPromise) {\n return wrapFetchPromise(cachedFetchPromise);\n }\n\n const fetchPromise = fetch(fetchInput, init);\n lruCache.set(cacheKey, fetchPromise);\n\n return wrapFetchPromise(fetchPromise);\n };\n\n return cachedFetch;\n};\n" }, { "path": "packages/shared/src/fetch-utils/makeFetchRetryable.ts", "content": "/**\n * @author Kuitos\n * @since 2024-03-05\n */\n\nimport { type Fetch } from './utils';\n\nexport const makeFetchRetryable: (fetch: Fetch, retryTimes?: number) => Fetch = (fetch, retryTimes = 1) => {\n let retryCount = 0;\n\n const fetchWithRetryable: Fetch = async (input, init) => {\n try {\n return await fetch(input, init);\n } catch (e) {\n if (retryCount < retryTimes) {\n retryCount++;\n\n if (process.env.NODE_ENV === 'development') {\n console.debug(\n `[qiankun] fetch retrying --> url: ${\n typeof input === 'string' ? input : 'url' in input ? input.url : input.href\n } , time: ${retryCount}`,\n );\n }\n\n return await fetchWithRetryable(input, init);\n }\n\n throw e;\n }\n };\n\n return fetchWithRetryable;\n};\n" }, { "path": "packages/shared/src/fetch-utils/makeFetchThrowable.ts", "content": "/**\n * @author Kuitos\n * @since 2024-03-05\n * wrap fetch to throw error when response status is not 200~400\n */\n\nimport { type Fetch, isValidResponse } from './utils';\n\nexport const makeFetchThrowable: (fetch: Fetch) => Fetch = (fetch) => {\n return async (url, init) => {\n const urlString = typeof url === 'string' ? url : 'url' in url ? url.url : url.href;\n\n let res: Response;\n try {\n res = await fetch(url, init);\n } catch (e) {\n // The error message of fetch failed is usually \"Failed to fetch\"\n // We need to prepend the url to the error message to make it easier to debug\n // e.g. \"https://example.com/script.js Failed to fetch\"\n try {\n if (e instanceof Error && !e.message.includes(urlString)) {\n e.message = `${urlString} ${e.message}`;\n }\n } catch (_) {\n // e.message may be readonly\n }\n throw e;\n }\n\n if (!isValidResponse(res.status)) {\n throw new Error(`${urlString} [RESPONSE_ERROR_AS_STATUS_INVALID] ${res.status} ${res.statusText}`);\n }\n\n return res;\n };\n};\n" }, { "path": "packages/shared/src/fetch-utils/miniLruCache.ts", "content": "export class LRUCache {\n private readonly capacity: number;\n private cache: Map;\n\n constructor(capacity: number) {\n this.capacity = capacity;\n this.cache = new Map();\n }\n\n get(key: K): V | undefined {\n const value = this.cache.get(key);\n if (value !== undefined) {\n this.cache.delete(key);\n this.cache.set(key, value);\n }\n return value;\n }\n\n set(key: K, value: V): void {\n if (this.cache.has(key)) {\n this.cache.delete(key);\n }\n this.cache.set(key, value);\n if (this.cache.size > this.capacity) {\n const firstKey = this.cache.keys().next().value as K;\n this.cache.delete(firstKey);\n }\n }\n\n delete(key: K): void {\n this.cache.delete(key);\n }\n}\n" }, { "path": "packages/shared/src/fetch-utils/utils.ts", "content": "export type Fetch = typeof window.fetch;\n\nexport const isValidResponse = (status: number): boolean => {\n return status >= 200 && status < 400;\n};\n" }, { "path": "packages/shared/src/index.ts", "content": "/**\n * @author Kuitos\n * @since 2023-05-06\n */\nexport * from './assets-transpilers';\nexport * from './utils';\nexport * from './module-resolver';\nexport * from './common';\nexport * from './reporter';\nexport * from './fetch-utils/makeFetchCacheable';\nexport * from './fetch-utils/makeFetchRetryable';\nexport * from './fetch-utils/makeFetchThrowable';\nexport * from './deferred-queue';\n" }, { "path": "packages/shared/src/module-resolver/__tests__/index.test.ts", "content": "import { describe, expect, it } from 'vitest';\n\nimport { moduleResolver } from '../index';\n\ndescribe('default module resolver', () => {\n const mainAppContainer = document.createElement('div');\n mainAppContainer.innerHTML = `\n \n `;\n\n it('should works well', () => {\n const microAppContainer = document.createElement('div');\n microAppContainer.innerHTML = `\n \n `;\n\n const result1 = moduleResolver('https://unpkg.com/4.0.1/antd', microAppContainer, mainAppContainer);\n expect(result1).toBeUndefined();\n\n const result2 = moduleResolver('https://unpkg.com/4.0.1/lodash.js', microAppContainer, mainAppContainer);\n expect(result2).toStrictEqual({\n name: 'lodash',\n version: '4.0.2',\n url: 'https://unpkg.com/4.0.2/lodash.js',\n });\n\n const result3 = moduleResolver('https://unpkg.com/2.0.1/moment.js', microAppContainer, mainAppContainer);\n expect(result3).toStrictEqual({\n name: 'moment',\n version: '2.1.1',\n url: 'https://unpkg.com/2.1.1/moment.js',\n });\n\n const result4 = moduleResolver('https://unpkg.com/4.0.2/antd', microAppContainer, mainAppContainer);\n expect(result4).toBeUndefined();\n });\n});\n" }, { "path": "packages/shared/src/module-resolver/__tests__/satisfies.test.ts", "content": "import { describe, expect, it } from 'vitest';\nimport { satisfies } from '../satisfies';\n\ndescribe('satisfies wrapper', () => {\n describe('full wildcards', () => {\n it('should match * wildcard', () => {\n expect(satisfies('1.2.3', '*')).toBe(true);\n expect(satisfies('0.0.1', '*')).toBe(true);\n });\n\n it('should match x wildcard', () => {\n expect(satisfies('1.2.3', 'x')).toBe(true);\n expect(satisfies('1.2.3', 'X')).toBe(true);\n });\n\n it('should not match prerelease by default', () => {\n expect(satisfies('1.0.0-alpha', '*')).toBe(false);\n expect(satisfies('1.0.0-alpha', 'x')).toBe(false);\n });\n });\n\n describe('short wildcards (N.x format)', () => {\n it('should match major.x format', () => {\n expect(satisfies('1.0.0', '1.x')).toBe(true);\n expect(satisfies('1.2.3', '1.x')).toBe(true);\n expect(satisfies('1.99.99', '1.x')).toBe(true);\n });\n\n it('should not match different major version', () => {\n expect(satisfies('0.9.9', '1.x')).toBe(false);\n expect(satisfies('2.0.0', '1.x')).toBe(false);\n });\n\n it('should handle * and X variants', () => {\n expect(satisfies('1.2.3', '1.*')).toBe(true);\n expect(satisfies('1.2.3', '1.X')).toBe(true);\n expect(satisfies('2.0.0', '1.*')).toBe(false);\n });\n\n it('should not match prerelease by default', () => {\n expect(satisfies('1.0.0-alpha', '1.x')).toBe(false);\n expect(satisfies('1.0.0-alpha', '1.*')).toBe(false);\n });\n });\n\n describe('standard ranges (passthrough)', () => {\n it('should handle caret ranges', () => {\n expect(satisfies('1.2.3', '^1.0.0')).toBe(true);\n expect(satisfies('2.0.0', '^1.0.0')).toBe(false);\n });\n\n it('should handle tilde ranges', () => {\n expect(satisfies('1.2.5', '~1.2.0')).toBe(true);\n expect(satisfies('1.3.0', '~1.2.0')).toBe(false);\n });\n\n it('should handle full wildcards with segments', () => {\n expect(satisfies('1.2.3', '1.2.x')).toBe(true);\n expect(satisfies('1.2.3', '1.x.x')).toBe(true);\n expect(satisfies('1.2.3', '1.2.*')).toBe(true);\n });\n });\n\n describe('prerelease versions (semver-compatible)', () => {\n it('should not match prerelease when range has no prerelease', () => {\n expect(satisfies('1.0.0-alpha', '^1.0.0')).toBe(false);\n expect(satisfies('1.0.1-beta.1', '^1.0.0')).toBe(false);\n expect(satisfies('1.1.0-rc.1', '~1.0.0')).toBe(false);\n });\n\n it('should match prerelease when range includes prerelease', () => {\n expect(satisfies('1.0.0-alpha', '1.0.0-alpha')).toBe(true);\n expect(satisfies('1.0.0-alpha', '>=1.0.0-alpha')).toBe(true);\n });\n\n it('should handle numeric prerelease identifiers', () => {\n expect(satisfies('1.0.0-1', '>=1.0.0-1')).toBe(true);\n expect(satisfies('1.0.0-1', '^1.0.0')).toBe(false);\n });\n\n it('should handle normal versions correctly', () => {\n expect(satisfies('1.0.0', '^1.0.0')).toBe(true);\n expect(satisfies('1.2.3', '^1.0.0')).toBe(true);\n });\n });\n});\n" }, { "path": "packages/shared/src/module-resolver/index.ts", "content": "import { satisfies } from './satisfies';\nimport type { MatchResult } from './types';\n\ndeclare global {\n interface HTMLElement {\n __matched_deps__?: string[];\n }\n}\n\ntype Dependency = {\n url: string;\n version: string;\n range: string;\n peerDeps?: string[];\n};\n\ntype NormalizedDependency = {\n name: string;\n} & Dependency;\n\ntype DependencyMap = {\n dependencies: Record;\n};\n\nexport type { MatchResult } from './types';\n\nexport function moduleResolver(\n url: string,\n microAppContainer: HTMLElement,\n mainAppContainer: HTMLElement,\n): MatchResult | undefined {\n const dependencyMapSelector = 'script[type=dependencymap]';\n\n const microAppDependenciesString = microAppContainer.querySelector(dependencyMapSelector)?.innerHTML;\n if (microAppDependenciesString) {\n const { dependencies } = JSON.parse(microAppDependenciesString) as DependencyMap;\n const normalizedDependencies = normalizeDependencies(dependencies);\n const microAppDependency = normalizedDependencies.find((v) => v.url === url);\n\n if (microAppDependency) {\n const mainAppDependencyMapString = mainAppContainer.querySelector(dependencyMapSelector)?.innerHTML;\n\n if (mainAppDependencyMapString) {\n const mainAppDependencyMap = JSON.parse(mainAppDependencyMapString) as DependencyMap;\n const matchedDeps = (microAppContainer.__matched_deps__ ??= []);\n const matchedDep = findDependency(\n microAppDependency,\n normalizeDependencies(mainAppDependencyMap.dependencies),\n matchedDeps,\n );\n\n if (matchedDep) {\n matchedDeps.push(matchedDep.name);\n return matchedDep;\n }\n }\n }\n }\n\n return undefined;\n}\n\nfunction findDependency(\n dependency: NormalizedDependency,\n mainAppDependencies: NormalizedDependency[],\n matchedDependencies: string[],\n): MatchResult | undefined {\n const matched = mainAppDependencies.find(\n (mainAppDependency) =>\n mainAppDependency.name === dependency.name &&\n satisfies(mainAppDependency.version, dependency.range) &&\n // peer dependencies must be cached before\n (dependency.peerDeps || []).every((peerDep) => matchedDependencies.indexOf(peerDep) !== -1),\n );\n\n if (matched) {\n return {\n name: matched.name,\n version: matched.version,\n url: matched.url,\n };\n }\n\n return undefined;\n}\n\nfunction normalizeDependencies(dependencies: DependencyMap['dependencies']): NormalizedDependency[] {\n return Object.keys(dependencies).map((name) => ({\n name,\n ...dependencies[name],\n }));\n}\n" }, { "path": "packages/shared/src/module-resolver/satisfies.ts", "content": "import { satisfies as compareSatisfies } from 'compare-versions';\n\n/**\n * Semver-compatible satisfies check using compare-versions.\n * Handles edge cases that compare-versions doesn't support:\n * - Full wildcards (*, x, X)\n * - Short wildcards (1.x, 1.*)\n * - Prerelease version behavior\n */\nexport function satisfies(version: string, range: string): boolean {\n const trimmed = range.trim();\n const hasPrerelease = version.includes('-');\n const rangeHasPrerelease = /-[0-9A-Za-z]/.test(trimmed);\n\n // Full wildcards: *, x, X\n if (trimmed === '*' || trimmed.toLowerCase() === 'x') {\n return !hasPrerelease;\n }\n\n // Short wildcards: N.x, N.*, N.X (without third segment)\n const shortMatch = trimmed.match(/^(\\d+)\\.[xX*]$/);\n if (shortMatch) {\n const major = parseInt(shortMatch[1], 10);\n if (hasPrerelease && !rangeHasPrerelease) {\n return false;\n }\n return compareSatisfies(version, `>=${major}.0.0`) && compareSatisfies(version, `<${major + 1}.0.0`);\n }\n\n // Prerelease compatibility: if version is prerelease but range doesn't\n // include prerelease identifier, return false (matching semver behavior)\n if (hasPrerelease && !rangeHasPrerelease) {\n return false;\n }\n\n return compareSatisfies(version, range);\n}\n" }, { "path": "packages/shared/src/module-resolver/types.ts", "content": "/**\n * @author Kuitos\n * @since 2023-08-26\n */\nexport type MatchResult = {\n name: string;\n version: string;\n url: string;\n};\n" }, { "path": "packages/shared/src/reporter/QiankunError.ts", "content": "export class QiankunError extends Error {\n constructor(message: string) {\n super(`[qiankun]: ${message}`);\n }\n}\n" }, { "path": "packages/shared/src/reporter/index.ts", "content": "export { QiankunError } from './QiankunError';\nexport * from './logger';\n" }, { "path": "packages/shared/src/reporter/logger.ts", "content": "export function warn(msg: string, ...args: unknown[]) {\n console.warn(`[qiankun]: ${msg}`, ...args);\n}\n" }, { "path": "packages/shared/src/typings.d.ts", "content": "type Priority = 'high' | 'low' | 'auto';\n\ninterface HTMLScriptElement {\n fetchPriority?: Priority;\n}\n\ninterface RequestInit {\n priority?: Priority;\n}\n" }, { "path": "packages/shared/src/utils.ts", "content": "/**\n * @author Kuitos\n * @since 2023-04-26\n */\n\n// eslint-disable-next-line @typescript-eslint/unbound-method\nexport const { create, defineProperty, getOwnPropertyDescriptor, getOwnPropertyNames, freeze, keys } = Object;\nexport const hasOwnProperty = (caller: unknown, p: PropertyKey) => Object.prototype.hasOwnProperty.call(caller, p);\n\nexport class Deferred {\n promise: Promise;\n\n #status: 'pending' | 'fulfilled' | 'rejected' = 'pending';\n\n resolve!: (value: T | PromiseLike) => void;\n\n reject!: (reason?: unknown) => void;\n\n constructor() {\n this.promise = new Promise((resolve, reject) => {\n this.resolve = (value) => {\n this.#status = 'fulfilled';\n resolve(value);\n };\n this.reject = (reason) => {\n this.#status = 'rejected';\n reject(reason);\n };\n });\n }\n\n isSettled(): boolean {\n return this.#status !== 'pending';\n }\n}\n\nexport async function waitUntilSettled(promise: Promise): Promise {\n try {\n await promise;\n } catch (e) {\n if (process.env.NODE_ENV === 'development') {\n console.warn('waitUntilSettled error', e);\n }\n }\n}\n\nexport function resolveUrl(uri: string, baseURI: string): string {\n // should not handle an entire url especially protocol-relative url, e.g. //example.com/foo.js\n // otherwise it may occur that the user previously stored the script src as //example.com/foo.js,\n // resulting in a conversion to http://example.com/foo.js which does not match the original stored key.\n if (uri.startsWith('//') || uri.startsWith('http://') || uri.startsWith('https://')) {\n return uri;\n }\n\n const publicPath = new URL(baseURI, window.location.href);\n const entireUrl = new URL(uri, publicPath);\n return entireUrl.toString();\n}\n\n/**\n * Check if the running environment support qiankun 3.0\n *\n */\nexport function isRuntimeCompatible(): boolean {\n return (\n // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n typeof Proxy === 'function' && typeof TransformStream === 'function' && typeof URL?.createObjectURL === 'function'\n );\n}\n" }, { "path": "packages/ui-bindings/react/.eslintrc.cjs", "content": "module.exports = {\n extends: ['plugin:react/recommended', require.resolve('../../../.eslintrc.cjs')],\n parserOptions: {\n tsconfigRootDir: __dirname,\n project: ['./tsconfig.json'],\n },\n rules: {\n 'react/display-name': 'off',\n 'react/prop-types': 'off',\n },\n};\n" }, { "path": "packages/ui-bindings/react/.fatherrc.js", "content": "export { default } from '../../../.fatherrc.cjs';\n" }, { "path": "packages/ui-bindings/react/CHANGELOG.md", "content": "# @qiankunjs/react\n\n## 0.0.1-rc.14\n\n### Patch Changes\n\n- ac068ae: fix: remove unused umd bundle configuration\n- Updated dependencies [ac068ae]\n - @qiankunjs/ui-shared@0.0.1-rc.1\n\n## 0.0.1-rc.13\n\n### Patch Changes\n\n- 9ec15954: feat: refactor the code of microapp\n- Updated dependencies [9ec15954]\n - @qiankunjs/ui-shared@0.0.1-rc.0\n\n## 0.0.1-rc.12\n\n### Patch Changes\n\n- Updated dependencies [a8809ecf]\n - qiankun@3.0.0-rc.15\n\n## 0.0.1-rc.11\n\n### Patch Changes\n\n- qiankun@3.0.0-rc.14\n\n## 0.0.1-rc.10\n\n### Patch Changes\n\n- Updated dependencies [f2af2e36]\n - qiankun@3.0.0-rc.13\n\n## 0.0.1-rc.9\n\n### Patch Changes\n\n- Updated dependencies [7cc06bd4]\n- Updated dependencies [312abbc7]\n - qiankun@3.0.0-rc.12\n\n## 0.0.1-rc.8\n\n### Patch Changes\n\n- 43bf37a5: fix(sandbox): should get container from getter function in every accessing\n- Updated dependencies [43bf37a5]\n - qiankun@3.0.0-rc.11\n\n## 0.0.1-rc.7\n\n### Patch Changes\n\n- fix: use qiankun 2.x or 3.x as peerDependencies\n\n## 0.0.1-rc.6\n\n### Patch Changes\n\n- Updated dependencies [2aca545c]\n - qiankun@3.0.0-rc.10\n\n## 0.0.1-rc.5\n\n### Patch Changes\n\n- Updated dependencies [fe68e878]\n - qiankun@3.0.0-rc.9\n\n## 0.0.1-rc.4\n\n### Patch Changes\n\n- Updated dependencies [1d9adcaa]\n - qiankun@3.0.0-rc.8\n\n## 0.0.1-rc.3\n\n### Patch Changes\n\n- qiankun@3.0.0-rc.7\n\n## 0.0.1-rc.2\n\n### Patch Changes\n\n- e7d788ef: feat: not rebind non-native global properties\n- Updated dependencies [317961eb]\n- Updated dependencies [e448082c]\n- Updated dependencies [76b6bff7]\n - qiankun@3.0.0-rc.6\n" }, { "path": "packages/ui-bindings/react/README.md", "content": "# qiankun ui binding for react\n\n## Usage\n\n```bash\nnpm i @qiankunjs/react\n```\n\n## MicroApp component\n\nLoad (or unload) child apps directly through the `` component, which provides loading and error catching-related capabilities:\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\nWhen the sub-app loading animation or error capture capability is enabled, the sub-app accepts an additional style class `wrapperClassName`, and the rendered result is as follows:\n\n```tsx\n
\n \n \n \n
\n```\n\n### Load animation\n\nWhen this capability is enabled, loading animations are automatically displayed when child apps are loading. When the sub-application is mounted and changes to the `MOUNTED` state, the loading status ends and the sub-application content is displayed.\n\nJust pass `autoSetLoading` as a parameter:\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\n#### Custom loading animation\n\nIf you want to override the default loading animation style, you can set a custom loading component `loader` as the loading animation for the child app.\n\n```tsx\nimport CustomLoader from '@/components/CustomLoader';\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return (\n } />\n );\n}\n```\n\nwhere `loading` is the `boolean` type parameter, `true` indicates that the loading state is still being loaded, and `false` indicates that the loading state has ended.\n\n### Error catching\n\nWhen this capability is enabled, an error message is automatically displayed when a child app loads unexpectedly. You can pass the `autoCaptureError` property to the sub-app to enable sub-app error capture capabilities:\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\n#### Custom error capture\n\nIf you want to override the default error capture component style, you can set a custom component `errorBoundary` as the error capture component for the child app:\n\n```tsx\nimport CustomErrorBoundary from '@/components/CustomErrorBoundary';\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return (\n }\n />\n );\n}\n```\n\n### Component Props\n\n| Name | Required | Description | Type | Default |\n| --- | --- | --- | --- | --- |\n| `name` | yes | The name of the microapp | `string` |\n| `entry` | yes | The HTML address of the microapp | `string` |\n| `autoSetLoading` | no | Automatically set the loading state of your microapp | `boolean` | `false` |\n| `loader` | no | Custom microapps load state components | `(loading) => React.ReactNode` | `undefined` |\n| `autoCaptureError` | no | Automatically set up error capture for microapps | `boolean` | `false` |\n| `errorBoundary` | no | Custom microapp error capture component | `(error: any) => React.ReactNode` | `undefined` |\n| `className` | no | The style class for the microapp | `string` | `undefined` |\n| `wrapperClassName` | no | Wrap the microapp loading component, error capture component, and microapp's style classes, and are only valid when the load component or error capture component is enabled | `string` | `undefined` |\n\n## Get the child app load status\n\nThe loading status includes: \"NOT_LOADED\" | \"LOADING_SOURCE_CODE\" | \"NOT_BOOTSTRAPPED\" | \"BOOTSTRAPPING\" | \"NOT_MOUNTED\" | \"MOUNTING\" | \"MOUNTED\" | \"UPDATING\" | \"UNMOUNTING\" | \"UNLOADING\" |\n\n```tsx\nimport { useRef } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n const microAppRef = useRef();\n\n useEffect(() => {\n // Get the child app load status\n console.log(microAppRef.current?.getStatus());\n }, []);\n\n return ;\n}\n```\n" }, { "path": "packages/ui-bindings/react/README.zh-CN.md", "content": "# qiankun ui binding for react\n\n## 安装\n\n```bash\nnpm i @qiankunjs/react\n```\n\n## MicroApp 组件\n\n直接通过 `` 组件加载（或卸载）子应用，该组件提供了 loading 以及错误捕获相关的能力：\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\n当启用子应用加载动画或错误捕获能力时，子应用接受一个额外的样式类 `wrapperClassName`，渲染的结果如下所示：\n\n```tsx\n
\n \n \n \n
\n```\n\n### 加载动画\n\n启用此能力后，当子应用正在加载时，会自动显示加载动画。当子应用挂载完成变成 `MOUNTED` 状态时，加载状态结束，显示子应用内容。\n\n直接将 `autoSetLoading` 作为参数传入即可：\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\n#### 自定义加载动画\n\n如果您希望覆盖默认的加载动画样式时，可以设置一个自定义的加载组件 `loader` 作为子应用的加载动画。\n\n```tsx\nimport CustomLoader from '@/components/CustomLoader';\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return (\n } />\n );\n}\n```\n\n其中，`loading` 为 `boolean` 类型参数，为 `true` 时表示仍在加载状态，为 `false` 时表示加载状态已结束。\n\n### 错误捕获\n\n启用此能力后，当子应用加载出现异常时，会自动显示错误信息。可以向子应用传入 `autoCaptureError` 属性以开启子应用错误捕获能力：\n\n```tsx\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return ;\n}\n```\n\n#### 自定义错误捕获\n\n如果您希望覆盖默认的错误捕获组件样式时，可以设置一个自定义的组件 `errorBoundary` 作为子应用的错误捕获组件：\n\n```tsx\nimport CustomErrorBoundary from '@/components/CustomErrorBoundary';\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n return (\n }\n />\n );\n}\n```\n\n### 组件属性\n\n| 属性 | 必填 | 说明 | 类型 | 默认值 |\n| --- | --- | --- | --- | --- |\n| `name` | 是 | 微应用的名称 | `string` |\n| `entry` | 是 | 微应用的 HTML 地址 | `string` |\n| `autoSetLoading` | 否 | 自动设置微应用的加载状态 | `boolean` | `false` |\n| `loader` | 否 | 自定义的微应用加载状态组件 | `(loading) => React.ReactNode` | `undefined` |\n| `autoCaptureError` | 否 | 自动设置微应用的错误捕获 | `boolean` | `false` |\n| `errorBoundary` | 否 | 自定义的微应用错误捕获组件 | `(error: any) => React.ReactNode` | `undefined` |\n| `className` | 否 | 微应用的样式类 | `string` | `undefined` |\n| `wrapperClassName` | 否 | 包裹微应用加载组件、错误捕获组件和微应用的样式类，仅在启用加载组件或错误捕获组件时有效 | `string` | `undefined` |\n\n## 获取子应用加载状态\n\n加载状态包括：\"NOT_LOADED\" | \"LOADING_SOURCE_CODE\" | \"NOT_BOOTSTRAPPED\" | \"BOOTSTRAPPING\" | \"NOT_MOUNTED\" | \"MOUNTING\" | \"MOUNTED\" | \"UPDATING\" | \"UNMOUNTING\" | \"UNLOADING\" |\n\n```tsx\nimport { useRef } from 'react';\nimport { MicroApp } from '@qiankunjs/react';\n\nexport default function Page() {\n const microAppRef = useRef();\n\n useEffect(() => {\n // 获取子应用加载状态\n console.log(microAppRef.current?.getStatus());\n }, []);\n\n return ;\n}\n```\n" }, { "path": "packages/ui-bindings/react/package.json", "content": "{\n \"name\": \"@qiankunjs/react\",\n \"version\": \"0.0.1-rc.14\",\n \"description\": \"react binding for qiankun\",\n \"main\": \"./dist/cjs/index.js\",\n \"module\": \"./dist/esm/index.js\",\n \"types\": \"./dist/esm/index.d.ts\",\n \"sideEffects\": false,\n \"scripts\": {\n \"build\": \"father build\",\n \"dev\": \"father dev\"\n },\n \"author\": \"Bravepg\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@qiankunjs/ui-shared\": \"workspace:^\",\n \"lodash\": \"^4.17.11\"\n },\n \"devDependencies\": {\n \"@types/react\": \"^18.0.0\",\n \"eslint-plugin-react\": \"^7.33.2\",\n \"react\": \"^18.2.0\",\n \"react-dom\": \"^18.2.0\"\n },\n \"peerDependencies\": {\n \"react\": \">=16.9.0\",\n \"react-dom\": \">=16.9.0\"\n },\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\"\n },\n \"files\": [\n \"dist\"\n ],\n \"repository\": \"git@github.com:umijs/qiankun.git\"\n}\n" }, { "path": "packages/ui-bindings/react/src/ErrorBoundary.tsx", "content": "import React from 'react';\n\nconst ErrorBoundary: React.FC<{ error: Error }> = ({ error }) =>
{error.message}
;\n\nexport default ErrorBoundary;\n" }, { "path": "packages/ui-bindings/react/src/MicroApp.tsx", "content": "import { isEqual, noop } from 'lodash';\nimport {\n type SharedProps,\n type MicroAppType,\n type SharedSlots,\n unmountMicroApp,\n mountMicroApp,\n updateMicroApp,\n omitSharedProps,\n} from '@qiankunjs/ui-shared';\nimport React, { type Ref, forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';\nimport ErrorBoundary from './ErrorBoundary';\nimport MicroAppLoader from './MicroAppLoader';\n\nexport type Props = SharedProps & SharedSlots & Record;\n\nfunction useDeepCompare(value: T): T {\n const ref = useRef(value);\n if (!isEqual(value, ref.current)) {\n ref.current = value;\n }\n\n return ref.current;\n}\n\nexport const MicroApp = forwardRef((componentProps: Props, componentRef: Ref) => {\n const { name, autoSetLoading, autoCaptureError, wrapperClassName, className, loader, errorBoundary } = componentProps;\n\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState();\n const containerRef = useRef(null);\n const microAppRef = useRef();\n\n // 未配置自定义 errorBoundary 且开启了 autoCaptureError 场景下，使用插件默认的 errorBoundary，否则使用自定义 errorBoundary\n const microAppErrorBoundary = errorBoundary || (autoCaptureError ? (e) => : null);\n\n // 配置了 errorBoundary 才改 error 状态，否则直接往上抛异常\n const setComponentError = (e: Error | undefined) => {\n if (microAppErrorBoundary) {\n setError(e);\n // error log 出来，不要吞\n if (e) {\n console.error(e);\n }\n } else if (e) {\n throw e;\n }\n };\n\n const onError = (e: Error) => {\n setComponentError(e);\n setLoading(false);\n };\n\n useImperativeHandle(componentRef, () => microAppRef.current);\n\n useEffect(() => {\n mountMicroApp({\n prevMicroApp: microAppRef.current,\n container: containerRef.current!,\n componentProps,\n setLoading,\n setError: setComponentError,\n })\n .then((app) => {\n microAppRef.current = app;\n })\n .catch((e: Error) => {\n onError(e);\n });\n\n return () => {\n const microApp = microAppRef.current;\n if (microApp && microApp.getStatus() === 'MOUNTED') {\n // 微应用 unmount 是异步的，中间的流转状态不能确定，所有需要一个标志位来确保 unmount 开始之后不会再触发 update\n microApp._unmounting = true;\n unmountMicroApp(microApp).catch((e: Error) => {\n onError(e);\n });\n }\n };\n }, [name]);\n\n useEffect(() => {\n updateMicroApp({\n name,\n microApp: microAppRef.current,\n microAppProps: omitSharedProps(componentProps),\n setLoading,\n });\n\n return noop;\n }, [useDeepCompare(omitSharedProps(componentProps))]);\n\n // 未配置自定义 loader 且开启了 autoSetLoading 场景下，使用插件默认的 loader，否则使用自定义 loader\n const microAppLoader =\n loader || (autoSetLoading ? (loadingStatus) => : null);\n\n const microAppWrapperClassName = wrapperClassName\n ? `${wrapperClassName} qiankun-micro-app-wrapper`\n : 'qiankun-micro-app-wrapper';\n const microAppClassName = className ? `${className} qiankun-micro-app-container` : 'qiankun-micro-app-container';\n\n return microAppLoader || microAppErrorBoundary ? (\n
\n {microAppLoader && microAppLoader(loading)}\n {microAppErrorBoundary && error && microAppErrorBoundary(error)}\n
\n
\n ) : (\n
\n );\n});\n" }, { "path": "packages/ui-bindings/react/src/MicroAppLoader.tsx", "content": "import React from 'react';\n\nconst MicroAppLoader: React.FC<{ loading: boolean }> = ({ loading }) => {\n if (loading) {\n return <>loading...;\n }\n\n return null;\n};\n\nexport default MicroAppLoader;\n" }, { "path": "packages/ui-bindings/react/src/index.ts", "content": "export * from './MicroApp';\n" }, { "path": "packages/ui-bindings/react/tsconfig.json", "content": "{\n \"extends\": \"../../../tsconfig.json\",\n \"compilerOptions\": {\n \"jsx\": \"react\",\n \"paths\": {\n \"qiankun\": [\"packages/qiankun/src\"]\n }\n }\n}\n" }, { "path": "packages/ui-bindings/shared/.fatherrc.js", "content": "export { default } from '../../../.fatherrc.cjs';\n" }, { "path": "packages/ui-bindings/shared/CHANGELOG.md", "content": "# @qiankunjs/ui-shared\n\n## 0.0.1-rc.1\n\n### Patch Changes\n\n- ac068ae: fix: remove unused umd bundle configuration\n\n## 0.0.1-rc.0\n\n### Patch Changes\n\n- 9ec15954: feat: refactor the code of microapp\n" }, { "path": "packages/ui-bindings/shared/package.json", "content": "{\n \"name\": \"@qiankunjs/ui-shared\",\n \"version\": \"0.0.1-rc.1\",\n \"description\": \"ui binding shared for qiankun\",\n \"main\": \"./dist/cjs/index.js\",\n \"module\": \"./dist/esm/index.js\",\n \"types\": \"./src/index.ts\",\n \"sideEffects\": false,\n \"scripts\": {\n \"build\": \"father build\",\n \"dev\": \"father dev\"\n },\n \"author\": \"linghaoSu\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"lodash\": \"^4.17.11\"\n },\n \"devDependencies\": {\n \"qiankun\": \"workspace:^\"\n },\n \"peerDependencies\": {\n \"qiankun\": \"^3.0.0-rc.15\"\n },\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\"\n },\n \"files\": [\n \"dist\"\n ],\n \"repository\": \"git@github.com:umijs/qiankun.git\"\n}\n" }, { "path": "packages/ui-bindings/shared/src/index.ts", "content": "import type { AppConfiguration, MicroApp as MicroAppTypeDefinition, LifeCycles } from 'qiankun';\nimport { loadMicroApp } from 'qiankun';\nimport { mergeWith, concat, omit } from 'lodash';\nimport type { LifeCycleFn } from 'qiankun';\n\nexport type MicroAppType = {\n _unmounting?: boolean;\n _updatingPromise?: Promise;\n _updatingTimestamp?: number;\n} & MicroAppTypeDefinition;\n\nexport type SharedProps = {\n name: string;\n entry: string;\n settings?: AppConfiguration;\n lifeCycles?: LifeCycles>;\n\n autoSetLoading?: boolean;\n autoCaptureError?: boolean;\n // 仅开启 loader 时需要\n wrapperClassName?: string;\n className?: string;\n};\n\nexport type SharedSlots = {\n loader?: (loading: boolean) => T;\n errorBoundary?: (error: Error) => T;\n};\n\nexport const omitSharedProps = (props: Partial) => {\n return omit(props, ['wrapperClassName', 'className', 'lifeCycles', 'settings', 'entry', 'name']);\n};\n\nexport async function mountMicroApp({\n prevMicroApp,\n container,\n componentProps,\n setLoading,\n setError,\n}: {\n prevMicroApp?: MicroAppType;\n container: HTMLDivElement;\n componentProps: SharedProps;\n setLoading?: (loading: boolean) => void;\n setError?: (error?: Error) => void;\n}) {\n if (!componentProps.name || !componentProps.entry) {\n console.error('the name and entry of MicroApp is needed');\n return;\n }\n\n // 等待 prevMicroApp 卸载完成\n if (prevMicroApp?._unmounting) {\n await prevMicroApp.unmountPromise;\n }\n\n setError?.(undefined);\n setLoading?.(true);\n\n const microAppProps = omitSharedProps(componentProps);\n const configuration = {\n globalContext: window,\n ...(componentProps.settings || {}),\n };\n\n const microApp = loadMicroApp(\n {\n name: componentProps.name,\n entry: componentProps.entry,\n container,\n props: microAppProps,\n },\n configuration,\n mergeWith(\n {},\n componentProps.lifeCycles,\n (v1: LifeCycleFn>, v2: LifeCycleFn>) => concat(v1, v2),\n ),\n );\n\n microApp.mountPromise\n .then(() => {\n if (componentProps.autoSetLoading) {\n setLoading?.(false);\n }\n })\n .catch((err: Error) => {\n setError?.(err);\n setLoading?.(false);\n });\n\n (['loadPromise', 'bootstrapPromise'] as const).forEach((key) => {\n const promise = microApp[key];\n\n promise.catch((e: Error) => {\n setError?.(e);\n setLoading?.(false);\n });\n });\n\n return microApp;\n}\n\nexport function updateMicroApp({\n name,\n microApp,\n microAppProps,\n setLoading,\n}: {\n name?: string;\n microApp?: MicroAppType;\n microAppProps?: Record;\n setLoading?: (loading: boolean) => void;\n}) {\n if (microApp) {\n if (!microApp._updatingPromise) {\n // 初始化 updatingPromise 为 microApp.mountPromise，从而确保后续更新是在应用 mount 完成之后\n microApp._updatingPromise = microApp.mountPromise;\n microApp._updatingTimestamp = Date.now();\n } else {\n // 确保 microApp.update 调用是跟组件状态变更顺序一致的，且后一个微应用更新必须等待前一个更新完成\n microApp._updatingPromise = microApp._updatingPromise.then(() => {\n const canUpdate = (app: MicroAppType) => app.update && app.getStatus() === 'MOUNTED' && !app._unmounting;\n if (canUpdate(microApp)) {\n const props = {\n ...microAppProps,\n setLoading(l: boolean) {\n setLoading?.(l);\n },\n };\n\n if (process.env.NODE_ENV === 'development') {\n const updatingTimestamp = microApp._updatingTimestamp!;\n if (Date.now() - updatingTimestamp < 200) {\n console.warn(\n `[@qiankunjs/ui-shared] It seems like microApp ${name} is updating too many times in a short time(200ms), you may need to do some optimization to avoid the unnecessary re-rendering.`,\n );\n }\n\n console.info(`[@qiankunjs/ui-shared}] MicroApp ${name} is updating with props: `, props);\n microApp._updatingTimestamp = Date.now();\n }\n\n // 返回 microApp.update 形成链式调用\n return microApp.update?.(props);\n }\n\n return void 0;\n });\n }\n }\n}\n\nexport async function unmountMicroApp(microApp: MicroAppType) {\n await microApp.mountPromise.then(() => microApp.unmount());\n}\n" }, { "path": "packages/ui-bindings/shared/tsconfig.json", "content": "{\n \"extends\": \"../../../tsconfig.json\",\n \"compilerOptions\": {\n \"paths\": {\n \"qiankun\": [\"packages/qiankun/src\"]\n }\n }\n}\n" }, { "path": "packages/ui-bindings/vue/.fatherrc.js", "content": "export { default } from '../../../.fatherrc.cjs';\n" }, { "path": "packages/ui-bindings/vue/CHANGELOG.md", "content": "# @qiankunjs/vue\n\n## 0.0.1-rc.2\n\n### Patch Changes\n\n- f6926d3: fix(vue): add unmount hook to unmount application\n\n## 0.0.1-rc.1\n\n### Patch Changes\n\n- ac068ae: fix: remove unused umd bundle configuration\n- Updated dependencies [ac068ae]\n - @qiankunjs/ui-shared@0.0.1-rc.1\n\n## 0.0.1-rc.0\n\n### Patch Changes\n\n- 9ec15954: feat: refactor the code of microapp\n- Updated dependencies [9ec15954]\n - @qiankunjs/ui-shared@0.0.1-rc.0\n" }, { "path": "packages/ui-bindings/vue/README.md", "content": "# qiankun vue binding\n\n## Usage\n\n```bash\nnpm i @qiankunjs/vue\n```\n\n## MicroApp Component\n\nLoad (or unload) a sub-application directly through the `` component, which provides capabilities related to loading and error capturing:\n\n```vue\n\n\n```\n\nWhen enabling the sub-application loading animation or error capturing capabilities, an additional style class `wrapperClassName` is accepted by the sub-application. The rendered result is as follows:\n\n```vue\n
\n \n \n \n
\n```\n\n### Loading Animation\n\nAfter enabling this feature, a loading animation will automatically be displayed while the sub-application is loading. When the sub-application finishes mounting and becomes in the MOUNTED state, the loading state ends, and the sub-application content is displayed.\n\nSimply pass `autoSetLoading` as a parameter:\n\n```vue\n\n\n```\n\n#### Custom Loading Animation\n\nIf you wish to override the default loading animation style, you can customize the loading component by using the loader slot as the sub-application's loading animation.\n\n```vue\n\n\n```\n\nHere, `loading` is a boolean type parameter; when true, it indicates that it is still in the loading state, and when false, it indicates that the loading state has ended.\n\n### Error Capturing\n\nAfter enabling this feature, when the sub-application encounters an exception while loading, an error message will automatically be displayed. You can pass the `autoCaptureError` property to the sub-application to enable error capturing capabilities:\n\n```vue\n\n\n```\n\n#### Custom Error Capturing\n\nIf you wish to override the default error capturing component style, you can customize the error capturing component for the sub-application using the errorBoundary slot:\n\n```vue\n\n\n```\n\n### Component Properties\n\n| Property | Required | Description | Type | Default Value |\n| --- | --- | --- | --- | --- |\n| `name` | Yes | The name of the micro-application | `string` | |\n| `entry` | Yes | The HTML address of the micro-application | `string` | |\n| `autoSetLoading` | No | Automatically set the loading status of the micro-application | `boolean` | `false` |\n| `autoCaptureError` | No | Automatically set error capturing for the micro-application | `boolean` | `false` |\n| `className` | No | The style class for the micro-application | `string` | `undefined` |\n| `wrapperClassName` | No | The style class wrapping the micro-application's loading and error components | `string` | `undefined` |\n| `appProps` | No | Properties passed to the sub-application | `Record` | `undefined` |\n\n### Component Slots\n\n| Slot | Description |\n| --------------- | -------------------- |\n| `loader` | Loading state slot |\n| `errorBoundary` | Error capturing slot |\n" }, { "path": "packages/ui-bindings/vue/README.zh-CN.md", "content": "# qiankun vue binding\n\n## Usage\n\n```bash\nnpm i @qiankunjs/vue\n```\n\n## MicroApp 组件\n\n直接通过 组件加载（或卸载）子应用，该组件提供了 loading 以及错误捕获相关的能力：\n\n```vue\n\n\n```\n\n当启用子应用加载动画或错误捕获能力时，子应用接受一个额外的样式类 wrapperClassName，渲染的结果如下所示：\n\n```vue\n
\n \n \n \n
\n```\n\n### 加载动画\n\n启用此能力后，当子应用正在加载时，会自动显示加载动画。当子应用挂载完成变成 MOUNTED 状态时，加载状态结束，显示子应用内容。\n\n直接将 autoSetLoading 作为参数传入即可：\n\n```vue\n\n\n```\n\n#### 自定义加载动画\n\n如果您希望覆盖默认的加载动画样式时，可以通过 loader slot 来自定义加载组件 loader 作为子应用的加载动画。\n\n```vue\n\n\n```\n\n其中，loading 为 boolean 类型参数，为 true 时表示仍在加载状态，为 false 时表示加载状态已结束。\n\n### 错误捕获\n\n启用此能力后，当子应用加载出现异常时，会自动显示错误信息。可以向子应用传入 autoCaptureError 属性以开启子应用错误捕获能力：\n\n```vue\n\n\n```\n\n#### 自定义错误捕获\n\n如果您希望覆盖默认的错误捕获组件样式时，可以通过 errorBoundary slot 来自定义子应用的错误捕获组件：\n\n```vue\n\n\n```\n\n### 组件属性\n\n| 属性 | 必填 | 说明 | 类型 | 默认值 |\n| --- | --- | --- | --- | --- |\n| `name` | 是 | 微应用的名称 | `string` |\n| `entry` | 是 | 微应用的 HTML 地址 | `string` |\n| `autoSetLoading` | 否 | 自动设置微应用的加载状态 | `boolean` | `false` |\n| `autoCaptureError` | 否 | 自动设置微应用的错误捕获 | `boolean` | `false` |\n| `className` | 否 | 微应用的样式类 | `string` | `undefined` |\n| `wrapperClassName` | 否 | 包裹微应用加载组件、错误捕获组件和微应用的样式类，仅在启用加载组件或错误捕获组件时有效 | `string` | `undefined` |\n| `appProps` | 否 | 传递给子应用的属性 | `Record` | `undefined` |\n\n### 组件插槽\n\n| 插槽 | 说明 |\n| --------------- | ------------ |\n| `loader` | 加载状态插槽 |\n| `errorBoundary` | 错误捕获插槽 |\n" }, { "path": "packages/ui-bindings/vue/package.json", "content": "{\n \"name\": \"@qiankunjs/vue\",\n \"version\": \"0.0.1-rc.2\",\n \"description\": \"vue binding for qiankun\",\n \"main\": \"./dist/cjs/index.js\",\n \"module\": \"./dist/esm/index.js\",\n \"types\": \"./src/index.ts\",\n \"sideEffects\": false,\n \"scripts\": {\n \"build\": \"father build\",\n \"dev\": \"father dev\"\n },\n \"author\": \"linghaoSu\",\n \"license\": \"MIT\",\n \"dependencies\": {\n \"@qiankunjs/ui-shared\": \"workspace:^\",\n \"lodash\": \"^4.17.11\",\n \"vue-demi\": \"^0.14.6\"\n },\n \"devDependencies\": {\n \"eslint-plugin-vue\": \"^9.18.1\",\n \"vue\": \"^3.3.9\",\n \"vue2\": \"npm:vue@2.6.11\"\n },\n \"peerDependencies\": {\n \"@vue/composition-api\": \"^1.7.2\",\n \"vue\": \"^2.0.0 || >=3.0.0\"\n },\n \"peerDependenciesMeta\": {\n \"@vue/composition-api\": {\n \"optional\": true\n }\n },\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org/\"\n },\n \"files\": [\n \"dist\"\n ],\n \"repository\": \"git@github.com:umijs/qiankun.git\"\n}\n" }, { "path": "packages/ui-bindings/vue/src/ErrorBoundary.ts", "content": "import { defineComponent, h } from 'vue-demi';\n\nexport default defineComponent({\n props: {\n error: {\n type: Error,\n default: undefined,\n },\n },\n render() {\n return h('div', this.error?.message);\n },\n});\n" }, { "path": "packages/ui-bindings/vue/src/MicroApp.ts", "content": "import type { PropType } from 'vue-demi';\nimport {\n computed,\n defineComponent,\n h,\n onMounted,\n ref,\n onBeforeUnmount,\n shallowRef,\n toRefs,\n watch,\n isVue2,\n} from 'vue-demi';\nimport type { AppConfiguration, LifeCycles } from 'qiankun';\nimport type { MicroAppType } from '@qiankunjs/ui-shared';\nimport { mountMicroApp, omitSharedProps, unmountMicroApp, updateMicroApp } from '@qiankunjs/ui-shared';\n\nimport MicroAppLoader from './MicroAppLoader';\nimport ErrorBoundary from './ErrorBoundary';\n\nexport const MicroApp = defineComponent({\n name: 'MicroApp',\n props: {\n name: {\n type: String,\n required: true,\n },\n entry: {\n type: String,\n required: true,\n },\n settings: {\n type: Object as PropType,\n default: () => ({\n sandbox: true,\n }),\n },\n lifeCycles: {\n type: Object as PropType>>,\n },\n autoSetLoading: {\n type: Boolean,\n default: false,\n },\n autoCaptureError: {\n type: Boolean,\n default: false,\n },\n wrapperClassName: {\n type: String,\n default: undefined,\n },\n className: {\n type: String,\n default: undefined,\n },\n appProps: {\n type: Object,\n default: undefined,\n },\n },\n setup(props, { slots }) {\n const originProps = props;\n const { name, wrapperClassName, className, appProps, autoCaptureError } = toRefs(originProps);\n\n const loading = ref(false);\n const error = ref();\n\n const containerRef = ref(null);\n const microAppRef = shallowRef();\n\n const isNeedShowError = computed(() => {\n return slots.errorBoundary || autoCaptureError.value;\n });\n\n // 配置了 errorBoundary 才改 error 状态，否则直接往上抛异常\n const setComponentError = (err: Error | undefined) => {\n if (isNeedShowError.value) {\n error.value = err;\n // error log 出来，不要吞\n if (err) {\n console.error(error);\n }\n } else if (err) {\n throw err;\n }\n };\n\n const rootRef = ref(null);\n\n const unmount = () => {\n const microApp = microAppRef.value;\n\n if (microApp) {\n microApp._unmounting = true;\n\n unmountMicroApp(microApp).catch((err: Error) => {\n setComponentError(err);\n loading.value = false;\n });\n\n microAppRef.value = undefined;\n }\n };\n\n onMounted(() => {\n // watch name 变更切换子应用\n watch(\n name,\n () => {\n const prevApp = microAppRef.value;\n // 销毁上一个子应用\n unmount();\n\n // 初始化下一个子应用\n void mountMicroApp({\n prevMicroApp: prevApp,\n container: containerRef.value!,\n componentProps: {\n ...originProps,\n ...appProps.value,\n },\n setLoading: (l) => {\n loading.value = l;\n },\n setError: (err?: Error) => {\n setComponentError(err);\n },\n }).then((app) => {\n microAppRef.value = app;\n });\n },\n {\n immediate: true,\n },\n );\n\n watch(\n appProps,\n () => {\n updateMicroApp({\n microApp: microAppRef.value,\n setLoading: (l) => {\n loading.value = l;\n },\n microAppProps: {\n ...omitSharedProps(originProps),\n ...appProps.value,\n },\n });\n },\n {\n deep: true,\n },\n );\n });\n\n onBeforeUnmount(() => {\n unmount();\n });\n\n const microAppWrapperClassName = computed(() =>\n wrapperClassName.value ? `${wrapperClassName.value} qiankun-micro-app-wrapper` : 'qiankun-micro-app-wrapper',\n );\n\n const microAppClassName = computed(() => {\n return className.value ? `${className.value} qiankun-micro-app-container` : 'qiankun-micro-app-container';\n });\n\n return {\n loading,\n error,\n containerRef,\n microAppRef,\n microAppWrapperClassName,\n microAppClassName,\n rootRef,\n microApp: microAppRef,\n };\n },\n\n render() {\n return this.autoSetLoading || this.autoCaptureError || this.$slots.loader || this.$slots.errorBoundary\n ? h(\n 'div',\n {\n class: this.microAppWrapperClassName,\n },\n [\n this.$slots.loader\n ? typeof this.$slots.loader === 'function'\n ? this.$slots.loader(this.loading)\n : this.$slots.loader\n : this.autoSetLoading &&\n h(MicroAppLoader, {\n ...(isVue2\n ? {\n props: {\n loading: this.loading,\n },\n }\n : {\n loading: this.loading,\n }),\n }),\n this.error\n ? this.$slots.errorBoundary\n ? typeof this.$slots.errorBoundary === 'function'\n ? this.$slots.errorBoundary(this.error)\n : this.$slots.errorBoundary\n : this.autoCaptureError &&\n h(ErrorBoundary, {\n ...(isVue2\n ? {\n props: {\n error: this.error,\n },\n }\n : {\n error: this.error,\n }),\n })\n : null,\n h('div', {\n class: this.microAppClassName,\n ref: 'containerRef',\n }),\n ],\n )\n : h('div', {\n class: this.microAppClassName,\n ref: 'containerRef',\n });\n },\n});\n" }, { "path": "packages/ui-bindings/vue/src/MicroAppLoader.ts", "content": "import { defineComponent, h } from 'vue-demi';\n\nexport default defineComponent({\n props: {\n loading: {\n type: Boolean,\n default: false,\n },\n },\n\n render() {\n return h('div', this.loading ? 'loading...' : '');\n },\n});\n" }, { "path": "packages/ui-bindings/vue/src/index.ts", "content": "export * from './MicroApp';\n" }, { "path": "packages/ui-bindings/vue/tsconfig.json", "content": "{\n \"extends\": \"../../../tsconfig.json\",\n \"compilerOptions\": {\n \"paths\": {\n \"qiankun\": [\"packages/qiankun/src\"]\n }\n }\n}\n" }, { "path": "pnpm-workspace.yaml", "content": "packages:\n - \"packages/*\"\n - \"packages/ui-bindings/*\"\n # - \"examples/react15\"\n # - \"examples/react16\"\n # - \"examples/main\"\n" }, { "path": "scripts/generate-release-notes.mjs", "content": "#!/usr/bin/env node\n\n/**\n * Generate unified release notes from individual package CHANGELOGs.\n *\n * Usage: node scripts/generate-release-notes.mjs ''\n *\n * Reads each published package's CHANGELOG.md, extracts the latest version entry,\n * filters out \"Updated dependencies\" noise, and outputs aggregated markdown to stdout.\n */\n\nimport { existsSync, readFileSync, readdirSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst ROOT = resolve(fileURLToPath(import.meta.url), '../..');\n\n/**\n * Scan packages/ directory and build a map of package name → directory path.\n * Handles nested structures like packages/ui-bindings/react/.\n */\nfunction discoverPackageDirs() {\n const dirs = new Map();\n const packagesDir = join(ROOT, 'packages');\n\n function tryRegister(dir) {\n const pkgJsonPath = join(dir, 'package.json');\n if (existsSync(pkgJsonPath)) {\n const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));\n if (pkg.name) {\n dirs.set(pkg.name, dir);\n }\n return true;\n }\n return false;\n }\n\n function scanDir(dir) {\n const registered = tryRegister(dir);\n\n // Also scan subdirectories for nested packages (e.g. ui-bindings/react)\n try {\n const entries = readdirSync(dir, { withFileTypes: true });\n for (const entry of entries) {\n if (entry.isDirectory() && !['node_modules', 'dist', 'src', '.'].includes(entry.name)) {\n const subDir = join(dir, entry.name);\n if (!registered || existsSync(join(subDir, 'package.json'))) {\n scanDir(subDir);\n }\n }\n }\n } catch {\n // ignore read errors\n }\n }\n\n const topLevelDirs = readdirSync(packagesDir, { withFileTypes: true });\n for (const entry of topLevelDirs) {\n if (entry.isDirectory()) {\n scanDir(join(packagesDir, entry.name));\n }\n }\n\n return dirs;\n}\n\n/**\n * Extract the latest version entry from a CHANGELOG.md content string.\n * Returns filtered lines with \"Updated dependencies\" noise removed,\n * or null if no entry is found.\n */\nfunction extractLatestEntry(changelogContent) {\n const lines = changelogContent.split('\\n');\n\n // Find the range of the first ## version section\n let startIndex = -1;\n let endIndex = lines.length;\n\n for (let i = 0; i < lines.length; i++) {\n const line = lines[i];\n // Match \"## \" headings (not ### sub-headings)\n if (/^## \\S/.test(line)) {\n if (startIndex === -1) {\n startIndex = i;\n } else {\n endIndex = i;\n break;\n }\n }\n }\n\n if (startIndex === -1) return null;\n\n const entryLines = lines.slice(startIndex, endIndex);\n\n // Filter out \"Updated dependencies\" blocks:\n // - Updated dependencies [hash]\n // - Updated dependencies [hash]\n // - @pkg/name@version\n // - @pkg/name@version\n const filtered = [];\n let inUpdatedDeps = false;\n\n for (const line of entryLines) {\n if (line.startsWith('- Updated dependencies')) {\n inUpdatedDeps = true;\n continue;\n }\n\n if (inUpdatedDeps) {\n // Indented lines are dependency version references\n if (line.startsWith(' - ')) {\n continue;\n }\n // Any other line exits the block\n inUpdatedDeps = false;\n }\n\n filtered.push(line);\n }\n\n return filtered;\n}\n\n// --- Main ---\n\nconst publishedPackagesJSON = process.argv[2];\nif (!publishedPackagesJSON) {\n console.error('Usage: node scripts/generate-release-notes.mjs \\'\\'');\n process.exit(1);\n}\n\nlet publishedPackages;\ntry {\n publishedPackages = JSON.parse(publishedPackagesJSON);\n} catch (e) {\n console.error('Failed to parse publishedPackages JSON:', e.message);\n process.exit(1);\n}\n\nif (!Array.isArray(publishedPackages) || publishedPackages.length === 0) {\n console.error('No published packages provided.');\n process.exit(1);\n}\n\nconst packageDirs = discoverPackageDirs();\nconst sections = [];\n\n// Sort: qiankun first (facade package), then alphabetical\nconst sorted = [...publishedPackages].sort((a, b) => {\n if (a.name === 'qiankun') return -1;\n if (b.name === 'qiankun') return 1;\n return a.name.localeCompare(b.name);\n});\n\nfor (const { name, version } of sorted) {\n const dir = packageDirs.get(name);\n if (!dir) {\n console.error(`Warning: could not find directory for package \"${name}\"`);\n continue;\n }\n\n const changelogPath = join(dir, 'CHANGELOG.md');\n if (!existsSync(changelogPath)) {\n console.error(`Warning: no CHANGELOG.md found for \"${name}\" at ${changelogPath}`);\n continue;\n }\n\n const content = readFileSync(changelogPath, 'utf-8');\n const entryLines = extractLatestEntry(content);\n\n if (!entryLines || entryLines.length === 0) {\n continue;\n }\n\n // Skip the \"## version\" line (first entry) — we'll use our own formatted header\n const restLines = entryLines.slice(1);\n\n // Trim leading/trailing blank lines\n while (restLines.length > 0 && restLines[0].trim() === '') restLines.shift();\n while (restLines.length > 0 && restLines[restLines.length - 1].trim() === '') restLines.pop();\n\n // If only headings remain with no actual change items, skip this package\n const hasActualChanges = restLines.some((l) => l.startsWith('- '));\n if (!hasActualChanges) {\n continue;\n }\n\n sections.push(`## ${name} \\`${version}\\`\\n\\n${restLines.join('\\n')}`);\n}\n\nif (sections.length === 0) {\n console.error('No changelog entries found for any published package.');\n process.exit(1);\n}\n\nconsole.log(sections.join('\\n\\n'));\n" }, { "path": "tsconfig.eslint.json", "content": "{\n // extend your base config to share compilerOptions, etc\n \"extends\": \"./tsconfig.json\",\n \"compilerOptions\": {\n // ensure that nobody can accidentally use this config for a build\n \"noEmit\": true\n },\n \"include\": [\n // whatever paths you intend to lint\n \"packages/*/src\",\n \"packages/bundler-plugin/tests\",\n \"packages/ui-bindings/*/src\",\n \"vitest.workspace.ts\",\n \"vitest.config.ts\",\n \".fatherrc.js\"\n ]\n}\n" }, { "path": "tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"baseUrl\": \"./\",\n \"target\": \"esnext\",\n \"module\": \"esnext\",\n \"lib\": [\"es2018\", \"dom\"],\n \"declaration\": true,\n \"importHelpers\": false,\n \"downlevelIteration\": true,\n \"strict\": true,\n \"noImplicitAny\": true,\n \"strictNullChecks\": true,\n \"resolveJsonModule\": true,\n \"strictFunctionTypes\": true,\n \"strictPropertyInitialization\": true,\n \"noImplicitThis\": true,\n \"alwaysStrict\": true,\n \"noUnusedLocals\": true,\n \"noUnusedParameters\": true,\n \"noImplicitReturns\": true,\n \"noFallthroughCasesInSwitch\": true,\n \"moduleResolution\": \"node\",\n \"typeRoots\": [\"typings\", \"node_modules/@types\", \"node_modules\"],\n \"allowSyntheticDefaultImports\": true,\n \"esModuleInterop\": true,\n \"types\": [\"vitest/globals\", \"node\"],\n \"paths\": {\n \"@@/*\": [\"./.dumi/tmp/*\"],\n \"@qiankunjs/*\": [\"packages/*/src\"]\n }\n },\n \"exclude\": [\"node_modules\", \"examples\", \"packages/**/dist\"]\n}\n" }, { "path": "vitest.config.ts", "content": "import { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n test: {\n globals: false,\n environment: 'happy-dom',\n },\n});\n" }, { "path": "vitest.workspace.ts", "content": "export default ['packages/*', 'packages/ui-bindings/*'];\n" } ]