@ikaros-cli/ikaros

@ikaros-cli/ikaros

@ikaros-cli/ikaros 是 ikaros 的核心包，包含 CLI、配置系统、插件系统、默认 Rspack adapter、BuildPlan executor、inspect 和 watchdog。

Vite 与 Electron 不内置在核心包中。需要时安装 packages/contrlibs 下发布的可选包，ikaros 会从用户项目依赖中懒加载它们。

ikaros 面向通用前端工程：默认配置只覆盖跨框架的构建基础，尽量降低新项目的启动心智；当项目需要更细的 bundler 能力时，bundle.rspack、bundle.vite 和插件 hook 会保留原生配置出口。

安装

pnpm add -D @ikaros-cli/ikaros

CLI

开发服务：

pnpm exec ikaros --mode development

生产构建：

pnpm exec ikaros build --mode release

检查配置：

pnpm exec ikaros inspect -o ikaros.inspect.json

迁移 v2 配置：

pnpm exec ikaros migrate-config --config ./ikaros.config.mjs
pnpm exec ikaros migrate-config --config ./ikaros.config.mjs --write
pnpm exec ikaros migrate-config --config ./ikaros.config.mjs --output ./ikaros.config.v3.mjs

通用参数：

v3 配置

defineConfig 不要求写完整 schema。没有配置的字段会使用 CLI 内部默认值；只有需要改变默认行为时再写对应命名空间：

import { defineConfig } from '@ikaros-cli/ikaros'

export default defineConfig({
  dev: {
    port: 3000,
  },
  output: {
    sourceMap: true,
  },
})

Vite 高级出口：

import { defineConfig } from '@ikaros-cli/ikaros'
import { defineViteConfig } from '@ikaros-cli/ikaros-bundler-vite'

export default defineConfig({
  bundle: {
    adapter: 'vite',
    vite: {
      config: defineViteConfig({
        server: { host: '127.0.0.1' },
        build: { target: 'esnext' },
      }),
      configFile: './vite.config.ts',
    },
  },
})

vite.config 在生成的 ikaros Vite 配置之后合并，可覆盖底层 Vite 选项。configFile 默认是 false；设置后会将指定的原生 Vite 配置文件交给 Vite 加载。inspect 输出 最终 Vite 配置和 watch plan；开发服务会在该文件变更后重启。

Rspack 的 React/Vue 支持由可选插件提供：

import { defineConfig } from '@ikaros-cli/ikaros'
import { react } from '@ikaros-cli/plugin-react'

export default defineConfig({
  plugins: [react()],
})

import { defineConfig } from '@ikaros-cli/ikaros'
import { vue } from '@ikaros-cli/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})

常见可配置命名空间：

配置函数：

export default defineConfig(({ mode, env, command }) => ({
  source: {
    define: {
      __APP_MODE__: JSON.stringify(mode),
      __API_HOST__: JSON.stringify(env.API_HOST ?? ''),
      __COMMAND__: JSON.stringify(command),
    },
  },
}))

环境变量加载顺序遵循 .env、.env.local、.env.${mode}、.env.${mode}.local 逐级覆盖；如果 shell/CI 已经存在同名变量，则以 shell/CI 的值为准，且不会被 .env 文件覆盖。

最终环境变量会注入为 import.meta.env.KEY：

console.log(import.meta.env.API_HOST)

source.define 只用于裸常量替换，不会自动挂到 import.meta.env：

if (__APP_MODE__ === 'release') {
  // ...
}

页面与入口

未配置 pages 时，默认使用：

index.html
src/index

多页面：

export default defineConfig({
  pages: {
    index: {
      html: './index.html',
      entry: './src/index',
    },
    admin: {
      html: './admin.html',
      entry: './src/admin',
    },
  },
  dev: {
    pages: ['index'],
  },
})

Rspack

Rspack 是默认 bundler。常规项目不需要显式配置 loader；需要扩展时，原生 loader 和 plugin 放在 bundle.rspack：

import { defineConfig } from '@ikaros-cli/ikaros'
import { VizePlugin } from '@vizejs/rspack-plugin'

export default defineConfig({
  bundle: {
    rspack: {
      loaders: [
        {
          test: /\.vue$/,
          loader: '@vizejs/rspack-plugin/loader',
        },
      ],
      plugins: [new VizePlugin()],
    },
  },
})

SWC：

ikaros 内置 builtin:swc-loader，默认只根据扩展名设置必要的 parser，例如 .tsx 会启用 TypeScript 和 JSX 解析。ikaros 不会根据 React/Vue 等框架自动注入框架专属 transform。

需要精细控制 SWC 时，可以通过 bundle.rspack.swc 透传原生选项；这些选项会深合并到默认脚本规则：

export default defineConfig(({ command }) => ({
  bundle: {
    rspack: {
      swc: {
        jsc: {
          transform: {
            react: {
              runtime: 'automatic',
              development: command === 'server',
              refresh: command === 'server',
            },
          },
        },
      },
    },
  },
}))

CDN：

export default defineConfig({
  bundle: {
    rspack: {
      cdn: {
        modules: [
          {
            name: 'vue',
            var: 'Vue',
            path: 'dist/vue.runtime.min.js',
          },
        ],
      },
    },
  },
})

Vite

安装可选包：

pnpm add -D @ikaros-cli/ikaros-bundler-vite vite

配置：

import { defineConfig } from '@ikaros-cli/ikaros'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  bundle: {
    adapter: 'vite',
    vite: {
      plugins: [vue()],
    },
  },
})

库模式

export default defineConfig({
  library: {
    entry: 'src/index.ts',
    name: 'MyLibrary',
    formats: ['es', 'umd'],
    fileName: 'my-library',
    externals: ['vue'],
    globals: {
      vue: 'Vue',
    },
  },
})

Electron

安装可选包：

pnpm add -D @ikaros-cli/ikaros-platform-desktop-client electron

运行：

pnpm exec ikaros --platform desktopClient --mode development
pnpm exec ikaros build --platform desktopClient --mode release

desktopClient 平台生成三个 BuildPlan：

Inspect

inspect 使用与真实编译相同的配置流程，但不会启动 dev server 或 build：

pnpm exec ikaros inspect -o ikaros.inspect.json

输出包含：

• raw config
• current config
• normalized config
• BuildPlan 列表
• 每个 plan 的 bundler config
• 插件 hook trace
• plan provenance
• adapter capability matrix 与启用但不支持的配置告警
• env 与 watchdog 诊断

插件

import type { IkarosPlugin } from '@ikaros-cli/ikaros/plugin'

export const plugin: IkarosPlugin = {
  name: 'example-plugin',
  enforce: 'pre',
  order: 0,
  setup(api) {
    api.modifyBuildPlan((plan) => {
      return {
        ...plan,
        output: {
          ...plan.output,
          sourceMap: true,
        },
      }
    })
  },
}

推荐 hook 顺序：

modifyIkarosConfig
→ platform.createPlans
→ modifyBuildPlans
→ modifyBuildPlan
→ bundler.createConfig
→ modifyRspackRules / modifyRspackPlugins
→ modifyRspackConfig / modifyViteConfig

插件排序：

内置 pre → 用户 pre → 普通 → 用户 post → 内置 post

同组内按 order 和注册顺序排序。

推荐优先使用：

• modifyBuildPlans
• modifyBuildPlan
• modifyRspackRules
• modifyRspackPlugins

高级出口：

• modifyRspackConfig
• modifyViteConfig

底层 bundler config hook 会让插件直接依赖 Rspack/Vite 配置形状，适合少数必须改最终配置的场景。

插件属于一次 CLI 编译会话：Ikaros 在加载配置时一次性注册并初始化插件，完成 build、dev server 或 inspect 后结束本次会话。插件可以通过 hook 修改配置、BuildPlan 和 bundler registry， 也可以参与 build/dev server 生命周期；插件集合在会话开始后不可新增、移除或重放。 modifyIkarosConfig 可以修改 CLI 配置，但不能改变本次会话已经固定的插件集合。 尝试改变该集合会抛出 PLUGIN_SET_IMMUTABLE，应直接在加载的配置文件中声明插件。 bundler hook 的 context 在生成具体 BuildPlan 时提供 plan，Electron 插件可以据此区分 electron-main、electron-preload 和 electron-renderer。

子路径入口

import { defineConfig } from '@ikaros-cli/ikaros/config'
import type { IkarosPlugin } from '@ikaros-cli/ikaros/plugin'
import type { BuildPlan, BundlerAdapter } from '@ikaros-cli/ikaros/adapter'

公开入口：

v2 到 v3 字段映射

旧字段会被 v3 schema 拒绝，并输出迁移建议。