@nasti-toolchain/nasti 1.3.9 → 1.4.0

package/dist/index.d.cts

@@ -5,6 +5,8 @@ interface NastiConfig {
     base?: string;
     /** 运行模式 */
     mode?: 'development' | 'production';
+    /** 打包目标平台：web（默认）或 electron */
+    target?: 'web' | 'electron';
     /** 框架自动检测或手动指定 */
     framework?: 'react' | 'vue' | 'auto';
     /** 路径解析配置 */
@@ -15,11 +17,44 @@ interface NastiConfig {
     server?: ServerConfig;
     /** 构建配置 */
     build?: BuildConfig;
+    /** Electron 配置（当 target === 'electron' 时生效） */
+    electron?: ElectronConfig;
     /** 环境变量前缀 */
     envPrefix?: string | string[];
     /** 日志级别 */
     logLevel?: 'info' | 'warn' | 'error' | 'silent';
 }
+/** Electron 目标专用配置，支持 Electron 41+ */
+interface ElectronConfig {
+    /** 主进程入口文件，相对项目根目录 */
+    main?: string;
+    /** Preload 脚本入口，相对项目根目录。可传入多个 */
+    preload?: string | string[];
+    /** 渲染进程（Web）入口 HTML，默认沿用根目录 index.html */
+    renderer?: string;
+    /**
+     * 主进程与 preload 打包目标 Node 版本。
+     * Electron 41 捆绑 Node 22.x，默认为 'node22'
+     */
+    nodeTarget?: string;
+    /**
+     * 主进程输出格式：cjs（默认，兼容 Electron 加载器）或 esm
+     * （Electron 41+ 完整支持 ESM 主进程）
+     */
+    mainFormat?: 'cjs' | 'esm';
+    /** Preload 输出格式，默认 cjs（Electron contextIsolation 推荐） */
+    preloadFormat?: 'cjs' | 'esm';
+    /** Electron 可执行文件路径，默认从 node_modules/electron 查找 */
+    electronPath?: string;
+    /** 传递给 Electron 的命令行参数（dev 模式） */
+    electronArgs?: string[];
+    /** 开发时主/preload 文件变化后自动重启 Electron，默认 true */
+    autoRestart?: boolean;
+    /** 声明最低 Electron 版本，默认 41（低于此版本将警告） */
+    minVersion?: number;
+    /** 主进程/preload 的外部依赖（不参与打包，运行时 require） */
+    external?: string[];
+}
 interface ResolveConfig {
     alias?: Record<string, string>;
     extensions?: string[];
@@ -136,12 +171,14 @@ interface ResolvedConfig {
     root: string;
     base: string;
     mode: 'development' | 'production';
+    target: 'web' | 'electron';
     framework: 'react' | 'vue' | 'auto';
     command: 'build' | 'serve';
     resolve: Required<ResolveConfig>;
     plugins: NastiPlugin[];
     server: Required<ServerConfig>;
     build: Required<BuildConfig>;
+    electron: Required<ElectronConfig>;
     envPrefix: string[];
     logLevel: 'info' | 'warn' | 'error' | 'silent';
 }
@@ -200,6 +237,15 @@ interface HmrUpdate {
 }
 
 declare function defineConfig(config: NastiConfig): NastiConfig;
+/**
+ * Resolve the final configuration by loading file-based config, merging with inline config, and applying plugin hooks.
+ *
+ * Loads configuration from the project root (derived from `inlineConfig.root` or defaults), deep-merges file config with `inlineConfig` (inline takes precedence), runs each plugin's `config` hook and incorporates any returned partial config, constructs the complete `ResolvedConfig` (filling defaults for missing values and resolving tsconfig paths), filters plugins according to their `apply` field, and then invokes each included plugin's `configResolved` hook.
+ *
+ * @param inlineConfig - User-provided configuration that overrides file config and defaults
+ * @param command - The current command, either `"build"` or `"serve"`, which influences mode and plugin filtering
+ * @returns The fully resolved configuration with defaults applied, plugins filtered, and plugin hooks executed
+ */
 declare function resolveConfig(inlineConfig: NastiConfig | undefined, command: 'build' | 'serve'): Promise<ResolvedConfig>;
 
 interface BuildResult {
@@ -212,6 +258,41 @@ interface BuildResult {
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
+interface ElectronBuildResult {
+    rendererOutDir: string;
+    mainFile: string;
+    preloadFiles: string[];
+}
+/**
+ * Performs a full Electron build pipeline producing renderer, main, and preload artifacts.
+ *
+ * Resolves an Electron-targeted config, validates the installed Electron version, prepares the output directory, builds the renderer (via the web build), bundles the main process, bundles configured preload scripts, and logs a summary.
+ *
+ * @param inlineConfig - Optional config overrides merged into the resolved build configuration
+ * @returns An object with `rendererOutDir` (renderer output directory), `mainFile` (bundled main process file path), and `preloadFiles` (array of bundled preload file paths)
+ * @throws Error if the configured Electron main entry file does not exist
+ */
+declare function buildElectron(inlineConfig?: NastiConfig): Promise<ElectronBuildResult>;
+
 declare function createServer(inlineConfig?: NastiConfig): Promise<DevServer>;
 
-export { type DevServer, type HmrPayload, type ModuleNode, type NastiConfig, type NastiPlugin, type ResolvedConfig, type TransformResult, build, createServer, defineConfig, resolveConfig };
+interface ElectronDevOptions extends NastiConfig {
+    /** 不启动 Electron 进程，只编译主/preload（CI 场景） */
+    noSpawn?: boolean;
+}
+/**
+ * Start an Electron-focused development workflow: run the renderer dev server, build the main and preload bundles into .nasti/, and optionally spawn Electron with automatic restarts.
+ *
+ * @param inlineConfig - Development options; when `inlineConfig.noSpawn` is `true`, only compiles main/preload into `.nasti/` and does not start the Electron process.
+ */
+declare function startElectronDev(inlineConfig?: ElectronDevOptions): Promise<void>;
+
+/**
+ * Create a Vite/Rollup plugin that externalizes Electron and Node built-in imports according to the resolved config.
+ *
+ * @param config - Resolved build config; any entries in `config.electron.external` are added to the externalized modules set.
+ * @returns A plugin that marks `electron` and `electron/*` imports and Node built-in modules (including `node:`-prefixed names) as external.
+ */
+declare function electronPlugin(config: ResolvedConfig): NastiPlugin;
+
+export { type DevServer, type ElectronConfig, type HmrPayload, type ModuleNode, type NastiConfig, type NastiPlugin, type ResolvedConfig, type TransformResult, build, buildElectron, createServer, defineConfig, electronPlugin, resolveConfig, startElectronDev };

package/dist/index.d.ts

@@ -5,6 +5,8 @@ interface NastiConfig {
     base?: string;
     /** 运行模式 */
     mode?: 'development' | 'production';
+    /** 打包目标平台：web（默认）或 electron */
+    target?: 'web' | 'electron';
     /** 框架自动检测或手动指定 */
     framework?: 'react' | 'vue' | 'auto';
     /** 路径解析配置 */
@@ -15,11 +17,44 @@ interface NastiConfig {
     server?: ServerConfig;
     /** 构建配置 */
     build?: BuildConfig;
+    /** Electron 配置（当 target === 'electron' 时生效） */
+    electron?: ElectronConfig;
     /** 环境变量前缀 */
     envPrefix?: string | string[];
     /** 日志级别 */
     logLevel?: 'info' | 'warn' | 'error' | 'silent';
 }
+/** Electron 目标专用配置，支持 Electron 41+ */
+interface ElectronConfig {
+    /** 主进程入口文件，相对项目根目录 */
+    main?: string;
+    /** Preload 脚本入口，相对项目根目录。可传入多个 */
+    preload?: string | string[];
+    /** 渲染进程（Web）入口 HTML，默认沿用根目录 index.html */
+    renderer?: string;
+    /**
+     * 主进程与 preload 打包目标 Node 版本。
+     * Electron 41 捆绑 Node 22.x，默认为 'node22'
+     */
+    nodeTarget?: string;
+    /**
+     * 主进程输出格式：cjs（默认，兼容 Electron 加载器）或 esm
+     * （Electron 41+ 完整支持 ESM 主进程）
+     */
+    mainFormat?: 'cjs' | 'esm';
+    /** Preload 输出格式，默认 cjs（Electron contextIsolation 推荐） */
+    preloadFormat?: 'cjs' | 'esm';
+    /** Electron 可执行文件路径，默认从 node_modules/electron 查找 */
+    electronPath?: string;
+    /** 传递给 Electron 的命令行参数（dev 模式） */
+    electronArgs?: string[];
+    /** 开发时主/preload 文件变化后自动重启 Electron，默认 true */
+    autoRestart?: boolean;
+    /** 声明最低 Electron 版本，默认 41（低于此版本将警告） */
+    minVersion?: number;
+    /** 主进程/preload 的外部依赖（不参与打包，运行时 require） */
+    external?: string[];
+}
 interface ResolveConfig {
     alias?: Record<string, string>;
     extensions?: string[];
@@ -136,12 +171,14 @@ interface ResolvedConfig {
     root: string;
     base: string;
     mode: 'development' | 'production';
+    target: 'web' | 'electron';
     framework: 'react' | 'vue' | 'auto';
     command: 'build' | 'serve';
     resolve: Required<ResolveConfig>;
     plugins: NastiPlugin[];
     server: Required<ServerConfig>;
     build: Required<BuildConfig>;
+    electron: Required<ElectronConfig>;
     envPrefix: string[];
     logLevel: 'info' | 'warn' | 'error' | 'silent';
 }
@@ -200,6 +237,15 @@ interface HmrUpdate {
 }
 
 declare function defineConfig(config: NastiConfig): NastiConfig;
+/**
+ * Resolve the final configuration by loading file-based config, merging with inline config, and applying plugin hooks.
+ *
+ * Loads configuration from the project root (derived from `inlineConfig.root` or defaults), deep-merges file config with `inlineConfig` (inline takes precedence), runs each plugin's `config` hook and incorporates any returned partial config, constructs the complete `ResolvedConfig` (filling defaults for missing values and resolving tsconfig paths), filters plugins according to their `apply` field, and then invokes each included plugin's `configResolved` hook.
+ *
+ * @param inlineConfig - User-provided configuration that overrides file config and defaults
+ * @param command - The current command, either `"build"` or `"serve"`, which influences mode and plugin filtering
+ * @returns The fully resolved configuration with defaults applied, plugins filtered, and plugin hooks executed
+ */
 declare function resolveConfig(inlineConfig: NastiConfig | undefined, command: 'build' | 'serve'): Promise<ResolvedConfig>;
 
 interface BuildResult {
@@ -212,6 +258,41 @@ interface BuildResult {
 }
 declare function build(inlineConfig?: NastiConfig): Promise<BuildResult>;
 
+interface ElectronBuildResult {
+    rendererOutDir: string;
+    mainFile: string;
+    preloadFiles: string[];
+}
+/**
+ * Performs a full Electron build pipeline producing renderer, main, and preload artifacts.
+ *
+ * Resolves an Electron-targeted config, validates the installed Electron version, prepares the output directory, builds the renderer (via the web build), bundles the main process, bundles configured preload scripts, and logs a summary.
+ *
+ * @param inlineConfig - Optional config overrides merged into the resolved build configuration
+ * @returns An object with `rendererOutDir` (renderer output directory), `mainFile` (bundled main process file path), and `preloadFiles` (array of bundled preload file paths)
+ * @throws Error if the configured Electron main entry file does not exist
+ */
+declare function buildElectron(inlineConfig?: NastiConfig): Promise<ElectronBuildResult>;
+
 declare function createServer(inlineConfig?: NastiConfig): Promise<DevServer>;
 
-export { type DevServer, type HmrPayload, type ModuleNode, type NastiConfig, type NastiPlugin, type ResolvedConfig, type TransformResult, build, createServer, defineConfig, resolveConfig };
+interface ElectronDevOptions extends NastiConfig {
+    /** 不启动 Electron 进程，只编译主/preload（CI 场景） */
+    noSpawn?: boolean;
+}
+/**
+ * Start an Electron-focused development workflow: run the renderer dev server, build the main and preload bundles into .nasti/, and optionally spawn Electron with automatic restarts.
+ *
+ * @param inlineConfig - Development options; when `inlineConfig.noSpawn` is `true`, only compiles main/preload into `.nasti/` and does not start the Electron process.
+ */
+declare function startElectronDev(inlineConfig?: ElectronDevOptions): Promise<void>;
+
+/**
+ * Create a Vite/Rollup plugin that externalizes Electron and Node built-in imports according to the resolved config.
+ *
+ * @param config - Resolved build config; any entries in `config.electron.external` are added to the externalized modules set.
+ * @returns A plugin that marks `electron` and `electron/*` imports and Node built-in modules (including `node:`-prefixed names) as external.
+ */
+declare function electronPlugin(config: ResolvedConfig): NastiPlugin;
+
+export { type DevServer, type ElectronConfig, type HmrPayload, type ModuleNode, type NastiConfig, type NastiPlugin, type ResolvedConfig, type TransformResult, build, buildElectron, createServer, defineConfig, electronPlugin, resolveConfig, startElectronDev };