vite-plugin-uni-subpackage-placeholder

Vite plugin for uni-app mini programs: automatically inject componentPlaceholder when a page or component references a custom component from another subpackage.

Works seamlessly with easycom, manual imports, and unplugin-vue-components.

Built-in platform detection — only runs on mini program builds (mp-*). H5 / App are no-ops. No need to wrap with process.env.UNI_PLATFORM in your config.

English | 中文

English

Install

pnpm add -D vite-plugin-uni-subpackage-placeholder

Usage

// vite.config.ts
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import uniSubpackagePlaceholder from 'vite-plugin-uni-subpackage-placeholder'

export default defineConfig({
  plugins: [
    uni(),
    uniSubpackagePlaceholder(['pages-echarts', 'pages-sub', 'pages-sub1']),
  ],
})

Pair with easycom in pages.config.ts:

easycom: {
  custom: {
    'com-chart': '@/pages-echarts/components/common/ComChart.vue',
  },
},
preloadRule: {
  'pages/index': { network: 'all', packages: ['pages-echarts'] },
},

Enable subpackage optimization in manifest.json:

{
  "mp-weixin": {
    "optimization": { "subPackages": true }
  }
}

Options

uniSubpackagePlaceholder({
  /** Subpackage roots in output bundle (without `src/` prefix) */
  include: ['pages-echarts', 'pages-sub', 'pages-sub1'],
  /** Path alias map @default { '@': 'src' } */
  aliasMap: { '@': 'src', '@/': 'src/' },
  /** Placeholder tag name @default 'view' */
  placeholder: 'view',
  /** Target platforms @default all mp-* */
  platforms: ['mp-weixin'],
})

Shorthand — pass an array for include:

uniSubpackagePlaceholder(['pages-echarts', 'pages-sub'])

Platform behavior

| UNI_PLATFORM | Plugin | |----------------|--------| | mp-weixin, mp-alipay, … | Active on build | | h5, app, … | No-op (skipped automatically) |

中文

安装

pnpm add -D vite-plugin-uni-subpackage-placeholder

使用

// vite.config.ts — 无需判断平台，直接注册即可
import uni from '@dcloudio/vite-plugin-uni'
import uniSubpackagePlaceholder from 'vite-plugin-uni-subpackage-placeholder'

export default defineConfig({
  plugins: [
    uni(),
    uniSubpackagePlaceholder(['pages-echarts', 'pages-sub', 'pages-sub1']),
  ],
})

插件内部根据 process.env.UNI_PLATFORM 判断，仅在小程序 build 时生效，H5 / App 自动跳过。

参数

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | include | string[] | [] | 分包根路径（产物路径，如 pages-sub1） | | aliasMap | Record<string, string> | { '@': 'src' } | 路径别名 | | placeholder | string | 'view' | 占位组件名 | | platforms | string[] | 全部 mp-* | 生效平台，可收窄为 ['mp-weixin'] |

License

MIT