Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/qmhc/vite-plugin-dts
A Vite plugin for generating `.d.ts` files.
https://github.com/qmhc/vite-plugin-dts
dts react tsc typescript vite vite-plugin volar vue vue-tsc
Last synced: 5 days ago
JSON representation
A Vite plugin for generating `.d.ts` files.
- Host: GitHub
- URL: https://github.com/qmhc/vite-plugin-dts
- Owner: qmhc
- License: mit
- Created: 2021-06-01T11:30:09.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-10T01:44:56.000Z (16 days ago)
- Last Synced: 2025-01-18T20:52:30.752Z (7 days ago)
- Topics: dts, react, tsc, typescript, vite, vite-plugin, volar, vue, vue-tsc
- Language: TypeScript
- Homepage:
- Size: 3.44 MB
- Stars: 1,343
- Watchers: 8
- Forks: 92
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-vite - vite-plugin-dts - Generate declaration files from `.ts` or `.vue` source files for lib. (Plugins / Framework-agnostic Plugins)
- awesome - vite-plugin-dts
- awesome-vite - vite-plugin-dts - Generate declaration files from `.ts` or `.vue` source files for lib. (Plugins / Framework-agnostic Plugins)
README
vite-plugin-dts
A Vite plugin that generates declaration files (*.d.ts) from .ts(x) or .vue source files when using Vite in library mode.
**English** | [中文](./README.zh-CN.md)
## Install
```sh
pnpm i 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()]
})
```
By default, the generated declaration files are following the source structure.
If you want to merge all declarations into one file, just specify `rollupTypes: true`:
```ts
{
plugins: [dts({ rollupTypes: true })]
}
```
If you start with official Vite template, you should specify the `tsconfigPath`:
```ts
{
plugins: [dts({ tsconfigPath: './tsconfig.app.json' })]
}
```
Starting with `3.0.0`, you can use this plugin with Rollup.
## FAQ
Here are some FAQ's and solutions.
### Type errors that are unable to infer types from packages in `node_modules`
This is an existing [TypeScript issue](https://github.com/microsoft/TypeScript/issues/42873) where TypeScript infers types from packages located in `node_modules` through soft links (pnpm). A workaround is to add `baseUrl` to your `tsconfig.json` and specify the `paths` for these packages:
```json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"third-lib": ["node_modules/third-lib"]
}
}
}
```
### `Internal Error` occurs when using `rollupTypes: true`
Refer to this [issue](https://github.com/microsoft/rushstack/issues/3875), it's due to a limitation of `@microsoft/api-extractor` or TypeScript resolver.
The main reason is that `baseUrl` is specified in `tsconfig.json` and non-standard paths are used directly when imported.
For example: `baseUrl: 'src'` is specified and importing from `/src/components/index.ts` in `/src/index.ts`, and `import 'components'` is used instead of `import './components'`.
Currently, you need to avoid the above situation, or use aliases instead (with the `paths` option).
### Get module not found errors during build
This is likely due to incorrect configuration of the `include` property in your default `tsconfig.json`.
Due to some limitations, the plugin relies on the top-level `tsconfig.json` to resolve the files to include. Therefore, you need to specify the correct `include` property in the top-level `tsconfig.json`, or you can specify a configuration file path with the correct `include` property using the `tsconfigPath` option of the plugin. For example, in the Vite initial template, it is `tsconfig.app.json`.
You can refer to this [comment](https://github.com/qmhc/vite-plugin-dts/issues/343#issuecomment-2198111439).
Legacy
### Missing some declaration files after build (before `1.7.0`)
By default, the `skipDiagnostics` option is set to `true` which means type diagnostics will be skipped during the build process (some projects may have diagnostic tools such as `vue-tsc`). Files with type errors which interrupt the build process will not be emitted (declaration files won't be generated).
If your project doesn't use type diagnostic tools, you can set `skipDiagnostics: false` and `logDiagnostics: true` to turn on diagnostic and logging features of this plugin. Type errors during build will be logged to the terminal.
### Type error when using both `script` and `setup-script` in Vue component (before `3.0.0`)
This is usually caused by using the `defineComponent` function in both `script` and `setup-script`. When `vue/compiler-sfc` compiles these files, the default export result from `script` gets merged with the parameter object of `defineComponent` from `setup-script`. This is incompatible with parameters and types returned from `defineComponent`. This results in a type error.
Here is a simple [example](https://github.com/qmhc/vite-plugin-dts/blob/main/examples/vue/components/BothScripts.vue). You should remove the `defineComponent` in `script` and export a native object directly.
## Options
```ts
import type ts from 'typescript'
import type { IExtractorConfigPrepareOptions, IExtractorInvokeOptions } from '@microsoft/api-extractor'
import type { LogLevel } from 'vite'
type MaybePromise = T | Promise
export type RollupConfig = Omit<
IExtractorConfigPrepareOptions['configObject'],
| 'projectFolder'
| 'mainEntryPointFilePath'
| 'compiler'
| 'dtsRollup'
>
export interface Resolver {
/**
* The name of the resolver
*
* The later resolver with the same name will overwrite the earlier
*/
name: string,
/**
* Determine whether the resolver supports the file
*/
supports: (id: string) => void | boolean,
/**
* Transform source to declaration files
*
* Note that the path of the returns should base on `outDir`, or relative path to `root`
*/
transform: (payload: {
id: string,
code: string,
root: string,
outDir: string,
host: ts.CompilerHost,
program: ts.Program
}) => MaybePromise<{ path: string, content: string }[]>
}
export interface PluginOptions {
/**
* Specify root directory.
*
* Defaults to the 'root' of the Vite config, or `process.cwd()` if using Rollup.
*/
root?: string,
/**
* Output directory for declaration files.
*
* Can be an array to output to multiple directories.
*
* Defaults to 'build.outDir' of the Vite config, or `outDir` of tsconfig.json if using Rollup.
*/
outDir?: string | string[],
/**
* Override root path of entry files (useful in monorepos).
*
* The output path of each file will be calculated based on the value provided.
*
* The default is the smallest public path for all source files.
*/
entryRoot?: string,
/**
* Restrict declaration files output to `outDir`.
*
* If true, generated declaration files outside `outDir` will be ignored.
*
* @default true
*/
strictOutput?: boolean,
/**
* Override compilerOptions.
*
* @default null
*/
compilerOptions?: ts.CompilerOptions | null,
/**
* Specify tsconfig.json path.
*
* Plugin resolves `include` and `exclude` globs from tsconfig.json.
*
* If not specified, plugin will find config file from root.
*/
tsconfigPath?: string,
/**
* Specify custom resolvers.
*
* @default []
*/
resolvers?: Resolver[],
/**
* Parsing `paths` of tsconfig.json to aliases.
*
* Note that these aliases only use for declaration files.
*
* @default true
* @remarks Only use first replacement of each path.
*/
pathsToAliases?: boolean,
/**
* Set which paths should be excluded when transforming aliases.
*
* @default []
*/
aliasesExclude?: (string | RegExp)[],
/**
* Whether to transform file names ending in '.vue.d.ts' to '.d.ts'.
*
* If there is a duplicate name after transform, it will fall back to the original name.
*
* @default false
*/
cleanVueFileName?: boolean,
/**
* Whether to transform dynamic imports to static (eg `import('vue').DefineComponent` to `import { DefineComponent } from 'vue'`).
*
* Value is forced to `true` when `rollupTypes` is `true`.
*
* @default false
*/
staticImport?: boolean,
/**
* Override `include` glob (relative to root).
*
* Defaults to `include` property of tsconfig.json (relative to tsconfig.json located).
*/
include?: string | string[],
/**
* Override `exclude` glob.
*
* Defaults to `exclude` property of tsconfig.json or `'node_modules/**'` if not supplied.
*/
exclude?: string | string[],
/**
* Whether to remove `import 'xxx'`.
*
* @default true
*/
clearPureImport?: boolean,
/**
* Whether to generate types entry file(s).
*
* When `true`, uses package.json `types` property if it exists or `${outDir}/index.d.ts`.
*
* Value is forced to `true` when `rollupTypes` is `true`.
*
* @default false
*/
insertTypesEntry?: boolean,
/**
* Rollup type declaration files after emitting them.
*
* Powered by `@microsoft/api-extractor` - time-intensive operation.
*
* @default false
*/
rollupTypes?: boolean,
/**
* Bundled packages for `@microsoft/api-extractor`.
*
* @default []
* @see https://api-extractor.com/pages/configs/api-extractor_json/#bundledpackages
*/
bundledPackages?: string[],
/**
* Override the config of `@microsoft/api-extractor`.
*
* @default null
* @see https://api-extractor.com/pages/setup/configure_api_report/
*/
rollupConfig?: RollupConfig,
/**
* Override the invoke options of `@microsoft/api-extractor`.
*
* @default null
* @see https://api-extractor.com/pages/setup/invoking/#invoking-from-a-build-script
*/
rollupOptions?: IExtractorInvokeOptions,
/**
* Whether to copy .d.ts source files to `outDir`.
*
* @default false
* @remarks Before 2.0, the default was `true`.
*/
copyDtsFiles?: boolean,
/**
* Whether to emit declaration files only.
*
* When `true`, all the original outputs of vite (rollup) will be force removed.
*
* @default false
*/
declarationOnly?: boolean,
/**
* Logging level for this plugin.
*
* Defaults to the 'logLevel' property of your Vite config.
*/
logLevel?: LogLevel,
/**
* Hook called after diagnostic is emitted.
*
* According to the `diagnostics.length`, you can judge whether there is any type error.
*
* @default () => {}
*/
afterDiagnostic?: (diagnostics: readonly ts.Diagnostic[]) => MaybePromise,
/**
* Hook called prior to writing each declaration file.
*
* This allows you to transform the path or content.
*
* The file will be skipped when the return value `false` or `Promise`.
*
* @default () => {}
*/
beforeWriteFile?: (
filePath: string,
content: string
) => MaybePromise<
| void
| false
| {
filePath?: string,
content?: string
}
>,
/**
* Hook called after rolling up declaration files.
*
* @default () => {}
*/
afterRollup?: (result: ExtractorResult) => MaybePromise,
/**
* Hook called after all declaration files are written.
*
* It will be received a map (path -> content) that records those emitted files.
*
* @default () => {}
*/
afterBuild?: (emittedFiles: Map) => MaybePromise
}
```
## Contributors
Thanks for all the contributions!
## Example
Clone and run the following script:
```sh
pnpm run test:ts
```
Then check `examples/ts/types`.
Also Vue and React cases under `examples`.
A real project using this plugin: [Vexip UI](https://github.com/vexip-ui/vexip-ui).
## License
MIT License.