đź“ť Minimalistic Vue-powered static site generator
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:
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:
defineConfig
defineConfig4CustomTheme
defineTheme
definePlugin
Note that using @vuepress/types
is equivalent to using vuepress/config
.
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({
// ...
});
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;
}
};
});
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({
// ...
});
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;
}
};
});
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.
VuePress 1.9 introduced full TypeScript Support for Config File, for VuePress 1.x, this is a late key feature:
.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 intellisenseA 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"
// ...
});
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"
}
});
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:
import { defineConfig } from "vuepress/config";
export default defineConfig({
plugins: [
[
"@vuepress/pwa",
{
serviceWorker: true
}
]
]
});
import { defineConfig } from "vuepress/config";
export default defineConfig({
plugins: {
"@vuepress/pwa": {
serviceWorker: true
}
}
});
The illustration snapshot is omitted here, you can try it yourself.
Type inference supports ISO Language Code
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
}));
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.
esbuild
..temp
directory at most once per run (fix #2254) (#2612) (970b434)