vite-plugin-property-paths-to-types

English | 中文

一个 Vite 插件，用于从 JSON 配置文件自动生成 TypeScript 类型定义。

特性

• 🚀 自动生成类型：从 JSON 配置文件自动生成完整的 TypeScript 类型定义
• 📁 多文件支持：支持同时处理多个配置文件
• 🔄 热重载：开发模式下监听配置文件变化，自动重新生成类型
• 📝 JSDoc 支持：自动生成详细的 JSDoc 注释
• ⚙️ 高度可配置：支持自定义类型名称、属性信息等
• 🛡️ 类型安全：提供完整的类型检查和验证

安装

npm install vite-plugin-property-paths-to-types -D
# 或
yarn add vite-plugin-property-paths-to-types -D
# 或
pnpm add vite-plugin-property-paths-to-types -D

快速开始

1. 配置 Vite 插件

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import propertyPathsToTypes from 'vite-plugin-property-paths-to-types';

export default defineConfig({
  plugins: [
    vue(),
    propertyPathsToTypes({
      configFiles: [
        './src/types/app.json',
        './src/types/api.json'
      ],
      outputDir: './src/types/generated',
      watch: true
    })
  ]
});

2. 创建配置文件

src/types/app.json

{
  "app": {
    "name": "string",
    "version": "string",
    "components?[]": {
      "id": "string",
      "label?": "string"
    }
  },
  "database": {
    "host": "string",
    "port": "number",
    "credentials": {
      "username": "string",
      "password": "string"
    }
  }
}

src/types/api.json

{
  "endpoints": {
    "users": "string",
    "posts": "string"
  },
  "headers": {
    "authorization": "string",
    "contentType": "string"
  }
}

3. 使用生成的类型

// 在您的代码中使用自动生成的类型
import type { AppConfig } from './types/generated/app';
import type { ApiConfig } from './types/generated/api';

const appConfig: AppConfig = {
  app: {
    name: "My App",
    version: "1.0.0",
    components: [
      {
        "id": "x-1",
        "label" "CZ-1"
      },
      {
        "id": "x-2",
        "label": "CZ-2"
      }
    ]

  },
  database: {
    host: "localhost",
    port: 5432,
    credentials: {
      username: "admin",
      password: "secret"
    }
  }
};

const apiConfig: ApiConfig = {
  endpoints: {
    users: "/api/users",
    posts: "/api/posts"
  },
  headers: {
    authorization: "Bearer token",
    contentType: "application/json"
  }
};

配置选项

interface PropertyPathsPluginOptions {
  /**
   * 配置文件路径数组
   * @example ['./src/types/app.json', './src/types/database.json']
   */
  configFiles: string[];
  
  /**
   * 输出目录
   * @default './src/types/generated'
   */
  outputDir?: string;
  
  /**
   * 开发模式下是否监听变化
   * @default true
   */
  watch?: boolean;
  
  /**
   * 属性信息映射，用于自定义类型和描述
   */
  propertyInfo?: Record<string, PropertyInfo>;
  
  /**
   * 是否生成 JSDoc 注释
   * @default true
   */
  generateComments?: boolean;
  
  /**
   * 自定义类型前缀
   */
  typePrefix?: string;
  
  /**
   * 自定义类型后缀
   */
  typeSuffix?: string;
  
  /**
   * 默认属性类型
   * @default 'string'
   */
  defaultPropertyType?: string;
  
  /**
   * 根类型名称映射，key为文件名，value为类型名
   */
  rootTypeNames?: Record<string, string>;
}

interface PropertyInfo {
  type: string;
  description?: string;
  defaultValue?: any;
  required?: boolean;
}

高级用法

自定义属性信息

propertyPathsToTypes({
  configFiles: ['./src/types/app.json'],
  propertyInfo: {
    'app.name': {
      type: 'string',
      description: '应用名称',
      defaultValue: 'My App'
    },
    'database.port': {
      type: 'number',
      description: '数据库端口',
      defaultValue: 5432
    },
    'features.auth.enabled': {
      type: 'boolean',
      description: '是否启用认证',
      defaultValue: true
    }
  }
})

自定义类型命名

propertyPathsToTypes({
  configFiles: ['./src/types/app.json'],
  rootTypeNames: {
    './src/types/app.json': 'ApplicationConfig'
  },
  typePrefix: 'Custom',
  typeSuffix: 'Type'
})

禁用 JSDoc 注释

propertyPathsToTypes({
  configFiles: ['./src/types/app.json'],
  generateComments: false
})

生成的文件结构

src/
├── types/
│   ├── app.json          # 配置文件
│   ├── api.json          # 配置文件
│   └── generated/        # 自动生成的类型文件
│       ├── app.ts
│       └── api.ts

示例输出

生成的 app.ts

// 自动生成的类型定义 - 请勿手动修改
// Generated by vite-plugin-property-paths-to-types
// https://github.com/cao5zy/vite-plugin-property-paths-to-types

/** app 对象类型 */
export interface App {
  /** 应用名称 */
  name: string;
  version: string;
  components?: Component[]
}

/** component 对象类型 */
export interface Component {
  id string;
  label?: string;
}

/** database.credentials 对象类型 */
export interface DatabaseCredentials {
  username: string;
  password: string;
}

/** database 对象类型 */
export interface Database {
  host: string;
  /** 数据库端口 */
  port: number;
  credentials: DatabaseCredentials;
}

/** 根对象类型 */
export interface AppConfig {
  app: App;
  database: Database;
}

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.0.0

• 初始版本发布
• 支持多配置文件
• 自动生成嵌套类型
• JSDoc 注释支持