Vite plugin type is Plugin | Plugin[], but always returns a single plugin instance

[sullyD64]

Describe the bug

I noticed that the type definition for the Vite plugin export is currently:

import unplugin from '.'

export default unplugin.vite

Which results in the following built .d.ts:

(options: Options) => vite.Plugin<any> | vite.Plugin<any>[]

But from looking at the code and using the plugin, it always returns a single plugin object for Vite—never an array. This can be confusing for TypeScript users, since there isn’t any case (at least documented or in the code) where you’d get an array.

As a reference, in unplugin-vue-components, the Vite plugin is typed more strictly as just a single plugin:

import type { Plugin } from 'vite'
import type { Options, PublicPluginAPI } from './types'
import unplugin from '.'

export default unplugin.vite as (options?: Options | undefined) => Plugin & { api: PublicPluginAPI }

If there’s any advanced use case where an array could actually be returned, it would be great to document that! Otherwise, maybe the type could be updated to match the real behavior.

Thanks for your work on this project!

Reproduction

https://stackblitz.com/edit/vitejs-vite-c4tcpscb?file=vite.config.ts&view=editor

System Info

System:
    OS: Linux 5.0 undefined
    CPU: (8) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
    Memory: 0 Bytes / 0 Bytes
    Shell: 1.0 - /bin/jsh
  Binaries:
    Node: 20.19.1 - /usr/local/bin/node
    Yarn: 1.22.19 - /usr/local/bin/yarn
    npm: 10.8.2 - /usr/local/bin/npm
    pnpm: 8.15.6 - /usr/local/bin/pnpm

Used Package Manager

npm

Validations

• Follow our Code of Conduct
• Read the Contributing Guide.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A, please open a GitHub Discussion instead.
• The provided reproduction is a minimal reproducible of the bug.

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• vitejs-vite-c4tcpscb (Open reproduction)

[ilyaliao]

I think it’s because Vite accepts one or more plugins, according to the docs.
That’s exactly the default export type for unplugin.vite in unplugin.