feat(css): export PostCSS config type for type-safe configs

Re-exports the PostCSS user config shape as `PostcssUserConfig` from
`vite`, so PostCSS configs can be typed against the same definition Vite
loads them with:

```ts
import type { PostcssUserConfig } from 'vite'

const config: PostcssUserConfig = { plugins: [] }
export default config
```

The type mirrors `postcss-load-config`'s `Config`. `postcss-load-config`
is bundled into Vite and its declarations use CommonJS `export =` syntax,
which `rolldown-plugin-dts` cannot re-export through the bundled `.d.ts`,
so the shape is mirrored from `postcss` types instead. A type-level test
asserts the mirror stays structurally identical to the upstream `Config`,
so it cannot silently drift.

Closes #19109

Author: linyiru

packages/vite/src/node/__tests_dts__/postcss.ts

@@ -0,0 +1,26 @@
+// Tests the `PostcssUserConfig` type re-exported from `vite`. It mirrors the
+// `Config` type of `postcss-load-config` (which is bundled into Vite and cannot
+// be re-exported through the bundled `.d.ts`, see #19109). The `Equal` case
+// below locks the two together so the mirror can never silently drift.
+import type { Equal, ExpectTrue } from '@type-challenges/utils'
+import type { Config as PostcssLoadConfig } from 'postcss-load-config'
+import type { PostcssUserConfig } from '../index'
+
+export type cases = [ExpectTrue<Equal<PostcssUserConfig, PostcssLoadConfig>>]
+
+// The array plugin format is accepted.
+;({ plugins: [] }) satisfies PostcssUserConfig
+
+// The object plugin format is accepted, alongside the other options.
+;({
+  map: false,
+  from: 'src/index.css',
+  plugins: { 'postcss-preset-env': {} },
+}) satisfies PostcssUserConfig
+
+;({
+  // @ts-expect-error --- `map` must be `string | false`, not a number
+  map: 123,
+}) satisfies PostcssUserConfig
+
+export {}

packages/vite/src/node/index.ts

@@ -200,6 +200,7 @@ export type {
   CSSModulesOptions,
   PreprocessCSSResult,
   ResolvedCSSOptions,
+  PostcssUserConfig,
   SassPreprocessorOptions,
   LessPreprocessorOptions,
   StylusPreprocessorOptions,

packages/vite/src/node/plugins/css.ts

@@ -111,6 +111,35 @@ import { IIFE_BEGIN_RE, UMD_BEGIN_RE } from './oxc'
 const decoder = new TextDecoder()
 // const debug = createDebugger('vite:css')
 
+/**
+ * The shape of a PostCSS config file (e.g. `postcss.config.js`), matching the
+ * `Config` type of the `postcss-load-config` version that Vite uses to load it.
+ * Use it to write a type-safe PostCSS config:
+ *
+ * ```ts
+ * import type { PostcssUserConfig } from 'vite'
+ *
+ * const config: PostcssUserConfig = { plugins: [] }
+ * export default config
+ * ```
+ *
+ * `postcss-load-config` is bundled into Vite and its types are declared with
+ * CommonJS `export =` syntax, so they cannot be re-exported through the bundled
+ * `.d.ts`. This mirrors its `Config` type instead, and a type-level test in
+ * `__tests_dts__/postcss.ts` asserts the two stay structurally identical.
+ */
+export type PostcssUserConfig = {
+  parser?: string | PostCSS.ProcessOptions['parser'] | false
+  stringifier?: string | PostCSS.ProcessOptions['stringifier'] | false
+  syntax?: string | PostCSS.ProcessOptions['syntax'] | false
+  map?: string | false
+  from?: string
+  to?: string
+  plugins?:
+    | Array<PostCSS.Transformer | PostCSS.Plugin | PostCSS.Processor | false>
+    | Record<string, object | false>
+}
+
 export interface CSSOptions {
   /**
    * Using lightningcss is an experimental option to handle CSS modules,