Add TypeScript types to the viteFastfiy plugin and utils exports (#352)

Author: onlywei

.changeset/dirty-feet-wash.md

@@ -0,0 +1,5 @@
+---
+"@fastify/vite": minor
+---
+
+Add TypeScript types to the `viteFastify` plugin and utils exports. #352

packages/fastify-vite/package.json

@@ -25,7 +25,9 @@
     "utils.js",
     "mode/development.js",
     "mode/production.js",
-    "types/index.d.ts"
+    "types/index.d.ts",
+    "types/plugin.d.ts",
+    "types/utils.d.ts"
   ],
   "main": "index.js",
   "types": "./types/index.d.ts",
@@ -36,15 +38,21 @@
       "import": "./index.js",
       "require": "./index.js"
     },
-    "./utils": "./utils.js",
-    "./plugin": "./plugin.mjs"
+    "./utils": {
+      "types": "./types/utils.d.ts",
+      "import": "./utils.js",
+      "require": "./utils.js"
+    },
+    "./plugin": {
+      "types": "./types/plugin.d.ts",
+      "import": "./plugin.mjs"
+    }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "test": "vitest run --no-file-parallelism",
-    "test:type": "vitest --ui --typecheck"
+    "test": "vitest run --no-file-parallelism && vitest --typecheck.only --run"
   },
   "dependencies": {
     "@fastify/deepmerge": "^3.1.0",
@@ -58,7 +66,6 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.3",
-    "@vitest/ui": "4.0.16",
     "fastify": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"

packages/fastify-vite/tsconfig.json

@@ -1,5 +1,4 @@
 {
-  "files": ["**/*.ts"],
   "compilerOptions": {
     "target": "esnext",
     "lib": ["ES2020"],

packages/fastify-vite/types/plugin.d.ts

@@ -0,0 +1,29 @@
+import type { Plugin } from 'vite'
+
+export interface ViteFastifyPluginOptions {
+  /**
+   * Enable SPA mode (no SSR environment)
+   */
+  spa?: boolean
+  /**
+   * Path to the client module entry point
+   */
+  clientModule?: string
+  /**
+   * Use paths relative to the application root directory
+   */
+  useRelativePaths?: boolean
+}
+
+/**
+ * Vite plugin for Fastify integration.
+ * Configures Vite environments for client and SSR builds.
+ */
+export declare function viteFastify(options?: ViteFastifyPluginOptions): Plugin
+
+/**
+ * Finds the common path prefix among an array of paths.
+ */
+export declare function findCommonPath(paths: string[]): string
+
+export default viteFastify

packages/fastify-vite/types/plugin.test-d.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from 'vite'
+import { describe, expectTypeOf, it } from 'vitest'
+import viteFastify, { findCommonPath, type ViteFastifyPluginOptions } from './plugin'
+
+describe('plugin types', () => {
+  it('viteFastify returns a Vite Plugin', () => {
+    expectTypeOf(viteFastify()).toExtend<Plugin>()
+    expectTypeOf(viteFastify({})).toExtend<Plugin>()
+    expectTypeOf(viteFastify({ spa: true })).toExtend<Plugin>()
+    expectTypeOf(viteFastify({ clientModule: './client.js' })).toExtend<Plugin>()
+    expectTypeOf(viteFastify({ useRelativePaths: true })).toExtend<Plugin>()
+    expectTypeOf(
+      viteFastify({ spa: false, clientModule: './client.js', useRelativePaths: false }),
+    ).toExtend<Plugin>()
+  })
+
+  it('findCommonPath accepts string array and returns string', () => {
+    expectTypeOf(findCommonPath).parameter(0).toEqualTypeOf<string[]>()
+    expectTypeOf(findCommonPath(['a', 'b'])).toEqualTypeOf<string>()
+  })
+
+  it('ViteFastifyPluginOptions has correct shape', () => {
+    const options: ViteFastifyPluginOptions = {}
+    expectTypeOf(options.spa).toEqualTypeOf<boolean | undefined>()
+    expectTypeOf(options.clientModule).toEqualTypeOf<string | undefined>()
+    expectTypeOf(options.useRelativePaths).toEqualTypeOf<boolean | undefined>()
+  })
+})

packages/fastify-vite/types/utils.d.ts

@@ -0,0 +1,28 @@
+export interface RendererInfo {
+  path: string
+}
+
+export interface SetupOptions {
+  root: string
+  renderer: RendererInfo
+}
+
+/**
+ * Creates an HTML template function from source HTML.
+ * The returned function accepts an object with template variables
+ * and returns the compiled HTML string.
+ */
+export declare function createHtmlTemplateFunction(
+  source: string,
+): Promise<(context?: Record<string, unknown>) => string>
+
+/**
+ * Ensures the Vite config file exists, copying from renderer blueprint if needed.
+ * @returns The path to the config file
+ */
+export declare function ensureConfigFile(base: string, options: SetupOptions): Promise<string>
+
+/**
+ * Ejects the renderer blueprint files to the project root.
+ */
+export declare function ejectBlueprint(base: string, options: SetupOptions): Promise<void>