feat(v2): option and config validation life cycle method for official plugins #2943
Conversation
|
Deploy preview for docusaurus-2 ready! Built with commit 408d871 |
anshulrgoyal
force-pushed
the
anshul/validation
branch
from
9cedb64
to
68a1bb1
Compare
packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts
Outdated
Show resolved
Hide resolved
packages/docusaurus-plugin-content-blog/src/__tests__/validation.test.ts
Outdated
Show resolved
Hide resolved
packages/docusaurus-plugin-content-blog/src/__tests__/validation.test.ts
Outdated
Show resolved
Hide resolved
|
|
||
| const getFeedTypes = (type?: FeedType) => { | ||
| assertFeedTypes(type); | ||
| const getFeedTypes = (type: FeedType) => { | ||
| let feedTypes: ('rss' | 'atom')[] = []; |
There was a problem hiding this comment.
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"
|
|
||
| module.exports.validateThemeConfig = ({validate, themeConfig}) => { | ||
| return validate(ThemeConfigSchema, themeConfig); | ||
| }; |
There was a problem hiding this comment.
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
packages/docusaurus-plugin-content-blog/src/__tests__/validation.test.ts
Show resolved
Hide resolved
| themeConfig: context.siteConfig.themeConfig, | ||
| }); | ||
| } | ||
| return plugin(context, pluginOptions); |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
For documentation, I will add lifecycle methods to docs. And for import, I think we can support both.
|
awesome, let's finally merge this! |
| export const DefaultOptions = { | ||
| feedOptions: {}, | ||
| beforeDefaultRehypePlugins: [], | ||
| beforeDefaultRemarkPlugins: [], |
There was a problem hiding this comment.
Hey, are these options a typo?
That looks like, please confirm so that I can remove in my current pr
There was a problem hiding this comment.
ah no it seems used in practice
There was a problem hiding this comment.
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
},
There was a problem hiding this comment.
ah no it seems used in practice
Sorry I didn't understand what u mean.
There was a problem hiding this comment.
nevermind I thought it was not used but it is
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.