How to deactivate the hash in the filenames?

[fmabap]

Hi,

we have a vitepress documentation where multiple users work simultaneal on different markdown files.

When we build the html files of it, then it renders also the unchanged files again and the generated files (JS, images…) get a new hash at the end of the filename.

This leads to a regeneration of the whole documentation, which leads sometimes to git merge conflicts based on the simultaneal changes of the multiple users.

Is there an option to deactivate the hash or to use always the same hash in the generated filenames?

[zhangyx1998]

Consider ignoring the build artifact (dist/) from git. It should not be version-controlled.

[fmabap]

Hi Yuxuan,

thank you very much for your reply. The documentation is hosted on a GitHub Enterprise Server with GitHub Pages. On this server are no GitHub Actions allowed. So we have to build it local and commit it to the server.

[brc-dd]

If there are many people simultaneously working on a repo, it feels weird not have some sort of CI/CD pipeline. As a possible workaround, you can assign someone to periodically build and upload the artifacts to a different branch, and use that branch as GitHub pages target.

[fmabap]

Thank you very much, this could be an organisational solution.

But is there no technical solution for it?

It looks like that Vite has the possibility to remove the hashes as described here:

https://blog.livelyupward.dev/blog/remove-vite-hash

Is it possible to use this approach also for VitePress?

[zhangyx1998]

@brc-dd Maybe we can optionally strip the hash from filenames and instead affix them as URL queries for browser hash control?

For example:

- pagePath = `${base}${__ASSETS_DIR__}/${pagePath}.${pageHash}.js`
+ pagePath = `${base}${__ASSETS_DIR__}/${pagePath}.js?${pageHash}`

In html files:

-    <script type="module" src="/assets/app.CyXjMrYi.js"></script>
+    <script type="module" src="/assets/app.js?CyXjMrYi"></script>

[brc-dd]

The emitted assets won't be fingerprinted then. CDNs won't be able to cache them. The caching at browser-level won't be effective as well without the server explicitly sending cache headers for those requests.

[zhangyx1998]

Changing the query string from a client request will bypass CDN cache and cause it to fallback to origin - I guess this will serve the same purpose as a in-name cache string if it's what you're concerning.

[brc-dd]

Not exactly. For example, Vercel doesn't cache bust depending on query params for static files. https://vercel.com/docs/edge-cache#cache-invalidation

[zhangyx1998]

Hmm, how about making this a configurable option? Default behavior will be embedding hash in the name.

[brc-dd]

Seems unnecessary to me unless there is much demand. The OP has a very specific use case which most of the users won't encounter. Also, regarding the post they shared above for disabling hashes in vite, those options were added to support library mode. Disabling hash in applications was never the goal of those options.

[brc-dd]

As a workaround, you can add some plugin like this:

import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    plugins: [
      {
        name: 'remove-hash',
        enforce: 'post',
        config(config) {
          const ssr = !!config.build?.ssr
          return {
            build: {
              rollupOptions: {
                output: {
                  assetFileNames: `assets/[name].0.[ext]`,
                  ...(ssr
                    ? {
                        entryFileNames: '[name].js',
                        chunkFileNames: '[name].0.js'
                      }
                    : {
                        entryFileNames: `assets/[name].0.js`,
                        chunkFileNames: `assets/chunks/[name].0.js`
                      })
                }
              }
            }
          }
        }
      }
    ]
  }
})

It will set hash of everything to 0. This should not cause issues with anything the router depends on. The OP is deploying on github pages so the caching related issues will be minimal since it only caches for 10 minutes.

[fmabap]

Thank you very much, this seams to work in general, but there is an issue with the images.

The images have no unique name. We have for example image.png in sub folder A and image.png in sub folder B. Vitepress generates all images in the assets folder without sub folders.

The images gets a new name image.0.png for the one from sub folder A and image.1.png for the one from sub folder B.

When I rebuild the documentation then the numbering of the images is not the same. Image.0.png will be the one from sub folder B and image.1.png will be the one from sub folder A.

This leads also to changes on the js files.

Is there a solution for this? For example to generate the sub folders in the assets folder?

[brc-dd]

You can pass a function to assetFileNames for that and customize the output path.

https://rollupjs.org/configuration-options/#output-assetfilenames

Something like this should work:

assetFileNames(chunkInfo) {
  const filename = chunkInfo.originalFileNames[0]
  if (filename && !filename.startsWith('.')) return filename
  return `assets/[name].[ext]`
}

[fmabap]

Thank you very much again.

We found a solution.

We replaced just the 0 at the assetFilenames with [hash].

Old:

 assetFileNames: `assets/[name].0.[ext]`,

New:

 assetFileNames: `assets/[name].[hash].[ext]`,

It looks at the end like this:

import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    plugins: [
      {
        name: 'remove-hash',
        enforce: 'post',
        config(config) {
          const ssr = !!config.build?.ssr
          return {
            build: {
              rollupOptions: {
                output: {
                  assetFileNames: `assets/[name].[hash].[ext]`,
                  ...(ssr
                    ? {
                        entryFileNames: '[name].js',
                        chunkFileNames: '[name].0.js'
                      }
                    : {
                        entryFileNames: `assets/[name].0.js`,
                        chunkFileNames: `assets/chunks/[name].0.js`
                      })
                }
              }
            }
          }
        }
      }
    ]
  }
})