vite-plugin-dts 0.9.1 → 0.9.5

package/README.md

@@ -1,128 +1,174 @@
-# vite-plugin-dts
-
-**English** | [中文](./README.zh-CN.md)
-
-A vite plugin that generate `.d.ts` files from `.ts` or `.vue` source files for lib.
-
-## Install
-
-```sh
-yarn add vite-plugin-dts -D
-```
-
-## Usage
-
-```ts
-import { resolve } from 'path'
-import { defineConfig } from 'vite'
-import dts from 'vite-plugin-dts'
-
-export default defineConfig({
-  build: {
-    lib: {
-      entry: resolve(__dirname, 'src/index.ts'),
-      name: 'MyLib',
-      formats: ['es'],
-      fileName: 'my-lib'
-    }
-  },
-  plugins: [dts()]
-})
-```
-
-## Options
-
-```ts
-import type { ts, Diagnostic } from 'ts-morph'
-
-interface TransformWriteFile {
-  filePath?: string
-  content?: string
-}
-
-export interface PluginOptions {
-  // Depends on the root directory
-  // Defaults base on your vite config root options
-  root?: string
-
-  // Declaration files output directory
-  // Defaults base on your vite config output options
-  outputDir?: string
-
-  // Project init compilerOptions using by ts-morph
-  // Default: null
-  compilerOptions?: ts.CompilerOptions | null
-
-  // Project init tsconfig.json file path by ts-morph
-  // Plugin also resolve incldue and exclude files from tsconfig.json
-  // Default: 'tsconfig.json'
-  tsConfigFilePath?: string
-
-  // Whether transform file name '.vue.d.ts' to '.d.ts'
-  // Default: false
-  cleanVueFileName?: boolean
-
-  // Whether transform dynamic import to static
-  // eg. 'import('vue').DefineComponent' to 'import { DefineComponent } from "vue"'
-  // Default: false
-  staticImport?: boolean
-
-  // Manual set include glob
-  // Defaults base on your tsconfig.json include option
-  include?: string | string[]
-
-  // Manual set exclude glob
-  // Defaults base on your tsconfig.json exclude option, be 'node_module/**' when empty
-  exclude?: string | string[]
-
-  // Whether generate types entry file
-  // When true will from package.json types field if exists or `${outputDir}/index.d.ts`
-  // Default: false
-  insertTypesEntry?: boolean
-
-  // Whether copy .d.ts source files into outputDir
-  // Default: true
-  copyDtsFiles?: boolean
-
-  // Whether emit nothing when has any diagnostic
-  // Default: false
-  noEmitOnError?: boolean
-
-  // Whether skip typescript diagnostics
-  // Default: true
-  skipDiagnostics?: boolean
-
-  // Whether log diagnostic informations
-  // Default: false
-  logDiagnostics?: boolean
-
-  // After emit diagnostic hook
-  // According to the length to judge whether there is any type error
-  // Default: () => {}
-  afterDiagnostic?: (diagnostics: Diagnostic[]) => void | Promise<void>
-
-  // Before declaration file be writed hook
-  // You can transform declaration file-path and content through it
-  // Default: () => {}
-  beforeWriteFile?: (filePath: string, content: string) => void | TransformWriteFile
-
-  // After build hook
-  // It wil be called after all declaration files are written
-  // Default: () => {}
-  afterBuild?: () => void | Promise<void>
-}
-```
-
-## Example
-
-Clone and run the following script:
-
-```sh
-yarn run test:e2e
-```
-
-Then check `example/types`.
-
-## License
-
-MIT License.
+# vite-plugin-dts
+
+**English** | [中文](./README.zh-CN.md)
+
+A vite plugin that generate `.d.ts` files from `.ts` or `.vue` source files for lib.
+
+## Install
+
+```sh
+yarn add vite-plugin-dts -D
+```
+
+## Usage
+
+In `vite.config.ts`:
+
+```ts
+import { resolve } from 'path'
+import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'MyLib',
+      formats: ['es'],
+      fileName: 'my-lib'
+    }
+  },
+  plugins: [dts()]
+})
+```
+
+In your component:
+
+```vue
+<template>
+  <div></div>
+</template>
+
+<script lang="ts">
+// using defineComponent for inferring types
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  name: 'Component'
+})
+</script>
+```
+
+```vue
+<script setup lang="ts">
+// Need to access the defineProps returned value to
+// infer types although you never use the props directly
+const props = defineProps<{
+  color: 'blue' | 'red'
+}>()
+</script>
+
+<template>
+  <div>{{ color }}</div>
+</template>
+```
+
+## Options
+
+```ts
+import type { ts, Diagnostic } from 'ts-morph'
+
+interface TransformWriteFile {
+  filePath?: string
+  content?: string
+}
+
+export interface PluginOptions {
+  // Depends on the root directory
+  // Defaults base on your vite config root options
+  root?: string
+
+  // Declaration files output directory
+  // Defaults base on your vite config output options
+  outputDir?: string
+
+  // Project init compilerOptions using by ts-morph
+  // Default: null
+  compilerOptions?: ts.CompilerOptions | null
+
+  // Project init tsconfig.json file path by ts-morph
+  // Plugin also resolve incldue and exclude files from tsconfig.json
+  // Default: 'tsconfig.json'
+  tsConfigFilePath?: string
+
+  // Whether transform file name '.vue.d.ts' to '.d.ts'
+  // Default: false
+  cleanVueFileName?: boolean
+
+  // Whether transform dynamic import to static
+  // eg. 'import('vue').DefineComponent' to 'import { DefineComponent } from "vue"'
+  // Default: false
+  staticImport?: boolean
+
+  // Manual set include glob
+  // Defaults base on your tsconfig.json include option
+  include?: string | string[]
+
+  // Manual set exclude glob
+  // Defaults base on your tsconfig.json exclude option, be 'node_module/**' when empty
+  exclude?: string | string[]
+
+  // Whether generate types entry file
+  // When true will from package.json types field if exists or `${outputDir}/index.d.ts`
+  // Default: false
+  insertTypesEntry?: boolean
+
+  // Whether copy .d.ts source files into outputDir
+  // Default: true
+  copyDtsFiles?: boolean
+
+  // Whether emit nothing when has any diagnostic
+  // Default: false
+  noEmitOnError?: boolean
+
+  // Whether skip typescript diagnostics
+  // Skip type diagnostics means that type errors will not interrupt the build process
+  // But for the source files with type errors will not be emitted
+  // Default: true
+  skipDiagnostics?: boolean
+
+  // Whether log diagnostic informations
+  // Not effective when `skipDiagnostics` is true
+  // Default: false
+  logDiagnostics?: boolean
+
+  // After emit diagnostic hook
+  // According to the length to judge whether there is any type error
+  // Default: () => {}
+  afterDiagnostic?: (diagnostics: Diagnostic[]) => void | Promise<void>
+
+  // Before declaration file be writed hook
+  // You can transform declaration file-path and content through it
+  // Default: () => {}
+  beforeWriteFile?: (filePath: string, content: string) => void | TransformWriteFile
+
+  // After build hook
+  // It wil be called after all declaration files are written
+  // Default: () => {}
+  afterBuild?: () => void | Promise<void>
+}
+```
+
+## Example
+
+Clone and run the following script:
+
+```sh
+yarn run test:e2e
+```
+
+Then check `example/types`.
+
+## FAQ
+
+Here will include some FAQ's and provide some solutions.
+
+### Missing some declaration files after build
+
+By default `skipDiagnostics` option is `true`, which means that type diagnostic will be skipped during the build process (some projects may have diagnostic tool such as `vue-tsc`). If there are some files with type errors which will interrupt the build process, these files will not be emitted (not generate declaration files).
+
+If your project has not type diagnostic tools, you can set `skipDiagnostics: false` and `logDiagnostics: true` to turn on the diagnostic and log features of this plugin. It will help you to check the type errors during build and log error information to the terminal.
+
+## License
+
+MIT License.

package/README.zh-CN.md

@@ -1,128 +1,173 @@
-# vite-plugin-dts
-
-**中文** | [English](./README.md)
-
-一款用于从 `.ts` 或 `.vue` 源文件生成 `.d.ts` 文件的 Vite 插件。
-
-## 安装
-
-```sh
-yarn add vite-plugin-dts -D
-```
-
-## 使用
-
-```ts
-import { resolve } from 'path'
-import { defineConfig } from 'vite'
-import dts from 'vite-plugin-dts'
-
-export default defineConfig({
-  build: {
-    lib: {
-      entry: resolve(__dirname, 'src/index.ts'),
-      name: 'MyLib',
-      formats: ['es'],
-      fileName: 'my-lib'
-    }
-  },
-  plugins: [dts()]
-})
-```
-
-## 选项
-
-```ts
-import type { ts, Diagnostic } from 'ts-morph'
-
-interface TransformWriteFile {
-  filePath?: string
-  content?: string
-}
-
-export interface PluginOptions {
-  // 执行的根目录
-  // 默认基于 vite 配置的 root 选项
-  root?: string
-
-  // 声明文件的输出目录
-  // 默认基于 vite 配置的输出目录
-  outputDir?: string
-
-  // 提供给 ts-morph Project 初始化的 compilerOptions 选项
-  // 默认值: null
-  compilerOptions?: ts.CompilerOptions | null
-
-  // 提供给 ts-morph Project 初始化的 tsconfig.json 路径
-  // 插件也会读取 tsconfig.json 的 incldue 和 exclude 选项来解析文件
-  // 默认值: 'tsconfig.json'
-  tsConfigFilePath?: string
-
-  // 是否将 '.vue.d.ts' 文件名转换为 '.d.ts'
-  // 默认值: false
-  cleanVueFileName?: boolean
-
-  //是否将动态引入转换为静态
-  // eg. 'import('vue').DefineComponent' 转换为 'import { DefineComponent } from "vue"'
-  // 默认值: false
-  staticImport?: boolean
-
-  // 手动设置包含路径的 glob
-  // 默认基于 tsconfig.json 的 include 选项
-  include?: string | string[]
-
-  // 手动设置排除路径的 glob
-  // 默认基于 tsconfig.json 的 exclude 选线，未设置时为 'node_module/**'
-  exclude?: string | string[]
-
-  // 是否生成类型声明入口
-  // 当为 true 时会基于 package.json 的 tpyes 字段生成，或者 `${outputDir}/index.d.ts`
-  // 默认值: false
-  insertTypesEntry?: boolean
-
-  // 是否将源码里的 .d.ts 文件复制到 outputDir
-  // 默认值: true
-  copyDtsFiles?: boolean
-
-  // 出现类型诊断信息时不生成类型文件
-  // 默认值: false
-  noEmitOnError?: boolean
-
-  // 是否跳过类型诊断
-  // 默认值: true
-  skipDiagnostics?: boolean
-
-  // 是否打印类型诊断信息
-  // 默认值: false
-  logDiagnostics?: boolean
-
-  // 获取诊断信息后的钩子
-  // 可以根据参数 length 来判断有误类型错误
-  // 默认值: () => {}
-  afterDiagnostic?: (diagnostics: Diagnostic[]) => void | Promise<void>
-
-  // 类型声明文件被写入前的钩子
-  // 可以在钩子里转换文件路径和文件内容
-  // 默认值: () => {}
-  beforeWriteFile?: (filePath: string, content: string) => void | TransformWriteFile
-
-  // 构建后回调钩子
-  // 将会在所有类型文件被写入后调用
-  // 默认值: () => {}
-  afterBuild?: () => void | Promise<void>
-}
-```
-
-## Example
-
-克隆项目然后执行下列命令：
-
-```sh
-yarn run test:e2e
-```
-
-然后检查 `example/types` 目录。
-
-## 授权
-
-MIT License
+# vite-plugin-dts
+
+**中文** | [English](./README.md)
+
+一款用于从 `.ts` 或 `.vue` 源文件生成 `.d.ts` 文件的 Vite 插件。
+
+## 安装
+
+```sh
+yarn add vite-plugin-dts -D
+```
+
+## 使用
+
+在 `vite.config.ts`:
+
+```ts
+import { resolve } from 'path'
+import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+
+export default defineConfig({
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'MyLib',
+      formats: ['es'],
+      fileName: 'my-lib'
+    }
+  },
+  plugins: [dts()]
+})
+```
+
+在你的组件中:
+
+```vue
+<template>
+  <div></div>
+</template>
+
+<script lang="ts">
+// 使用 defineComponent 来进行类型推断
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  name: 'Component'
+})
+</script>
+```
+
+```vue
+<script setup lang="ts">
+// 尽管没有直接使用 props，你仍需要接收 defineProps 的返回值
+const props = defineProps<{
+  color: 'blue' | 'red'
+}>()
+</script>
+
+<template>
+  <div>{{ color }}</div>
+</template>
+```
+
+## 选项
+
+```ts
+import type { ts, Diagnostic } from 'ts-morph'
+
+interface TransformWriteFile {
+  filePath?: string
+  content?: string
+}
+
+export interface PluginOptions {
+  // 执行的根目录
+  // 默认基于 vite 配置的 root 选项
+  root?: string
+
+  // 声明文件的输出目录
+  // 默认基于 vite 配置的输出目录
+  outputDir?: string
+
+  // 提供给 ts-morph Project 初始化的 compilerOptions 选项
+  // 默认值: null
+  compilerOptions?: ts.CompilerOptions | null
+
+  // 提供给 ts-morph Project 初始化的 tsconfig.json 路径
+  // 插件也会读取 tsconfig.json 的 incldue 和 exclude 选项来解析文件
+  // 默认值: 'tsconfig.json'
+  tsConfigFilePath?: string
+
+  // 是否将 '.vue.d.ts' 文件名转换为 '.d.ts'
+  // 默认值: false
+  cleanVueFileName?: boolean
+
+  //是否将动态引入转换为静态
+  // eg. 'import('vue').DefineComponent' 转换为 'import { DefineComponent } from "vue"'
+  // 默认值: false
+  staticImport?: boolean
+
+  // 手动设置包含路径的 glob
+  // 默认基于 tsconfig.json 的 include 选项
+  include?: string | string[]
+
+  // 手动设置排除路径的 glob
+  // 默认基于 tsconfig.json 的 exclude 选线，未设置时为 'node_module/**'
+  exclude?: string | string[]
+
+  // 是否生成类型声明入口
+  // 当为 true 时会基于 package.json 的 tpyes 字段生成，或者 `${outputDir}/index.d.ts`
+  // 默认值: false
+  insertTypesEntry?: boolean
+
+  // 是否将源码里的 .d.ts 文件复制到 outputDir
+  // 默认值: true
+  copyDtsFiles?: boolean
+
+  // 出现类型诊断信息时不生成类型文件
+  // 默认值: false
+  noEmitOnError?: boolean
+
+  // 是否跳过类型诊断
+  // 跳过类型诊断意味着出现错误时不会中断打包进程的执行
+  // 但对于出现错误的源文件，将无法生成相应的类型文件
+  // 默认值: true
+  skipDiagnostics?: boolean
+
+  // 是否打印类型诊断信息
+  // 当跳过类型诊断时该属性将不会生效
+  // 默认值: false
+  logDiagnostics?: boolean
+
+  // 获取诊断信息后的钩子
+  // 可以根据参数 length 来判断有误类型错误
+  // 默认值: () => {}
+  afterDiagnostic?: (diagnostics: Diagnostic[]) => void | Promise<void>
+
+  // 类型声明文件被写入前的钩子
+  // 可以在钩子里转换文件路径和文件内容
+  // 默认值: () => {}
+  beforeWriteFile?: (filePath: string, content: string) => void | TransformWriteFile
+
+  // 构建后回调钩子
+  // 将会在所有类型文件被写入后调用
+  // 默认值: () => {}
+  afterBuild?: () => void | Promise<void>
+}
+```
+
+## 示例
+
+克隆项目然后执行下列命令：
+
+```sh
+yarn run test:e2e
+```
+
+然后检查 `example/types` 目录。
+
+## 常见问题
+
+此处将收录一些常见的问题并提供一些解决方案。
+
+### 打包后出现类型文件缺失
+
+默认情况下 `skipDiagnostics` 选项的值为 `true`，这意味着打包过程中将跳过类型检查（一些项目通常有 `vue-tsc` 等的类型检查工具），这时如果出现存在类型错误的文件，并且这是错误会中断打包过程，那么这些文件对应的类型文件将不会被生成。
+
+如果您的项目没有依赖外部的类型检查工具，这时候可以您可以设置 `skipDiagnostics: false` 和 `logDiagnostics: true` 来打开插件的诊断与输出功能，这将帮助您检查打包过程中出现的类型错误并将错误信息输出至终端。
+
+## 授权
+
+MIT 授权。

package/dist/index.d.ts

@@ -26,4 +26,4 @@ interface PluginOptions {
 }
 declare function dtsPlugin(options?: PluginOptions): Plugin;
 
-export { PluginOptions, dtsPlugin as default };
+export { dtsPlugin as default };