跳到主要内容
FarmFarm
2.x(最新)
简体中文
Version: 2.x(最新)
本页目录

JavaScript API

Farm 从 @farmfe/core 暴露 Node.js API,用于开发服务器、生产构建、watch 模式、预览服务器、配置加载、环境变量加载和直接访问编译器。

sh
npm add @farmfe/core@latest
sh
yarn add @farmfe/core@latest
sh
pnpm add @farmfe/core@latest
sh
bun add @farmfe/core@latest

顶层辅助方法

start

ts
start(options?: FarmCliOptions & UserConfig): Promise<void>

启动 Farm 开发服务器。它会以 dev / development 模式解析配置、创建服务器、开始监听、编译项目并打印服务器 URL。

ts
import { start } from '@farmfe/core';
import react from '@farmfe/plugin-react';

await start({
  compilation: {
    input: { index: './index.html' },
    output: { publicPath: '/dist/' }
  },
  server: { port: 6532 },
  plugins: [react()]
});

build

ts
build(options?: FarmCliOptions & UserConfig): Promise<void>

以 build / production 模式解析配置,创建编译器,执行一次编译并将资源写入磁盘。

ts
import { build } from '@farmfe/core';

await build({
  compilation: {
    input: { index: './index.html' },
    output: { path: 'dist' }
  }
});

watch

ts
watch(options?: FarmCliOptions & UserConfig): Promise<void>

以 watch 模式构建,并在监听文件变化时重新构建。如果启用了懒编译,Farm 也会启动懒编译服务器。

ts
import { watch } from '@farmfe/core';

await watch({ compilation: { output: { path: 'dist' } } });

preview

ts
preview(options?: FarmCliOptions & UserConfig): Promise<void>

为已有的生产构建产物启动预览服务器。

ts
import { preview } from '@farmfe/core';

await preview({
  server: {
    preview: { port: 9000, distDir: 'dist' }
  }
});

clean

ts
clean(rootPath: string, recursive?: boolean): Promise<void>

清理解析后项目的 Farm 持久化缓存文件。传入 recursive: true 可递归查找嵌套的 node_modules 目录。

ts
import { clean } from '@farmfe/core';

await clean(process.cwd());

配置和环境辅助方法

defineConfig

ts
import { defineConfig } from '@farmfe/core';
import react from '@farmfe/plugin-react';

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

resolveConfig

ts
resolveConfig(
  inlineConfig?: FarmCliOptions & UserConfig,
  command?: 'dev' | 'build' | 'watch',
  mode?: string
): Promise<ResolvedUserConfig>

在调用 createCompiler 等底层 API 前,先使用 resolveConfig 解析配置。

ts
import { createCompiler, resolveConfig } from '@farmfe/core';

const resolved = await resolveConfig({ root: process.cwd() }, 'build', 'production');
const compiler = createCompiler(resolved);

loadEnv

ts
loadEnv(
  mode: string,
  envDir: string,
  prefixes?: string | string[]
): [env: Record<string, string>, existsEnvFiles: string[]]

从 envDir 加载 .env、.env.local、.env.${mode} 和 .env.${mode}.local。前缀默认是 ['FARM_', 'VITE_']。

ts
import { loadEnv } from '@farmfe/core';

const [env, files] = loadEnv('development', process.cwd());

开发服务器 API

Server.createServer

ts
Server.createServer(options?: FarmCliOptions & UserConfig): Promise<Server>

创建并初始化开发服务器。调用 listen() 开始监听 HTTP 服务并执行初始编译。

ts
import { Server } from '@farmfe/core';

const server = await Server.createServer({ server: { port: 9000 } });
await server.listen();

Server 实例方法

方法描述
listen(): Promise<void>开始监听、编译并设置 watch 行为。
restart(): Promise<Server>关闭当前服务器,并使用相同 inline config 创建替代服务器。
restartServer(): Promise<void>重启并在 host/port 变化时打印 URL。
getCompiler(): Compiler | undefined在服务器开始编译后返回当前编译器。
setCompiler(compiler: Compiler): void替换服务器编译器实例。
addWatchFile(root: string, deps: string[]): void通过编译器添加额外监听文件。
close(): Promise<void>关闭 watcher、WebSocket 服务器和 HTTP 服务器。
printUrls(): void在 listen() 后打印解析出的服务器 URL。

PreviewServer

preview() 是预览模式的高层 API。需要更底层控制时,PreviewServer 可通过 @farmfe/core 的 server 模块导出使用。

编译器 API

从解析后的配置创建编译器:

ts
import { createCompiler, resolveConfig } from '@farmfe/core';

const config = await resolveConfig({}, 'build', 'production');
const compiler = createCompiler(config);
await compiler.compile();
方法描述
compile(): Promise<void>执行一次编译。设置 FARM_PROFILE 时内部使用同步编译。
compileSync(): void同步执行编译。
update(paths, sync?, ignoreCompilingCheck?, generateUpdateResource?): Promise<JsUpdateResult>增量更新模块。paths 是 { path, type } 列表,type 为 added、updated 或 removed。
traceDependencies(): Promise<unknown>从原生编译器返回配置/模块依赖追踪信息。
traceModuleGraph(): Promise<TracedModuleGraph>返回追踪后的模块图。
hasModule(resolvedPath: string): boolean检查解析路径是否在模块图中。
getParentFiles(idOrResolvedPath: string): string[]返回某模块的父模块/导入方。
resources(): Record<string, Buffer>返回按资源名索引的编译资源 buffer。
resource(path: string): Buffer返回单个编译资源 buffer。
resourcesMap(): Record<string, Resource>返回按资源名索引的完整资源元数据。
writeResourcesToDisk(): void写入资源并运行 writeResources 插件 hook。
callWriteResourcesHook(): void不写入资源,仅运行 JS 插件 writeResources hook。开发模式下 server.writeToDisk 禁用时会使用它。
removeOutputPathDir(): void删除配置的输出目录。
resolvedWatchPaths(): string[]返回编译器监听的模块路径。
resolvedModulePaths(root: string): string[]返回 root 下解析出的模块路径。
transformModulePath(root: string, path: string): string将模块路径规范化为文件系统路径。
onUpdateFinish(callback): void在更新完成后排队执行回调。
outputPath(): string返回解析后的输出目录。
addExtraWatchFile(root: string, paths: string[]): void添加额外监听文件。
stats(): unknown返回原生编译器 stats。
waitForCompileFinish(): Promise<void>等待正在进行的编译结束。
invalidateModule(moduleId: string): void使原生编译器中的一个模块失效。
writeMetadata(name, data, options?): void为插件/API 写入 JSON 序列化后的元数据。
readMetadata(name, options?): unknown读取 writeMetadata 写入的元数据。
readMetadataByScope(scope: string): unknown[]按 scope 读取元数据条目。

createInlineCompiler

ts
createInlineCompiler(
  config: ResolvedUserConfig,
  options?: ResolvedCompilation
): Compiler

通过内联覆盖解析后配置中的 compilation 对象来创建编译器。

100%

Drag or pinch to explore. Keyboard: + / − zoom, arrows pan, 0 resets, Esc closes.