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