feat(v2): option and config validation life cycle method for official plugins #2943

anshulrgoyal · 2020-06-16T11:42:08Z

Motivation

All the plugins don't validate and normalize options. It tries to generalize option validation and normalization.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

By adding tests for different plugins validation and normalization.

docusaurus-bot · 2020-06-16T11:45:31Z

Deploy preview for docusaurus-2 ready!

Built with commit 408d871

https://deploy-preview-2943--docusaurus-2.netlify.app

packages/docusaurus-plugin-content-blog/src/index.ts

slorber

That looks like a great start!

packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts

packages/docusaurus-plugin-content-blog/src/__tests__/validation.test.ts

slorber · 2020-06-19T12:59:30Z

packages/docusaurus-plugin-content-blog/src/index.ts

-
-const getFeedTypes = (type?: FeedType) => {
-  assertFeedTypes(type);
+const getFeedTypes = (type: FeedType) => {
  let feedTypes: ('rss' | 'atom')[] = [];


Omit<FeedType,"all"> would be more future proof. Wonder if we shouldn't simply remove this "all" from the type, as it's somehow a "shortcut"

packages/docusaurus-theme-classic/src/index.js

packages/docusaurus-types/src/index.d.ts

packages/docusaurus-plugin-content-blog/src/types.ts

packages/docusaurus/src/server/plugins/init.ts

slorber · 2020-06-19T13:24:25Z

packages/docusaurus-theme-classic/src/index.js

+
+module.exports.validateThemeConfig = ({validate, themeConfig}) => {
+  return validate(ThemeConfigSchema, themeConfig);
+};


this assigns the validateThemeConfig to the default exported plugin function.

I'm not very fan of this idea, but this is a bit subjective (api design choices).

I think we have 2 cases here:

compiled plugins (ie in this repo, the ones in TS), where we can use ES imports/exports

"raw" plugins (like this one, and maybe the ones the user will write), for which we can't use ES imports/exports, otherwise we wouldn't support older nodejs versions

What about exporting these static methods directly?

=> export function validateThemeConfig() {};

=> exports.validateThemeConfig = function() {};

It could even be possible to support both syntaxes 🤪 wonder the one we should recommend to the users

slorber

That seems nice, just a few things to discuss/change before merging ;)

packages/docusaurus-plugin-content-blog/src/__tests__/validation.test.ts

packages/docusaurus-plugin-content-blog/src/index.ts

packages/docusaurus-theme-classic/src/index.js

packages/docusaurus/src/server/plugins/init.ts

packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts

packages/docusaurus/src/server/plugins/init.ts

slorber

LGTM

Just 2 things left:

Support modern ES syntax
Some documentation

packages/docusaurus-plugin-content-blog/src/validation.ts

slorber · 2020-06-23T17:05:15Z

packages/docusaurus/src/server/plugins/init.ts

+          themeConfig: context.siteConfig.themeConfig,
+        });
+      }
+      return plugin(context, pluginOptions);


I think we should support plain ES export syntax here:

export function validateThemeConfig() { }

It does not look like it would work.

We'd need something like:

const validateOptions = pluginModule.default?. validateOptions ?? pluginModule.validateOptions; if ( validateOptions ) { ... }

For both plugins and themes.

We could even migrate the existing plugin to ES as well.

Note: we are recommending node >= 10 (not supporting ES imports), so only the TS/transpiled plugins can be migrated.

We should rather document both syntaxes. ES is more modern, but requires newest node versions of 12/14, while Common-js would work as well on older node versions.

For documentation, I will add lifecycle methods to docs. And for import, I think we can support both.

slorber · 2020-06-24T18:08:41Z

awesome, let's finally merge this!

slorber · 2020-07-30T16:32:40Z

packages/docusaurus-plugin-content-blog/src/validation.ts

+export const DefaultOptions = {
+  feedOptions: {},
+  beforeDefaultRehypePlugins: [],
+  beforeDefaultRemarkPlugins: [],


Hey, are these options a typo?

That looks like, please confirm so that I can remove in my current pr

ah no it seems used in practice

I copied it from docs.https://v2.docusaurus.io/docs/using-plugins/#docusaurusplugin-content-blog

beforeDefaultRemarkPlugins: [], beforeDefaultRehypePlugins: [], feedOptions: { type: '', // required. 'rss' | 'feed' | 'all' title: '', // default to siteConfig.title description: '', // default to `${siteConfig.title} Blog` copyright: '', language: undefined, // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes },

ah no it seems used in practice

Sorry I didn't understand what u mean.

nevermind I thought it was not used but it is

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 16, 2020

slorber reviewed Jun 16, 2020

View reviewed changes

packages/docusaurus-plugin-content-blog/src/index.ts Outdated Show resolved Hide resolved

anshulrgoyal requested a review from slorber June 17, 2020 11:43

anshulrgoyal closed this Jun 17, 2020

anshulrgoyal force-pushed the anshul/validation branch from 9cedb64 to 68a1bb1 Compare June 17, 2020 12:31

add validation for blog plugin

72edfba

anshulrgoyal reopened this Jun 17, 2020

anshul added 3 commits June 17, 2020 18:56

fix wrong default component

a420243

fix test and add yup to package.json

51d7b99

remove console.log

96b90f6

anshulrgoyal marked this pull request as ready for review June 17, 2020 15:23

anshulrgoyal requested a review from yangshun as a code owner June 17, 2020 15:23

anshul added 3 commits June 18, 2020 12:11

add validation for classic theme and code block theme

4c02942

add yup to packages

a53abb7

remove console.log

48a53bb

anshulrgoyal requested a review from lex111 as a code owner June 18, 2020 06:47

anshul added 2 commits June 18, 2020 12:41

fix build

492f912

fix logo required

740f288

slorber reviewed Jun 19, 2020

View reviewed changes

teikjun mentioned this pull request Jun 19, 2020

feat(v2): add option validation for remaining official plugins #2970

Merged

anshul and others added 9 commits June 19, 2020 20:00

replaced yup with joi

c5746de

fix test

cdffb96

remove hapi from docusuars core

f04aa61

replace joi with @hapi/joi

3d9f2c8

Merge branch 'master' into anshul/validation

aedd58a

fix eslint

3205979

Merge branch 'master' into anshul/validation

d099a83

fix remark plugin type

f024462

change remark plugin validation to match documentation

f5cf736

anshulrgoyal requested a review from slorber June 22, 2020 08:36

slorber requested changes Jun 22, 2020

View reviewed changes

move schema to it's own file

0d60418

anshulrgoyal requested a review from slorber June 22, 2020 13:29

anshul added 4 commits June 22, 2020 21:46

allow unknown only on outer theme object

e7802f6

fix type for schema type

18e754e

resolve conflict

962c98f

fix yarn.lock

bf22c67

slorber requested changes Jun 23, 2020

View reviewed changes

anshul added 2 commits June 23, 2020 23:05

support both commonjs and ES modules

c213008

add docs for new lifecycle method

408d871

anshulrgoyal requested a review from slorber June 24, 2020 05:13

slorber merged commit 81d8553 into facebook:master Jun 24, 2020

slorber added the pr: new feature This PR adds a new API or behavior. label Jun 24, 2020

slorber reviewed Jul 30, 2020

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): option and config validation life cycle method for official plugins #2943

feat(v2): option and config validation life cycle method for official plugins #2943

anshulrgoyal commented Jun 16, 2020

docusaurus-bot commented Jun 16, 2020 •

edited

Loading

slorber left a comment

slorber Jun 19, 2020

slorber Jun 19, 2020

slorber left a comment

slorber left a comment

slorber Jun 23, 2020

anshulrgoyal Jun 23, 2020

slorber commented Jun 24, 2020

slorber Jul 30, 2020

slorber Jul 30, 2020

anshulrgoyal Jul 30, 2020

anshulrgoyal Jul 30, 2020

slorber Jul 30, 2020

feat(v2): option and config validation life cycle method for official plugins #2943

feat(v2): option and config validation life cycle method for official plugins #2943

Conversation

anshulrgoyal commented Jun 16, 2020

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

docusaurus-bot commented Jun 16, 2020 • edited Loading

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber commented Jun 24, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

docusaurus-bot commented Jun 16, 2020 •

edited

Loading