Share data between vitepress config file and dynamic route paths loader

[pimlie]

Is your feature request related to a problem? Please describe.

Currently it doesn't seem possible to easily share data between your vitepress config and a dynamic paths loader. Nor can you easily share data between a content loader and a dynamic paths loader. It would be nice if this was possible.

A use case for this is when you also want to generate some custom sitemap for your dynamic routes. Or when your data contains a subject and tags and you want to add routes for all. Currently you either have to fetch your dynamic data/routes at least twice or implement fs caching yourself.

Describe the solution you'd like

Some key-value cache / interface so that you can fetch all dynamic routes in your config.ts, then do whatever you want with the data (fe create a sidebar for those dynamic routes), then re-use the already fetched routes in a some/[dynamic].paths.ts loader.

A suggested interface could be as simple as:

UserConfig.router.dynamicRouteData: Record<string | symbol, any>

then

• pass UserData from resolvePages to resolveDynamicRoutes in dynamicRoutesPlugin
• wrap loader call's and pass dynamicRouteData as second argument to the paths loader (first arg is the watched files afaik)

Im not sure if content loaders run before dynamic path loaders? If so then content loaders should probably also have access to this interface

Describe alternatives you've considered

It's not possible to use a virtual: vite module as the paths loaders are called during vite setup, not during vite build.

Additional context

At the moment I'm using a custom VitePress plugin that fetches data, then writes that data to the .vitepress/cache folder and use that data in the some/[dynamic].paths.ts loader. It works, but it's not super nice.

This request is tackling a similar problem as in #2826, but I think a top-down flow (from config to loaders instead of vice versa) is probably the easiest to resolve these cases. It's also similar to the Vue.provide/inject approach.

Another similar problem, also having to read data from fs twice: #3625

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[brc-dd]

Not typescript safe, but this is doable currently too:

// .vitepress/config.ts
import { defineConfig } from 'vitepress'

const routes = await getPathsAndParamsHere()

export default defineConfig({
  sidebar: buildSidebarFrom(routes),
  sitemap: buildSitemapFrom(routes),

  // @ts-ignore
  routes
})

// some/[dynamic].paths.ts
import { defineRoutes, type SiteConfig } from 'vitepress'

const { userConfig } = (global as any).VITEPRESS_CONFIG as SiteConfig

export default defineRoutes({
  async paths() {
    // @ts-ignore
    return userConfig.routes
  }
})

Augment the modules to avoid type casting / or using ts-ignore.

but I think a top-down flow (from config to loaders instead of vice versa) is probably the easiest to resolve these cases

For build, it's easy. For HMR, it'll get tricky. You can't specify watch patterns in config. So, if that routes data is dependent on other files for example, you'll need to restart server every time.

Also, symbols probably won't work.

[pimlie]

Awesome! Is it correct that the global VITEPRESS_CONFIG is a new v2 feature? In my v1 project I get a build error.

You can't specify watch patterns in config

That's a design decision not a technical limitation right? If there was a way to programmatically trigger a HMR it would probably be fine if the user would need to add a custom watcher themselves.

Somewhat related as it's actually the thing that I would like to be able to do, it would be even nicer if there was also a way to add routes programmatically. Then we could have VitePress content plugins that can be fully responsible for loading some doc tree in your project.
An example use case for this is when you want to publish reference documentation of f.e. a python project (created with Sphinx). Currently you need to manually add [data].md and [data].paths.ts files in some sub folder then manually import/load the Sphinx raw content. If routes could be added programmatically then instead a SphinxImport content plugin could have just a configuration like

UserConfig.sphinx.paths = Record<baseHref: string, pathToSphinxDocs: string>

  sphinx: {
    paths: {
      "/reference/my-python-lib": "../my-python-lib/docs/build"
    }
  }

which then could just make the full Sphinx docs available under that path :)

That said, I'd understand if the efforts required to support this do not weigh up against the essentially little boiler plating that needs to be done by the user currently. But wanted to share my full use case with you 🧡

[brc-dd]

Awesome! Is it correct that the global VITEPRESS_CONFIG is a new v2 feature? In my v1 project I get a build error.

Nope, should've worked fine in v1 too. (https://vitepress.dev/guide/data-loading#configuration) 👀 Though, not fully sure if it was/is working with route loaders. If it's not, it's a bug.

That's a design decision not a technical limitation right? If there was a way to programmatically trigger a HMR it would probably be fine if the user would need to add a custom watcher themselves.

Yeah. The watcher is customizable via vite plugins, but triggering HMR is tricky. Probably be better to support that out of the box.

Somewhat related as it's actually the thing that I would like to be able to do, it would be even nicer if there was also a way to add routes programmatically. Then we could have VitePress content plugins that can be fully responsible for loading some doc tree in your project.

This is also possible. You can write a vite plugin that assigns config.vitepress.siteConfig.dynamicRoutes in configResolved or other hooks. Mostly I think it should work, but there might be some edge cases, which can be fixed as they are discovered.

We definitely need to update the docs, but most of the things are doable 😅

[brc-dd]

Here is a demo - https://github.com/brc-dd/vp-dynamic-routes-injection/blob/b1dfd99baa44c1e795c79ffb02ce35d4c4181a36/.vitepress/config.ts#L11-L32

Ah, build is broken..

[pimlie]

Could it be that VITEPRESS_CONFIG is only available in data loaders, not in path loaders?

[brc-dd]

Hmm yeah. I'll fix that. I thought it was there in both.

[brc-dd]

Fixed that demo thing btw - https://github.com/brc-dd/vp-dynamic-routes-injection/blob/main/.vitepress/plugin/index.ts - needed to add new pages to rollupOptions.input too.

So, it's bit verbose if you're a plugin author, but for end users it will be as simple as:

import yourPlugin from 'your-plugin-package'

export default defineConfig({
  vite: {
    plugins: [yourPlugin(options)]
  }
})

[brc-dd]

Regarding VITEPRESS_CONFIG in path loaders, now I realize why it isn't available:

It's because resolvePages is being called before config is available. We can assign it partially, so that you have access to other things, but pages related things won't be there in path loaders.

  const config = {
    ...other stuff,
    ...(await resolvePages(srcDir, userConfig, logger, true))
  }

  // to be shared with content loaders
  // @ts-ignore
  global.VITEPRESS_CONFIG = config

[brc-dd]

Try the nightly builds, it should work fine:

pnpm add -D https://pkg.pr.new/vitepress@56ba65e

[brc-dd]

wrap loader call's and pass dynamicRouteData as second argument to the paths loader (first arg is the watched files afaik)

We can probably do this and pass whole config as ctx.config in last argument. That way it will be type safe and won't need casting, etc for existing stuff. For custom stuff it will still need module augmentation.

[pimlie]

Thanks for all your quick actions! 😻

pass whole config as ctx.config in last argument

I was worried that that might cause issues with or give the wrong impression to developers about what you can do with the config passed to a loader if it receives a fully mutable config. But as it would be similar to VITEPRESS_CONFIG I guess thats not an issue?