Moving VitePress' Node API as ESM only

[brc-dd]

Vite might be removing/deprecating it's CJS API is near future (vitejs/vite#13928) which will impact VitePress' CJS API as well.

Edit: Let's wait on discussion at Vite's side to conclude and we will try to follow their footsteps. But, it is recommended to use ESM APIs for anything new you might be building.

Most of the projects already appear to be using the import syntax. A quick GitHub code search shows about 20 public projects doing require('vitepress'). Exploring more, over half of them appear to be on vitepress@0.x branch. Leaving less than 10 projects that might need minor refactoring.

import syntax in config.js file when "type": "module" is not specified in nearest package.json also uses the CJS build. Might be difficult to estimate the impact. But for most of the cases where people are using import without type module or mjs/mts extension the migration should be straight forward -- either change the file extension or project level type.

Migration:

// use .mjs/.mts file extension if can't use `"type": "module"`

// change
const { defineConfig } = require('vitepress')

module.exports = {/*...*/}

// to
import { defineConfig } from 'vitepress'

export default {/*...*/}

// or since it's just a type helper simply do something like this

/** @type {ReturnType<typeof import('vitepress').defineConfig>} */
module.exports = {/*...*/}

// change
const { createMarkdownRenderer } = require('vitepress')
      // ^ or any async API like createServer, build, resolveConfig, resolveSiteData

async fn() {
  const md = await createMarkdownRenderer(/*...*/)
}

// to
async fn() {
  const { createMarkdownRenderer } = await import('vitepress')
  const md = await createMarkdownRenderer(/*...*/)
}

---

For maintainers, we will need to use jiti for the CLI and remove CJS stuff from rollup config.

CLI won't need any changes, it's already CJS compatible and uses ESM output. Only rollup related changes need to be done.

Rollout plan:

Let's log a warning for now if someone require's the package. We can drop the CJS API by RC.

/cc @kiaking @zonemeen

[zonemeen]

I think this kind of plan works.

[benmccann]

Most of the projects already appear to be using the import syntax. A quick GitHub code search shows about 20 public projects doing require('vitepress'). Exploring more, over half of them appear to be on vitepress@0.x branch. Leaving less than 10 projects that might need minor refactoring.

I sent PRs to a half dozen of these and filed issues with a handful more.

Let's log a warning for now if someone require's the package. We can drop the CJS API by RC.

This might end up causing multiple warnings if Vite decides to go the route of logging warnings. Honestly, it's probably easier to just go ahead and drop the CJS API now, so that you don't have to do a followup PR. I've either fixed or notified the affected projects and the error message will be a pretty common one since lots of projects are doing this migration, so there will be plenty of info out there on how to fix it.

[benmccann]

An update from vitejs/vite#13928 - we have PRs out now to migrate all projects to ESM except for Vitepress and Storybook