vuejs · posva · Jun 25, 2024 · Jun 25, 2024 · Jun 25, 2024 · Jun 26, 2024
diff --git a/.gitignore b/.gitignore
@@ -17,3 +17,4 @@ local.log
 _selenium-server.log
 packages/*/LICENSE
 tracing_output
+tsconfig.vitest-temp.json
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@vue/router-root",
   "private": true,
-  "packageManager": "pnpm@9.10.0",
+  "packageManager": "pnpm@10.13.1",
   "type": "module",
   "engines": {
     "node": ">=20.9.0"
@@ -36,17 +36,17 @@
     "brotli": "^1.3.3",
     "chalk": "^5.4.1",
     "enquirer": "^2.4.1",
-    "execa": "^9.5.2",
+    "execa": "^9.6.0",
     "globby": "^14.1.0",
     "lint-staged": "^15.5.1",
     "minimist": "^1.2.8",
     "p-series": "^3.0.0",
     "prettier": "^3.5.3",
     "semver": "^7.7.1",
     "simple-git-hooks": "^2.13.0",
-    "typedoc": "^0.26.11",
-    "typedoc-plugin-markdown": "^4.2.10",
-    "typescript": "~5.6.3",
+    "typedoc": "^0.28.7",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "~5.8.3",
     "vitest": "^2.1.9"
   },
   "simple-git-hooks": {
@@ -71,7 +71,12 @@
         "@types/react",
         "react-dom"
       ]
-    }
+    },
+    "onlyBuiltDependencies": [
+      "chromedriver",
+      "esbuild",
+      "geckodriver"
+    ]
   },
   "volta": {
     "node": "20.11.1"

diff --git a/packages/docs/.gitignore b/packages/docs/.gitignore
@@ -1 +1,2 @@
 .vitepress/cache
+api
diff --git a/packages/docs/.vitepress/config/en.ts b/packages/docs/.vitepress/config/en.ts
@@ -1,4 +1,5 @@
 import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+import typedocSidebar from '../../api/typedoc-sidebar.json'
 
 export const META_URL = 'https://router.vuejs.org'
 export const META_TITLE = 'Vue Router'
@@ -53,6 +54,12 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
     ],
 
     sidebar: {
+      '/api/': [
+        {
+          text: 'API',
+          items: typedocSidebar,
+        },
+      ],
       // catch-all fallback
       '/': [
         {
@@ -179,13 +186,6 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           ],
         },
       ],
-
-      '/api/': [
-        {
-          text: 'packages',
-          items: [{ text: 'vue-router', link: '/api/' }],
-        },
-      ],
     },
   },
 }
diff --git a/packages/docs/.vitepress/config/zh.ts b/packages/docs/.vitepress/config/zh.ts
@@ -1,4 +1,6 @@
 import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+import typedocSidebar from '../../api/typedoc-sidebar.json'
+// TODO: rework the typedoc sidebar to include the /zh/ prefix
 
 export const META_URL = 'https://router.vuejs.org'
 export const META_TITLE = 'Vue Router'
@@ -57,6 +59,12 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
     ],
 
     sidebar: {
+      '/zh/api/': [
+        {
+          text: 'API',
+          items: typedocSidebar,
+        },
+      ],
       '/zh/': [
         {
           text: '设置',
@@ -186,13 +194,6 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           ],
         },
       ],
-
-      '/zh/api/': [
-        {
-          text: 'packages',
-          items: [{ text: 'vue-router', link: '/zh/api/' }],
-        },
-      ],
     },
   },
 }

diff --git a/packages/docs/package.json b/packages/docs/package.json
@@ -13,9 +13,10 @@
     "docs:preview": "vitepress preview ."
   },
   "dependencies": {
-    "simple-git": "^3.27.0",
-    "vitepress": "1.5.0",
-    "vitepress-translation-helper": "^0.2.1",
+    "simple-git": "^3.28.0",
+    "typedoc-vitepress-theme": "^1.1.2",
+    "vitepress": "1.6.3",
+    "vitepress-translation-helper": "^0.2.2",
     "vue-router": "workspace:*"
   }
 }
diff --git a/packages/docs/run-typedoc.mjs b/packages/docs/run-typedoc.mjs
@@ -1,15 +1,21 @@
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { createTypeDocApp } from './typedoc-markdown.mjs'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
 createTypeDocApp({
-  name: 'API Documentation',
+  textContentMappings: {
+    'title.indexPage': 'API Reference',
+    'title.memberPage': '{name}',
+  },
   tsconfig: path.resolve(__dirname, './typedoc.tsconfig.json'),
+  // entryPointStrategy: 'packages',
   categorizeByGroup: true,
   githubPages: false,
-  disableSources: true, // some links are in node_modules and it's ugly
-  plugin: ['typedoc-plugin-markdown'],
+  readme: 'none',
+  indexFormat: 'table',
+  disableSources: true,
+  plugin: ['typedoc-plugin-markdown', 'typedoc-vitepress-theme'],
+  useCodeBlocks: true,
   entryPoints: [path.resolve(__dirname, '../router/src/index.ts')],
 }).then(app => app.build())
diff --git a/packages/docs/typedoc-markdown.mjs b/packages/docs/typedoc-markdown.mjs
@@ -2,12 +2,12 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { Application, PageEvent, TSConfigReader } from 'typedoc'
+import { Application, TSConfigReader, PageEvent } from 'typedoc'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
+/** @satisfies {Partial<import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions>} */
 const DEFAULT_OPTIONS = {
-  // disableOutputCheck: true,
   cleanOutputDir: true,
   excludeInternal: false,
   readme: 'none',
@@ -72,7 +72,7 @@ export async function createTypeDocApp(config = {}) {
     if (project) {
       // Rendered docs
       try {
-        await app.generateDocs(project, options.out)
+        await app.generateOutputs(project)
         app.logger.info(`generated at ${options.out}.`)
       } catch (error) {
         app.logger.error(error)
@@ -88,6 +88,12 @@ export async function createTypeDocApp(config = {}) {
   }
 }
 
+/**
+ * checks if a path exists
+ *
+ * @async
+ * @param {string} path
+ */
 async function exists(path) {
   try {
     await fs.access(path)
@@ -108,7 +114,7 @@ async function exists(path) {
  */
 function prependYAML(contents, vars) {
   return contents
-    .replace(/^/, `${toYAML(vars)}\n\n`)
+    .replace(/^/, toYAML(vars) + '\n\n')
     .replace(/[\r\n]{3,}/g, '\n\n')
 }
 

diff --git a/packages/docs/typedoc.tsconfig.json b/packages/docs/typedoc.tsconfig.json
@@ -31,6 +31,6 @@
     "removeComments": false,
     "jsx": "preserve",
     "lib": ["esnext", "dom"],
-    "types": ["node"]
+    "types": ["vitest", "node", "vite/client"]
   }
 }
diff --git a/packages/experiments-playground/.gitignore b/packages/experiments-playground/.gitignore
@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.DS_Store
+dist
+dist-ssr
+coverage
+*.local
+
+/cypress/videos/
+/cypress/screenshots/
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+*.tsbuildinfo
diff --git a/packages/experiments-playground/.vscode/extensions.json b/packages/experiments-playground/.vscode/extensions.json
@@ -0,0 +1,3 @@
+{
+  "recommendations": ["Vue.volar"]
+}
diff --git a/packages/experiments-playground/README.md b/packages/experiments-playground/README.md
@@ -0,0 +1,33 @@
+# experiments-playground
+
+This template should help get you started developing with Vue 3 in Vite.
+
+## Recommended IDE Setup
+
+[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+
+## Type Support for `.vue` Imports in TS
+
+TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
+
+## Customize configuration
+
+See [Vite Configuration Reference](https://vite.dev/config/).
+
+## Project Setup
+
+```sh
+pnpm install
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+pnpm dev
+```
+
+### Type-Check, Compile and Minify for Production
+
+```sh
+pnpm build
+```
diff --git a/packages/experiments-playground/env.d.ts b/packages/experiments-playground/env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/packages/experiments-playground/index.html b/packages/experiments-playground/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/packages/experiments-playground/package.json b/packages/experiments-playground/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "experiments-playground",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "preview": "vite preview",
+    "build-only": "vite build",
+    "type-check": "vue-tsc --build"
+  },
+  "dependencies": {
+    "vue": "^3.5.17",
+    "vue-router": "workspace:*"
+  },
+  "devDependencies": {
+    "@tsconfig/node22": "^22.0.2",
+    "@types/node": "^22.15.32",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "@vue/tsconfig": "^0.7.0",
+    "npm-run-all2": "^8.0.4",
+    "typescript": "~5.8.0",
+    "vite": "^7.0.0",
+    "vite-plugin-vue-devtools": "^7.7.7",
+    "vue-tsc": "^2.2.10"
+  }
+}