feat: New vite plugin config: useRelativePaths (#283)

onlywei · web-flow · commit cb2824d0a937 · 2025-08-04T11:30:21.000-04:00
* Add unit tests for findCommonPath so I know what its doing

* Add "useRelativePaths" option to vite plugin

* useRelativePaths in react examples

* Add docs for useRelativePaths
diff --git a/docs/guide/build-and-deploy.md b/docs/guide/build-and-deploy.md
@@ -51,6 +51,7 @@ The `viteFastify` plugin can be given the following options:
 
 * `spa` - Set this to `true` to disable the SSR build entirely. Default: `false`.
 * `clientModule` - The location of the SSR entry point, relative to the index.html file. Defaults to `index.js`. You can also use an absolute path to be extra safe.
+* `useRelativePaths` - Set this to `true` to avoid saving absolute paths in the `vite.config.json` file. This is useful if the machine you run the build on is NOT the machine you plan to run the server on (for example: if you build on a local machine but then copy the results into a Docker container). This results in a more hermetic application distribution. In a future release, this will be defaulted to `true`.
 
 Assuming you do not need to build your Fastify server itself, the only build script you need in your `package.json` file is below:
 
diff --git a/examples/react-vanilla-spa-ts/vite.config.js b/examples/react-vanilla-spa-ts/vite.config.js
@@ -5,7 +5,7 @@ import viteReact from '@vitejs/plugin-react'
 export default {
   root: resolve(import.meta.dirname, 'src', 'client'),
   plugins: [
-    viteFastify({ spa: true }),
+    viteFastify({ spa: true, useRelativePaths: true }),
     viteReact()
   ],
   build: {
diff --git a/examples/react-vanilla-spa/client/base.css b/examples/react-vanilla-spa/client/base.css
@@ -0,0 +1,15 @@
+html {
+  background: #f0e5d3;
+}
+* {
+  font-size: 1.2em;
+  font-family: sans-serif;
+}
+button {
+  margin: 0 0.5em;
+}
+#root {
+  display: flex;
+  place-items: center;
+  flex-direction: column;
+}
diff --git a/examples/react-vanilla-spa/vite.config.js b/examples/react-vanilla-spa/vite.config.js
@@ -5,7 +5,7 @@ import viteReact from '@vitejs/plugin-react'
 export default {
   root: join(import.meta.dirname, 'client'),
   plugins: [
-    viteFastify({ spa: true }),
+    viteFastify({ spa: true, useRelativePaths: false }),
     viteReact()
   ],
 }
diff --git a/examples/react-vanilla-ts/vite.config.js b/examples/react-vanilla-ts/vite.config.js
@@ -5,7 +5,7 @@ import viteReact from '@vitejs/plugin-react'
 export default {
   root: resolve(import.meta.dirname, 'src', 'client'),
   plugins: [
-    viteFastify(),
+    viteFastify({ useRelativePaths: true }),
     viteReact()
   ],
   build: {
diff --git a/examples/react-vanilla/vite.config.js b/examples/react-vanilla/vite.config.js
@@ -5,7 +5,7 @@ import viteReact from '@vitejs/plugin-react'
 export default {
   root: join(import.meta.dirname, 'client'),
   plugins: [
-    viteFastify(),
+    viteFastify({ useRelativePaths: true }),
     viteReact()
   ],
 }
diff --git a/packages/fastify-vite/config.js b/packages/fastify-vite/config.js
@@ -317,13 +317,22 @@ async function resolveViteConfig(root, dev, { spa, distDir } = {}) {
   ]
 }
 
+async function determineOutDirRoot(vite) {
+  const { usePathsRelativeToAppRoot } = vite.fastify
+  if (usePathsRelativeToAppRoot) {
+    const { packageDirectory } = await import('package-directory')
+    return await packageDirectory()
+  }
+  return vite.root
+}
+
 async function resolveSSRBundle({ dev, vite }) {
   const bundle = {}
   let clientOutDir
 
   if (!dev) {
     if (vite.fastify) {
-      clientOutDir = resolveIfRelative(vite.fastify.outDirs.client, vite.root)
+      clientOutDir = resolveIfRelative(vite.fastify.outDirs.client, await determineOutDirRoot(vite))
     } else {
       // Backwards compatibility for projects that do not use the viteFastify plugin.
       bundle.dir = resolveIfRelative(vite.build.outDir, vite.root)
@@ -360,7 +369,7 @@ async function resolveSPABundle({ dev, vite }) {
     let clientOutDir
 
     if (vite.fastify) {
-      clientOutDir = resolveIfRelative(vite.fastify.outDirs.client, vite.root)
+      clientOutDir = resolveIfRelative(vite.fastify.outDirs.client, await determineOutDirRoot(vite))
     } else {
       // Backwards compatibility for projects that do not use the viteFastify plugin.
       bundle.dir = resolveIfRelative(vite.build.outDir, vite.root)
diff --git a/packages/fastify-vite/mode/production.js b/packages/fastify-vite/mode/production.js
@@ -23,8 +23,16 @@ async function setup(config) {
   let ssrOutDir
 
   if (vite.fastify) {
-    clientOutDir = resolveIfRelative(vite.fastify.outDirs.client, vite.root)
-    ssrOutDir = resolveIfRelative(vite.fastify.outDirs.ssr || '', vite.root)
+    const { outDirs, usePathsRelativeToAppRoot } = vite.fastify
+
+    let outDirRoot = vite.root
+    if (usePathsRelativeToAppRoot) {
+      const { packageDirectory } = await import('package-directory')
+      outDirRoot = await packageDirectory()
+    }
+
+    clientOutDir = resolveIfRelative(outDirs.client, outDirRoot)
+    ssrOutDir = resolveIfRelative(outDirs.ssr || '', outDirRoot)
   } else {
     // Backwards compatibility for projects that do not use the viteFastify plugin.
     const outDir = resolveIfRelative(vite.build.outDir, vite.root)
@@ -37,11 +45,11 @@ async function setup(config) {
   const { assetsDir } = vite.build
 
   if (!exists(clientOutDir)) {
-    throw new Error('No client distribution bundle found.')
+    throw new Error(`No client distribution bundle found at ${clientOutDir}.`)
   }
 
   if (!spa && !exists(ssrOutDir)) {
-    throw new Error('No SSR distribution bundle found.')
+    throw new Error(`No SSR distribution bundle found at ${ssrOutDir}.`)
   }
 
   // We also register fastify-static to serve all static files
diff --git a/packages/fastify-vite/package.json b/packages/fastify-vite/package.json
@@ -52,7 +52,8 @@
     "find-cache-dir": "^5.0.0",
     "fs-extra": "^11.3.0",
     "html-rewriter-wasm": "^0.4.1",
-    "klaw": "^4.1.0"
+    "klaw": "^4.1.0",
+    "package-directory": "^8.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
diff --git a/packages/fastify-vite/plugin.mjs b/packages/fastify-vite/plugin.mjs
@@ -1,45 +1,46 @@
+import { isAbsolute, join, relative, sep } from 'node:path'
 import getDeepMergeFunction from '@fastify/deepmerge'
-import { isAbsolute, join, write, sep } from './ioutils.cjs'
+import { writeFile } from 'node:fs/promises'
 
-export function viteFastify({ spa, clientModule } = {}) {
-  let configuredOutDir
+export function viteFastify({ spa, clientModule, useRelativePaths = false } = {}) {
+  let customOutDir
   let jsonFilePath
   let configToWrite = {}
   let resolvedConfig = {}
 
   return {
     name: 'vite-fastify',
     enforce: 'pre',
-    async config(config, { mode }) {
-      configuredOutDir = config.build?.outDir
-      const dev = mode === 'development'
-      const outDir = configuredOutDir ?? 'dist'
+    async config(rawConfig, { mode }) {
+      customOutDir = rawConfig.build?.outDir
+      const isDevMode = mode === 'development'
+      const outDir = customOutDir ?? 'dist'
       const deepMerge = getDeepMergeFunction()
       const {
         resolveClientModule,
         createSSREnvironment,
         createClientEnvironment,
       } = await import('./config.js')
 
-      if (!config.environments) {
-        config.environments = {}
+      if (!rawConfig.environments) {
+        rawConfig.environments = {}
       }
-      config.environments.client = deepMerge(
-        createClientEnvironment(dev, outDir),
-        config.environments.client ?? {},
+      rawConfig.environments.client = deepMerge(
+        createClientEnvironment(isDevMode, outDir),
+        rawConfig.environments.client ?? {},
       )
       if (!spa) {
-        const ssrEntryPoint = clientModule ?? resolveClientModule(config.root)
-        config.environments.ssr = deepMerge(
-          createSSREnvironment(dev, outDir, ssrEntryPoint),
-          config.environments.ssr ?? {},
+        const ssrEntryPoint = clientModule ?? resolveClientModule(rawConfig.root)
+        rawConfig.environments.ssr = deepMerge(
+          createSSREnvironment(isDevMode, outDir, ssrEntryPoint),
+          rawConfig.environments.ssr ?? {},
         )
-        if (!config.builder) {
-          config.builder = {}
+        if (!rawConfig.builder) {
+          rawConfig.builder = {}
         }
         // Write the JSON file after the bundle finishes writing to avoid getting deleted by emptyOutDir
-        if (!config.builder.buildApp) {
-          config.builder.buildApp = async (builder) => {
+        if (!rawConfig.builder.buildApp) {
+          rawConfig.builder.buildApp = async (builder) => {
             await builder.build(builder.environments.client)
             await builder.build(builder.environments.ssr)
           }
@@ -90,7 +91,12 @@ export function viteFastify({ spa, clientModule } = {}) {
         fastify,
       }
 
-      let commonDistFolder = configuredOutDir // respect custom build.outDir config if provided
+      if (useRelativePaths) {
+        await makeAllPathsRelative(configToWrite)
+        fastify.usePathsRelativeToAppRoot = !!customOutDir
+      }
+
+      let commonDistFolder = customOutDir // respect custom build.outDir config if provided
       if (!commonDistFolder) {
         const outDirs = Object.values(fastify.outDirs)
         commonDistFolder = outDirs.length > 1
@@ -106,7 +112,7 @@ export function viteFastify({ spa, clientModule } = {}) {
       }
     },
     async writeBundle() {
-      await write(
+      await writeFile(
         jsonFilePath,
         JSON.stringify(configToWrite, undefined, 2),
         'utf-8',
@@ -119,7 +125,7 @@ export function findCommonPath(paths) {
   if (paths.length === 1) {
     return paths[0]
   }
-  const segments = paths.map((path) => path.split('/'))
+  const segments = paths.map((path) => path.split(sep))
   const minLength = Math.min(...segments.map((arr) => arr.length))
   const commonSegments = []
   for (let i = 0; i < minLength; i++) {
@@ -131,7 +137,23 @@ export function findCommonPath(paths) {
     }
   }
 
-  return commonSegments.join('/')
+  return commonSegments.join(sep)
+}
+
+async function makeAllPathsRelative(viteConfig) {
+  const { packageDirectory } = await import('package-directory')
+  const applicationRootDirectory = await packageDirectory() // location of user's package.json
+  const { build, fastify } = viteConfig
+
+  viteConfig.root = relative(applicationRootDirectory, viteConfig.root)
+
+  if (build?.outDir) {
+    build.outDir = relative(applicationRootDirectory, build.outDir)
+  }
+
+  Object.keys(fastify.outDirs).forEach((key) => {
+    fastify.outDirs[key] = relative(applicationRootDirectory, fastify.outDirs[key])
+  })
 }
 
 export default viteFastify
diff --git a/packages/fastify-vite/plugin.test.mjs b/packages/fastify-vite/plugin.test.mjs
@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { sep } from 'node:path'
+import { findCommonPath } from './plugin.mjs'
+
+describe('findCommonPath', () => {
+  it('should throw an error for empty input', () => {
+    expect(() => findCommonPath([])).toThrow()
+  })
+
+  it('should return the path itself when only one path is provided', () => {
+    expect(findCommonPath(['a/b/c'.split('/').join(sep)])).toBe('a/b/c'.split('/').join(sep))
+  })
+
+  it('should find the common path among multiple paths', () => {
+    expect(findCommonPath(['a/b/c'.split('/').join(sep), 'a/b/d'.split('/').join(sep)])).toBe('a/b'.split('/').join(sep))
+  })
+
+  it('should return an empty string if there is no common path', () => {
+    expect(findCommonPath(['a/b/c'.split('/').join(sep), 'd/e/f'.split('/').join(sep)])).toBe('')
+  })
+
+  it('should handle paths of different lengths', () => {
+    expect(findCommonPath(['a/b/c/d'.split('/').join(sep), 'a/b'.split('/').join(sep)])).toBe('a/b'.split('/').join(sep))
+  })
+
+  it('should handle more than two paths', () => {
+    expect(findCommonPath(['a/b/c'.split('/').join(sep), 'a/b/d'.split('/').join(sep), 'a/b/e'.split('/').join(sep)])).toBe('a/b'.split('/').join(sep))
+  })
+
+  it('should return the full path if all paths are identical', () => {
+    expect(findCommonPath(['a/b/c'.split('/').join(sep), 'a/b/c'.split('/').join(sep), 'a/b/c'.split('/').join(sep)])).toBe('a/b/c'.split('/').join(sep))
+  })
+
+  it('should work with root paths', () => {
+    const paths = ['/a/b/c'.split('/').join(sep), '/a/b/d'.split('/').join(sep)]
+    // In Windows, a root path starts with a drive letter (e.g., C:).
+    // The current logic will consider the drive letter part of the common path.
+    // This test ensures it behaves as expected on both platforms.
+    if (sep === '\\') {
+      expect(findCommonPath(paths)).toBe(`${paths[0].split(sep)[0]}${sep}a${sep}b`)
+    } else {
+      expect(findCommonPath(paths)).toBe('/a/b'.split('/').join(sep))
+    }
+  })
+
+  it('should be case-sensitive', () => {
+    expect(findCommonPath(['A/b/c'.split('/').join(sep), 'a/b/d'.split('/').join(sep)])).toBe('')
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@ import viteReact from '@vitejs/plugin-react'`
`5`	`5`	`export default {`
`6`	`6`	`root: join(import.meta.dirname, 'client'),`
`7`	`7`	`plugins: [`
`8`		`- viteFastify({ spa: true }),`
	`8`	`+ viteFastify({ spa: true, useRelativePaths: false }),`
`9`	`9`	`viteReact()`
`10`	`10`	`],`
`11`	`11`	`}`