Releases: vuejs/vuepress
v1.9.10
v1.9.2
TS Support for VuePress Plugin and Theme.
Motivation
We've announced VuePress 1.9 that takes full TypeScript Support for Config File, while VuePress 1.9.2 ships with TS Support for VuePress Plugin and Theme:
Quick Start
In order to make the plugin developer not dependent on VuePress for development, we provide a completely independent type package @vuepress/types:
npm i @vuepress/types -D@vuepress/types exports four functions:
defineConfigdefineConfig4CustomThemedefineThemedefinePlugin
Note that using @vuepress/types is equivalent to using vuepress/config.
Plugin Type
If you already have some VuePress plugins written in JS, you can leverage your IDE's intellisense with jsdoc type hints:
/**
* @type {import('@vuepress/types').Plugin}
*/
module.exports = {
ready() {
// ...
}
};Alternatively, you can use the defineConfig helper which should provide intellisense without the need for jsdoc annotations:
import { definePlugin } from "@vuepress/types";
export default definePlugin({
// ...
});Plugin Options Type
Type of plugin options also supports passing in through generic type:
import { definePlugin } from "@vuepress/types";
interface Options {
name: string;
}
export default definePlugin<Options>((options, ctx) => {
return {
ready() {
return ctx.base + options.name;
}
};
});Theme Type
Similar to plugin, the only difference is the type you use, and the define function:
/**
- * @type {import('@vuepress/types').Plugin}
+ * @type {import('@vuepress/types').Theme}
*/-import { definePlugin } from "@vuepress/types";
+import { defineTheme } from "@vuepress/types";
-export default definePlugin({
+export default defineTheme({
// ...
});Theme Config Type
Type of theme config also supports passing in through generic type:
import { defineTheme } from "@vuepress/types";
interface ThemeConfig {
lang: string;
}
export default defineTheme<ThemeConfig>((themeConfig, ctx) => {
return {
ready() {
return ctx.base + themeConfig.lang;
}
};
});Notes
It is worth noting that, unlike the site configuration, i.e. .vuepress/config.js, if you use TypeScript to write theme or plugin, you still need to compile it into JavaScript before publishing it to NPM.
v1.9.0
TypeScript Support for Config File
Overview
VuePress 1.9 introduced full TypeScript Support for Config File, for VuePress 1.x, this is a late key feature:
Features
Support .vuepress/config.ts
Previously, VuePress only supported these configurations
.vuepress/config.js.vuepress/config.yml.vuepress/config.toml
From now on, .vuepress/config.ts get officially supported.
defineConfig helper for config intellisense
A helper function exposed at vuepress/config, which helps you to have type prompt:
import { defineConfig } from "vuepress/config";
export default defineConfig({
title: "VuePress",
description: "Vue-powered Static Site Generator"
// ...
});Type Inferences for Theme
By default, defineConfig helper leverages type of Default Theme Config as themeConfig, i.e, type hints for all Default Theme Config is available for now.
import { defineConfig } from "vuepress/config";
export default defineConfig({
themeConfig: {
repo: "vuejs/vuepress",
editLinks: true,
docsDir: "packages/docs/docs"
// Type is `DefaultThemeConfig`
}
});If you use a custom theme, you can use the defineConfig4CustomTheme helper with ability to pass generic type for your theme:
import { defineConfig4CustomTheme } from "vuepress/config";
interface MyThemeConfig {
hello: string;
}
export default defineConfig4CustomTheme<MyThemeConfig>({
themeConfig: {
// Type is `MyThemeConfig`
hello: "vuepress"
}
});Type Inferences for Official Plugins
From now, you’ll be able to enjoy the type prompt of the official plugins:
Options of the official plugins certainly have type prompts, Both Tuple Style, Object Style, and Plugin Shorthand support type inference:
- Tuple Style:
import { defineConfig } from "vuepress/config";
export default defineConfig({
plugins: [
[
"@vuepress/pwa",
{
serviceWorker: true
}
]
]
});
- Object Style:
import { defineConfig } from "vuepress/config";
export default defineConfig({
plugins: {
"@vuepress/pwa": {
serviceWorker: true
}
}
});The illustration snapshot is omitted here, you can try it yourself.
ISO Language Code
Type inference supports ISO Language Code
Context API
VuePress’s configuration can also be a function, while its first parameter is the current app context:
import { defineConfig } from "vuepress/config";
export default defineConfig(ctx => ({
// do not execute babel compilation under development
evergreen: ctx.isProd
}));Limitations
It is worth noting that third-party plugins do not support Plugin Shorthand if you’re using Tuple Style to write your config, this is because from the perspective of the type system, the unknown shortcut is equivalent to string, which results in the failure of type inference.
By default, only officially maintained and plugins under VuePress Community support shortcut, feel free to submit pull request to add your plugin at this file.
Credits
- bundle-require (by @egoist): we leverage it under the hood to resolve user's config, which is powered by
esbuild. - vscode-ts-in-markdown (by @Amour1688): this documentation is powered by this plugin, which makes type checking possible in markdown.
v1.8.3
v1.8.2
v1.8.1
Bug Fixes
v1.8.0
Bug Fixes
- $plugin-google-analytics: report site base (#2687) (close #2169) (6bbcc69)
- $shared-utils: improve title inference and header extraction for markdown links syntax (d264e50)
- $theme-default: display header-anchor links when using keyboard navigation (#2699) (81cce39)
- Only empty the
.tempdirectory at most once per run (fix #2254) (#2612) (970b434)