search

AlchemyCMS / alchemy-guides

📜️ Source of the AlchemyCMS guidelines
https://guides.alchemy-cms.com
19 stars 46 forks source link

Update vuepress: 1.8.3 → 1.9.4 (minor) #161

Closed depfu[bot] closed 2 years ago

depfu[bot] commented 2 years ago

Here is everything you need to know about this update. Please take a good look at what changed and the test results before merging this pull request.

What changed?

✳️ vuepress (1.8.3 → 1.9.4) · Repo · Changelog

Release Notes

1.9.4 (from changelog)

Bug Fixes

Features

1.9.3 (from changelog)

Bug Fixes

1.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:

  • defineConfig
  • defineConfig4CustomTheme
  • defineTheme
  • definePlugin

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.

1.9.1 (from changelog)

Bug Fixes

  • types: support plain string usage for known third-party plugins (dd6e3ef) @chenhaoli

1.9.0

Overview

VuePress 1.9 introduced full TypeScript Support for Config File:

1 9-overview

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:

1 9-official-plugin-tuple-usage

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
      }
    ]
  ]
});

1 9-official-plugin-options

  • 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

1 9-lang

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

Does any of this look wrong? Please let us know.

Commits

See the full diff on Github. The new version differs by 40 commits:

Depfu Status

Depfu will automatically keep this PR conflict-free, as long as you don't add any commits to this branch yourself. You can also trigger a rebase manually by commenting with @depfu rebase.

All Depfu comment commands
@​depfu rebase
Rebases against your default branch and redoes this update
@​depfu recreate
Recreates this PR, overwriting any edits that you've made to it
@​depfu merge
Merges this PR once your tests are passing and conflicts are resolved
@​depfu close
Closes this PR and deletes the branch
@​depfu reopen
Restores the branch and reopens this PR (if it's closed)
@​depfu pause
Ignores all future updates for this dependency and closes this PR
@​depfu pause [minor|major]
Ignores all future minor/major updates for this dependency and closes this PR
@​depfu resume
Future versions of this dependency will create PRs again (leaves this PR as is)