Bug: cannot apply git-changelog plugin

[g-dx]

First, thanks for producing some amazing plugins for Vitepress :tada:

I'm trying to use v1.18.0 of the Git Changelog Plugin but Vite seems unable to process it.

Given the following:

package.json

{
  "name": "docs",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "docs:dev": "vitepress dev .",
    "docs:build": "vitepress build .",
    "docs:preview": "vitepress preview ."
  },
  "dependencies": {
    "vitepress": "1.0.0-rc.40",
    "@nolebase/vitepress-plugin-git-changelog": "^1.18.0"
  }
}

.vitepress/theme/index.ts

import DefaultTheme from 'vitepress/theme';
import type { Theme as ThemeConfig } from 'vitepress'

import {
  NolebaseGitChangelogPlugin,
} from '@nolebase/vitepress-plugin-git-changelog/client'

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  enhanceApp({app}) {
    app.use(NolebaseGitChangelogPlugin)
  }
}

export default Theme;

index.md

# Helloworld!

I get the following when attempting to run npm docs:build

> docs@0.0.1 docs:build
> vitepress build .

  vitepress v1.0.0-rc.40

[vite]: Rollup failed to resolve import "virtual:nolebase-git-changelog" from "/home/g-dx/docs/node_modules/@nolebase/vitepress-plugin-git-changelog/dist/client/index.mjs".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`
✖ building client + server bundles...
build error:
Error: [vite]: Rollup failed to resolve import "virtual:nolebase-git-changelog" from "/home/g-dx/docs/node_modules/@nolebase/vitepress-plugin-git-changelog/dist/client/index.mjs".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`
    at viteWarn (file:///home/g-dx/Workspaces/insights/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:67319:27)
    at onRollupWarning (file:///home/g-dx/Workspaces/insights/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:67347:9)
    at onwarn (file:///home/g-dx/Workspaces/insights/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:67064:13)

When running npm docs:dev I get the following error:

> docs@0.0.1 docs:dev
> vitepress dev .

  vitepress v1.0.0-rc.40

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help
21:46:01 [vitepress] Pre-transform error: Missing "./dist/client" specifier in "@nolebase/vitepress-plugin-git-changelog" package
21:46:01 [vitepress] Internal server error: Missing "./dist/client" specifier in "@nolebase/vitepress-plugin-git-changelog" package
  Plugin: vite:import-analysis
  File: /home/g-dx/docs/.vitepress/theme/index.ts
      at e (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:21914:25)
      at n (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:21914:627)
      at o (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:21914:1297)
      at resolveExportsOrImports (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:29466:20)
      at resolveDeepImport (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:29485:31)
      at tryNodeResolve (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:29210:20)
      at Context.resolveId (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:28978:28)
      at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
      at async Object.resolveId (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:63987:32)
      at async TransformContext.resolve (file:///home/g-dx/docs/node_modules/vite/dist/node/chunks/dep-9A4-l-43.js:63692:23)

Am I missing some configuration somewhere?

[nekomeowww]

@g-dx Ah yes.

Sorry about the lack of documentations here. I will try to complete the documentations ASAP this weekend.

You've completed the steps to install the UI components, congrats!

Than you need a vite.config.ts or vite option in config property of vitepress, to configure these two Vite plugins to read, prepare the git log data for components to render with, as well as transforming the Markdown file with the two new additional sections:

https://github.com/nolebase/integrations/blob/08c4e47f43f4678e2138401f8b62a1966a48b6ba/docs/vite.config.ts#L11-L35

Don't forget to include the stylesheets as well:

https://github.com/nolebase/integrations/blob/08c4e47f43f4678e2138401f8b62a1966a48b6ba/docs/.vitepress/theme/index.ts#L30

Btw, nice and such detailed issue description! Thank you for writing all these down for us to better understand the situation!

[g-dx]

Hi @nekomeowww

Thanks for your detailed response (my apologies as I did configure config.ts but forgot to add it to the original report!)

I've created a reproduction of this issue over on StackBlitz here: https://stackblitz.com/edit/vite-2g78w6

You can see the site doesn't load as StackBlitz is unable to resolve the dependencies:

I see the same thing in my IDE.

[nekomeowww]

Thanks for the detailed updates! Nice reproduction.

Good news

The good news is the Cannot find module *** or its corresponding type declarations is quite easy to fix.

Both VitePress, Nolebase and Nolebase Integrations uses Vite to bundle and transform the files. Vite depends on esbuild and rollup, which are bundlers too.

Therefore, in order to make everything work as expected and be able to import the subdirectory contained modules, we need to tweak the default behavior of TypeScript by configuring tsconfig.json and set the moduleResolution to Bundler.

So simply create a tsconfig.json and copy paste the contents below in the root directory:

{
  "compilerOptions": {
    "target": "ESNext",
    "jsx": "preserve", // Can be deleted if you don't write any JSX, TSX components, and won't import any
    "lib": ["DOM", "ESNext"], // Since this is a website, should have DOM types and contexts.
    "baseUrl": ".",
    "module": "ESNext", // This line must be changed to "ESNext"
    "moduleResolution": "Bundler", // This line must be changed to "Bundler"
    "resolveJsonModule": true, // Can be deleted if you don't have JSON modules
    "types": ["vite/client"], // Vite related types
    "allowJs": true, // The vitepress lives in node_modules contains `.js` files, you probably need this.
    "strict": true, // More strict rules
    "strictNullChecks": true, // Check for nulls
    "noUnusedLocals": true, // Check for unused
    "esModuleInterop": true, // Help you transform es modules
    "forceConsistentCasingInFileNames": true, // Can be deleted, just some casing enforcements
    "isolatedModules": true, // Required by "Bundler"
    "skipLibCheck": true // Skip type checks in `node_modules`
  },
  "include": [
    // Hidden directories are omiited by default, must include explicitly
    "docs/.vitepress/**/*.ts",
    "docs/.vitepress/**/*.tsx",
    "docs/.vitepress/**/*.vue"
  ]
}

If you don't have typescript as devDependencies, it is recommended to install one by:

npm install typescript -D

yarn add typescript -D

pnpm i typescript -D

Bad news

Problem 1

I found an undocumented vitepress behavior when it comes to declare plugins within vitepress's config.ts by comparing to a dedicated vite's vite.config.ts. Such undocumented behavior will cause both git changelog plugin and newly added page properties plugins transform and append the markdown sections to files during vite's building process. And then eventually cause the malformation of built cjs, esm files. This should be fixed by #69 .

This is easy to get it fixed now by upgrading plugins to latest versions.

But still, it is recommended to have a dedicated vite.config.ts.

To do this, install vite first:

npm install vite -D

yarn add vite -D

pnpm i vite -D

And then create a dedicated vite.config.ts next to .vitepress directory, or directly under root directory and then define the plugins there:

import { defineConfig } from 'vite'
import { GitChangelog, GitChangelogMarkdownSection } from '@nolebase/vitepress-plugin-git-changelog/vite'

export default defineConfig(async () => {
  return {
    assetsInclude: ['**/*.mov', '**/*.mp4'],
    plugins: [
      GitChangelog(),
      GitChangelogMarkdownSection(),
    ],
  }
})

Problem 2

Since vitepress-plugin-git-changelog relies on git cli to be present and configured correctly to obtain the changelogs and file histories from git log command (provided and wrapped by simple-git npm package), the reproduction and future demonstration on platforms like StackBlitz without git cli will need some workaround for the UI part of vitepress-plugin-git-changelog to work (because it requires a virtual module called virtual:nolebase-git-changelog module that only the GitChangelog() is capable to export).

Therefore, it is quite awkward to say, it is now impossible to demo and run the vitepress-plugin-git-changelog on StackBlitz easily.

However, I tweaked the code a little bit to make it possible to resolve the virtual modules with a fake GitChangelog() that exports an empty array of commits.

Anyway, no worries, I have modified the provided StackBlitz repo by you with the working version and the issues a mentioned resolved: https://stackblitz.com/edit/vite-bbvtbq?file=docs%2F.vitepress%2Fconfig.ts

Feel free to ask if you encountered further problems when setting up. (We should also consider these problems within documentations as the troubleshooting section)

[nekomeowww]

Closed due to stale. You are welcomed to open it again if you have any further questions.

[g-dx]

Hey, thanks again for your response & apologies for my delay in responding.

I updated my code to use v1.19.0 of the Git changelog plugin and can confirm everything now renders correctly :tada:

However, if I apply the suggested tsconfig.json changes all other imports in my Vitepress config.ts break in my IDE but that's something I can deal with. We can consider the original issue resolved.

Thanks again for the awesome set of Vitepress plugins :star: