fe-stack

fe-stack

一个包含 Vite、Tailwind、ESLint 和 TypeScript 配置的共享包，可以在多个项目中复用。

开发环境使用 pnpm 12.10.1（由 packageManager 固定）。Node.js 需满足 ^20.19.0 || ^22.13.0 || >=24。

安装方法

在项目中安装：

pnpm add -D fe-stack

工具链开箱即用（batteries-included）

fe-stack 已将整套工具链（vite、eslint、prettier、TypeScript、vue-tsc、tailwindcss、@microsoft/api-extractor 等）作为自身 dependencies 一并携带。下游可以复用这些依赖；使用 pnpm 时，按下面的配置提升工具以运行对应 CLI。

⚠️ pnpm 用户必读：pnpm 默认采用严格 node_modules 布局，fe-stack 携带的传递依赖不会出现在你项目顶层的 node_modules/.bin，导致 vite / eslint / prettier 等命令（以及对应的 VS Code 扩展）无法找到对应二进制。请在项目根目录的 pnpm-workspace.yaml 中开启精准提升：

publicHoistPattern:
  - vite
  - eslint
  - prettier
  - eslint-plugin-vue
  - typescript-eslint
  - vue-eslint-parser
  - vue-tsc
  - '@eslint/*'
  - '@types/node'
  - typescript
  - '@typescript/native'
  - tailwindcss
  - '@microsoft/api-extractor'

注意：

• 当前 pnpm 仅从 .npmrc 读取认证和 registry 配置。publicHoistPattern、saveExact 等写入 pnpm-workspace.yaml。
• 修改提升规则后运行 pnpm install，使依赖布局与配置一致。
• 本仓库保留 pnpm-lock.yaml；CI 使用 pnpm install --frozen-lockfile 安装相同的依赖版本。

使用方法

1. ESLint 配置

在项目中创建 eslint.config.js 继承共享的 flat config：

import feStack from 'fe-stack/eslint.config';

export default feStack;

如需在其基础上追加规则，可展开数组后再补充配置对象：

import feStack from 'fe-stack/eslint.config';

export default [
  ...feStack,
  {
    rules: {
      // 项目自定义规则
    },
  },
];

应用模式会在项目根目录生成 eslint-auto-imports.json。将它接入项目的 flat config，使 Vue lint 规则能识别自动导入的 API：

import feStack from 'fe-stack/eslint.config';
import autoImports from './eslint-auto-imports.json' with { type: 'json' };

export default [
  ...feStack,
  {
    files: ['src/**/*.{js,mjs,jsx,ts,mts,tsx,vue}'],
    languageOptions: { globals: autoImports.globals },
  },
];

首次接入时运行一次 Vite 开发服务器或构建来生成该文件，并将它与 src/auto-imports.d.ts 等生成声明一同提交，保证新检出项目可直接检查。共享配置按 src、Worker 和配置文件区分浏览器、Worker 与 Node globals；其他目录布局或 SSR 项目可自行追加对应配置。

2. 代码格式化（含 Vue）

格式化由 Prettier 负责，ESLint 只做代码质量检查（lint），两者职责分离：Prettier 处理排版，fe-stack/eslint.config 末尾已通过 eslint-config-prettier 关闭与 Prettier 冲突的格式化类规则。

在项目 package.json 中引用共享配置，命令行和编辑器都会自动读取：

{
  "prettier": "fe-stack/prettier.json"
}

也可以创建 .prettierrc.json，其完整内容为 JSON 字符串：

"fe-stack/prettier.json"

在每个运行 Prettier 的项目目录创建 .prettierignore，排除构建产物和自动生成文件；ESLint 的 ignores 不会影响 Prettier：

**/build/**
**/dist/**
**/dist-ssr/**
**/public/**
**/coverage/**
**/auto-imports.d.ts
**/components.d.ts
**/route-map.d.ts
**/eslint-auto-imports.json

# 格式化（含 .vue）
prettier --write .

# 检查格式（用于 CI）
prettier --check .

# 代码检查
eslint .

JavaScript 文件保留 no-undef 检查；TypeScript 和 Vue 文件的标识符检查交由项目的类型检查工具负责。自动导入的 globals 由 Vite 插件生成为只读声明。

3. Tailwind 配置

Tailwind v4 采用 CSS-first 配置，无需 tailwind.config.js。在入口 CSS 中引入即可：

@import 'tailwindcss';

如需自定义主题，使用 @theme 指令：

@import 'tailwindcss';

@theme {
  --color-brand: #1e40af;
}

Vite 项目通过 fe-stack/vite.config.base 已内置 @tailwindcss/vite 插件，开箱即用。

4. TypeScript 配置

按 TypeScript 官方并行安装方案，使用最新稳定版 TypeScript 7.0.2 的原生 tsc，同时保留 TS 6 编译器 API：

• @typescript/native 是 typescript@7.0.2 的 npm 别名，提供 tsc，用于纯 TypeScript、Node 配置及共享配置检查。
• typescript 是官方 @typescript/typescript6@6.0.2 兼容包的 npm 别名，提供 TS 6 API 和 tsc6，供 vue-tsc、typescript-eslint 及声明生成插件使用。

TypeScript 7.0 尚未提供旧的 JavaScript 编译器 API，不能直接替换这些工具依赖的 typescript 模块。Vue SFC 的类型检查仍通过兼容包执行。

tsconfig.json（Vue 应用）：

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

tsconfig.app.json：

{
  "extends": "fe-stack/tsconfig.app.json",
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}

tsconfig.node.json：

{
  "extends": "fe-stack/tsconfig.node.json",
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo"
  },
  "include": ["vite.config.*"]
}

共享配置启用了 isolatedModules。paths 不需要 baseUrl；缓存路径由各项目指定，避免多个项目共用同一个缓存文件。

Vue 应用使用 vue-tsc -b tsconfig.app.json 检查 SFC，再使用 TS 7 的 tsc -b tsconfig.node.json 检查 Node 配置，然后执行 vite build。纯 TypeScript 库使用 tsc --noEmit，并单独检查 Vite 配置。Vite 负责转译，不执行类型检查。

5. Vite 配置

Vue 应用模式

import { createBaseConfig } from 'fe-stack/vite.config.base';

export default createBaseConfig(import.meta.dirname, {
  viteConfig: {
    server: {
      port: 5173,
      proxy: {
        '/api': {
          target: 'http://your-api-server',
          changeOrigin: true,
        },
      },
    },
  },
});

Lib 打包模式

import { createBaseConfig } from 'fe-stack/vite.config.base';

export default createBaseConfig(import.meta.dirname, {
  mode: 'lib',
  dtsConfig: {
    // 自定义 vite-plugin-dts 配置
    bundleTypes: true,
    exclude: ['**/*.test.ts', '**/*.spec.ts'],
    insertTypesEntry: true,
  },
  viteConfig: {
    build: {
      lib: {
        entry: './src/index.ts',
        name: 'MyLib',
        fileName: 'index',
      },
    },
  },
});

特性：

• ✅ 完整的 TypeScript 类型支持
• ✅ 使用 mergeConfig 优雅合并配置
• ✅ dtsConfig 直接配置 dts 插件选项
• ✅ lib 模式自动配置 vite-plugin-dts
• ✅ 默认打包为 ESM 格式

多入口库应保证每个 package.json 的 exports 都有对应的 JavaScript 和声明产物，示例见 playground-lib。

仓库验证

在仓库根目录运行：

pnpm install --frozen-lockfile
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build

pnpm build 检查共享配置，然后依次构建库和应用；每个示例项目也会在构建前执行自身的类型检查。只构建应用可运行 pnpm build:playground，只构建库可运行 pnpm build:lib。

配置依据：ESLint 10 迁移指南、Vue 类型检查、TypeScript 7 发布与兼容方案、声明插件迁移指南、pnpm 配置。