feat(types): defineThemeEntry helper to infer type for theme entry

Author: ulivz

packages/@vuepress/theme-default/index.js

@@ -1,6 +1,8 @@
 const path = require('path')
 
-// Theme API.
+/**
+ * @type {import('@vuepress/types'.UserThemeEntry)}
+ */
 module.exports = (options, ctx) => {
  const { themeConfig, siteConfig } = ctx
 

packages/@vuepress/theme-default/package.json

@@ -24,6 +24,7 @@
  "@vuepress/plugin-active-header-links": "1.9.1",
  "@vuepress/plugin-nprogress": "1.9.1",
  "@vuepress/plugin-search": "1.9.1",
+ "@vuepress/types": "1.9.1",
  "docsearch.js": "^2.5.2",
  "lodash": "^4.17.15",
  "stylus": "^0.54.8",

packages/@vuepress/types/lib/config.ts

@@ -3,7 +3,8 @@ import { PostCssLoaderOptions } from "./style";
 import { MarkdownConfig } from "./markdown";
 import { LocaleConfig } from "./locale";
 import { ThemeConfig } from "./theme";
-import { PluginTuple, PluginObject } from "./plugin";
+import { Plugins } from "./plugin";
+import { Context } from "./context";
 
 /**
  * HTML tag name
@@ -123,7 +124,7 @@ export interface Config<T extends ThemeConfig> {
  *
  * @see https://vuepress.vuejs.org/config/#plugins
  */
- plugins?: PluginObject | Array<PluginTuple>;
+ plugins?: Plugins;
  /**
  * Markdown options.
  *
@@ -187,3 +188,10 @@ export interface Config<T extends ThemeConfig> {
  */
  evergreen?: boolean;
 }
+
+/**
+ * Expose `VuePress` config with function support
+ */
+export type UserConfig<T extends ThemeConfig> =
+ | Config<T>
+ | ((ctx: Context<T, Config<T>>) => Config<T>);

packages/@vuepress/types/lib/context.ts

@@ -1,3 +1,6 @@
+import { ThemeConfig } from "./theme";
+import { Config } from "./config";
+
 /**
  * Page instance.
  *
@@ -24,7 +27,10 @@ export interface Page {
  *
  * @see https://vuepress.vuejs.org/plugin/context-api.html
  */
-export interface Context {
+export interface Context<
+T extends ThemeConfig = ThemeConfig,
+C extends Config<T> = Config<ThemeConfig>
+> {
  /**
  * Whether VuePress run in production environment mode.
  */
@@ -53,4 +59,12 @@ export interface Context {
  * A utility for writing temporary files to tempPath.
  */
  writeTemp(filename: string, content: string): Promise<void>;
+ /**
+ * Current theme config.
+ */
+ themeConfig: T;
+ /**
+ * VuePress Config.
+ */
+ siteConfig: C;
 }

packages/@vuepress/types/lib/index.ts

@@ -4,3 +4,4 @@ export * from './markdown'
 export * from './style'
 export * from './context'
 export * from './theme-default'
+export * from './theme'

packages/@vuepress/types/lib/plugin-api.ts

@@ -63,3 +63,9 @@ export type PluginObject = Partial<PluginConfigMap>
  [k: string]: Record<string, any>;
  }
 
+/**
+ * Specify plugins.
+ *
+ * @see https://vuepress.vuejs.org/config/#plugins
+ */
+export type Plugins= PluginObject | Array<PluginTuple>;

packages/@vuepress/types/lib/plugin.ts

@@ -1,4 +1,55 @@
+import { Plugins } from "./plugin";
+import { Context } from "./context";
+import { Config } from "./config";
+
 /**
  * Default theme config type
  */
 export type ThemeConfig = any;
+
+/**
+ * Export type of theme entry
+ *
+ * @see https://vuepress.vuejs.org/theme/option-api.html
+ */
+export type ThemeEntry = {
+ /**
+ * plugins
+ */
+ plugins?: Plugins;
+ /**
+ * HTML template path used in dev mode.
+ *
+ * @default https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/client/index.dev.html
+ * @see https://vuepress.vuejs.org/theme/option-api.html#devtemplate
+ */
+ devTemplate?: string;
+ /**
+ * HTML template path used in build mode
+ *
+ * @default https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/client/index.ssr.html
+ * @see https://vuepress.vuejs.org/theme/option-api.html#ssrtemplate
+ */
+ ssrTemplate?: string;
+ /**
+ * Extends a theme
+ *
+ * @see https://vuepress.vuejs.org/theme/option-api.html#extend
+ */
+ extend?: string;
+ /**
+ * Global layout component is a component responsible for the global layout strategy.
+ *
+ * @see https://vuepress.vuejs.org/theme/option-api.html#globallayout
+ */
+ globalLayout?: string;
+};
+
+/**
+ * Export type of theme entry with function support
+ *
+ * @see https://vuepress.vuejs.org/theme/option-api.html
+ */
+export type UserThemeEntry<T extends ThemeConfig = ThemeConfig> =
+ | ThemeEntry
+ | ((themeConfig: T, ctx: Context<T, Config<T>>) => ThemeEntry);

packages/@vuepress/types/lib/theme.ts

@@ -1,15 +1,31 @@
-import { Context, Config, ThemeConfig, DefaultThemeConfig } from '@vuepress/types'
+import {
+ UserConfig,
+ ThemeConfig,
+ DefaultThemeConfig,
+ ThemeEntry
+} from '@vuepress/types'
 
 export * from '@vuepress/types'
 
-export type UserConfig<T extends ThemeConfig> =
- | Config<T>
- | ((ctx: Context) => Config<T>);
-
 /**
- * Helper for type prompt and type checking.
+ * A helper function to define VuePress config file.
+ *
+ * @see https://vuepress.vuejs.org/config/
  */
 export function defineConfig(config: UserConfig<DefaultThemeConfig>): void;
+
+/**
+ * A helper function to define VuePress config file, for custom theme.
+ *
+ * @see https://vuepress.vuejs.org/config/
+ */
 export function defineConfig4CustomTheme<T extends ThemeConfig = ThemeConfig>(
  config: UserConfig<T>
 ): void;
+
+/**
+ * A helper function to define VuePress theme entry file.
+ *
+ * @see https://vuepress.vuejs.org/theme/option-api.html
+ */
+export function defineThemeEntry(config: ThemeEntry): void;

packages/vuepress/config.d.ts

@@ -1,6 +1,6 @@
-exports.defineConfig = function (config) {
- return config
-}
-exports.defineConfig4CustomTheme = function (config) {
- return config
+function define (config) {
+ config
 }
+exports.defineConfig = define
+exports.defineConfig4CustomTheme = define
+exports.defineThemeEntry = define