feat: allow change the HTML filename (#459)

Author: userquin

examples/multiple-pages-with-store/package.json

@@ -5,6 +5,7 @@
     "dev": "DEBUG='vite-ssg:*' vite",
     "build": "DEBUG='vite-ssg:*' vite-ssg build",
     "build:nested": "NESTED_PAGES=true DEBUG='vite-ssg:*' vite-ssg build",
+    "build:test": "LOG_ROUTES=true NESTED_PAGES=true DEBUG='vite-ssg:*' vite-ssg build",
     "serve": "vite preview"
   },
   "dependencies": {

examples/multiple-pages-with-store/vite.config.ts

@@ -27,6 +27,12 @@ const config: UserConfig = {
     script: 'async',
     dirStyle: process.env.NESTED_PAGES === 'true' ? 'nested' : 'flat',
     formatting: 'prettify',
+    htmlFileName: process.env.LOG_ROUTES === 'true'
+      ? (filename) => {
+          console.log(`Generating HTML file: ${filename}`)
+          return undefined
+        }
+      : undefined,
   },
 }
 

src/node/build.ts

@@ -17,7 +17,7 @@ import { mergeConfig, resolveConfig, build as viteBuild } from 'vite'
 import { serializeState } from '../utils/state'
 import { getBeasties } from './critical'
 import { renderPreloadLinks } from './preload-links'
-import { buildLog, getSize, routesToPaths } from './utils'
+import { buildLog, getSize, prepareHtmlFileName, routesToPaths } from './utils'
 
 export type Manifest = Record<string, string[]>
 
@@ -55,6 +55,7 @@ export async function build(ssgOptions: Partial<ViteSSGOptions> = {}, viteConfig
     concurrency = 20,
     rootContainerId = 'app',
     base,
+    htmlFileName,
   }: ViteSSGOptions = mergedOptions
 
   const beastiesOptions = mergedOptions.beastiesOptions ?? {}
@@ -196,9 +197,12 @@ export async function build(ssgOptions: Partial<ViteSSGOptions> = {}, viteConfig
           ? `${route}index`
           : route).replace(/^\//g, '')}.html`
 
-        const filename = dirStyle === 'nested'
-          ? join(route.replace(/^\//g, ''), 'index.html')
-          : relativeRouteFile
+        const filename = await prepareHtmlFileName(
+          dirStyle === 'nested'
+            ? join(route.replace(/^\//g, ''), 'index.html')
+            : relativeRouteFile,
+          htmlFileName,
+        )
 
         await fs.mkdir(resolve(out, dirname(filename)), { recursive: true })
         await fs.writeFile(resolve(out, filename), formatted, 'utf-8')

src/node/utils.ts

@@ -1,3 +1,4 @@
+import type { ViteSSGOptions } from 'vite-ssg'
 import type { RouteRecordRaw } from 'vue-router'
 import { blue, gray, yellow } from 'ansis'
 
@@ -10,6 +11,18 @@ export function getSize(str: string) {
   return `${(str.length / 1024).toFixed(2)} KiB`
 }
 
+export async function prepareHtmlFileName(
+  filename: string,
+  htmlFileName?: ViteSSGOptions['htmlFileName'],
+) {
+  filename = filename.replace(/\\/g, '/')
+  if (!htmlFileName)
+    return filename
+
+  const newFileName = await htmlFileName(filename)
+  return newFileName || filename
+}
+
 export function routesToPaths(routes?: Readonly<RouteRecordRaw[]>) {
   if (!routes)
     return ['/']

src/types.ts

@@ -113,6 +113,28 @@ export interface ViteSSGOptions {
    * @default 20
    */
   concurrency?: number
+
+  /**
+   * Given a Vue route, `vite-ssg` will use the route path to generate the HTML file, this function
+   * will allow you to change that HTML filename.
+   *
+   * For example, using `unplugin-vue-router/vite` plugin on Windows, the `catch all` (`[...all].vue`)
+   * page will throw an error since the file (`:all(.*).html`) is not a valid file name on Windows
+   * filesystem. Old `vite-plugin-pages` plugin allows us to change the route styles to Nuxt, but this
+   * feature is still missing at `unplugin-vue-router/vite`.
+   *
+   * Beware that this function is called for every route; you can return `undefined` to keep the
+   * default behavior for unchanged routes.
+   *
+   * Beware also that you will need to handle the new file in your backend server, as the file name
+   * will not match the route name.
+   *
+   * The provided HTML filename will always be relative to the output directory.
+   *
+   * @param filename The file name including the `.html` extension.
+   * @return The new file name, or `undefined` to keep the default behavior.
+   */
+  htmlFileName?: (filename: string) => string | undefined | Promise<string | undefined>
 }
 
 type PartialKeys<T, Keys extends keyof T> = Omit<T, Keys> & Partial<Pick<T, Keys>>