feat(v2): allow config plugins as functions or [function,options] #4618

samuelships · 2021-04-15T16:40:26Z

Motivation

This is an attempt ti fix #3934

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

netlify · 2021-04-15T17:01:50Z

[V2]

Built with commit 0c8e545

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

github-actions · 2021-04-15T17:02:06Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	66
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4618--docusaurus-2.netlify.app/

slorber

Thanks, that looks like a good start.

ESLint is not happy and report some lint errors to fix + added a few inline comments.

I find this code starts to be a bit hard to follow, do you think we could refactor it to something simpler? My idea is to follow this recommendation and avoid using "let" reassignments: https://charles-stover.medium.com/replacing-let-with-const-86797b790775

Also we need some doc for this here: https://docusaurus.io/docs/next/using-plugins#creating-plugins
I'd like this function plugin to be the highlighted way for users to create a plugin.

slorber · 2021-04-16T08:32:03Z

packages/docusaurus/src/server/__tests__/configValidation.test.ts

@@ -153,6 +139,16 @@ describe('normalizeConfig', () => {
        ['this/should/work', {too: 'yes'}],
      ],
    ],
+    [
+      'should accept function for plugin', [
+        function(context, params) {}


Suggested change

function(context, params) {}

function(_context, _options) {}

_ permits to make eslint happy if you don't need to use the param

options is used instead of params

packages/docusaurus/src/server/plugins/__tests__/__fixtures__/simple-site/docs/hello.md

packages/docusaurus/src/server/plugins/__tests__/__fixtures__/simple-site/docusaurus.config.js

packages/docusaurus/src/server/plugins/__tests__/index.test.ts

packages/docusaurus/src/server/__tests__/configValidation.test.ts

packages/docusaurus/src/server/plugins/__tests__/__fixtures__/simple-site/docusaurus.config.js

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

slorber

Thanks, that starts to look good.

Added a few comments + a commit to fix some issues on the PR

packages/docusaurus/package.json

slorber · 2021-04-20T13:58:10Z

packages/docusaurus/src/commands/swizzle.ts

-        break;
-      } else {
-        packagePath = path.dirname(packagePath);
+  return plugins


I have a hard time understanding what this code is doing 😅 can you explain your changes please?

The getPluginNames() function fetches all module plugins and gets its name through its package.json. This was working fine because the signature for PluginConfig used to be just [string, {}], [string] or string. Since I added functional plugin support, these don't have a package.json file so I'm filtering for only plugins which use a path.

I see thanks. Don't hesitate to add comments or try to create smaller functions with good names, so that the code becomes self-documented. I'm not sure I'll understand this code again in 6 months 😅

...s/docusaurus/src/server/plugins/__tests__/__fixtures__/site-with-plugin/docusaurus.config.js

slorber · 2021-04-20T14:00:07Z

packages/docusaurus/src/server/plugins/__tests__/__fixtures__/site-with-plugin/myPlugin.js

@@ -0,0 +1,5 @@
+module.exports = function (context, options) {
+    return {


we usually intend with 2 spaces, not sure why prettier does not complain about this

slorber · 2021-04-20T14:00:58Z

packages/docusaurus/src/server/plugins/__tests__/index.test.ts

+
+import path from 'path';
+
+import {loadContext} from '@docusaurus/core/src/server/index';


this is the other part of the issue: code from core should use relative imports, not code from @docusaurus/core that is the public API for other packages that depends on core

import {loadContext} from '../../index';

slorber · 2021-04-20T14:18:51Z

website/versioned_docs/version-2.0.0-alpha.72/using-plugins.md

+````js title="docusaurus.config.js"
+module.exports = {
+  // ...
+  plugins: [function(contex, options) {


Add some line-breaks here and. add // highlight-start and // highlight-end around the plugin function

slorber · 2021-04-20T14:19:09Z

website/versioned_docs/version-2.0.0-alpha.72/using-plugins.md

+    return {
+      name: 'my-docusaurus-plugin',
+      async loadContent() {
+        /* ... */


Suggested change

/* ... */

// ...

For consistency with the pattern used above?

slorber · 2021-04-20T14:19:27Z

website/versioned_docs/version-2.0.0-alpha.72/using-plugins.md

@@ -166,7 +190,7 @@ interface LoadContext {
  outDir: string;
  baseUrl: string;
 }
-```
+````


is this needed?

slorber · 2021-04-20T14:20:25Z

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

-      if (!pluginModuleImport) {
+      const pluginModuleImport = getPluginModuleImport();
+      const plugin = getPlugin();
+      pluginOptions = getPluginOptions();


why not const? I don't think options need reassignment

slorber · 2021-04-20T14:21:59Z

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

+        return null;
+      }
+
+      function getPluginModuleImport(): string | null {


Can you extract all those fns outside of initPlugins? I think it would help make the code more readable by passing the required data as function params (make the fn dependencies more explicit)

The functions being inside a function where they are only used was common in docusaurus-plugin-content-docs so I thought I would follow that pattern since these functions are not used anywhere else

This is not a big deal but splitting as much as possible into multiple pure functions makes the code more explicit, readable and testable.

Historically, most of the code of the docs plugin was directly inside index.test.ts, and I moved code outside of it progressively.

Do your best, I'll continue the refactor later if you don't find a solution to extract those methods, it's not high priority and shouldn't block merging this PR.

netlify · 2021-04-20T14:29:58Z

[V1]

Built with commit 0c8e545

https://deploy-preview-4618--docusaurus-1.netlify.app

slorber · 2021-04-21T14:39:51Z

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

+          return pluginItem;
+        }
+
+        return null;


Is this case actually possible (assuming we have a good validation?)

If it's not possible, then throw an error like throw new Error("Unexpected").

In general it's a good practice to fail-fast in case of unexpected met, like at the end/default of a switch/case or in the "else" branch of conditionals.

Didn't read but looks like a good article to illustrate the concept: https://levelup.gitconnected.com/switch-guard-in-typescript-how-to-make-sure-all-possible-cases-are-handled-19e86fd15797

# Conflicts: # yarn.lock

slorber · 2021-05-15T17:18:55Z

Thanks @besemuna , LGTM

Was able to cleanup the plugin init code, looks easier to understand now

samuelships added 3 commits April 15, 2021 15:55

feat : update PluginSchema validation

d90317e

feat : update plugin init functionality

1798afc

test : add and update tests

99a0a26

samuelships requested review from lex111 and slorber as code owners April 15, 2021 16:40

facebook-github-bot added the CLA Signed Signed Facebook CLA label Apr 15, 2021

fix : tests

9425229

slorber requested changes Apr 16, 2021

View reviewed changes

samuelships added 3 commits April 19, 2021 12:44

refactor : init.ts

af91ac9

test : update test

b48ec05

docs : add functional plugin docs

6367b2c

samuelships requested a review from slorber April 20, 2021 11:08

samuelships and others added 2 commits April 20, 2021 11:09

Merge branch 'master' into besemuna/iss3934

21b4b38

fix little issues

11b5e88

slorber requested changes Apr 20, 2021

View reviewed changes

refactor : refactor code

8b9b502

slorber changed the title ~~feat(v2) : passing a plain function as a plugin is ignored silently~~ feat(v2): allow config plugins as functions or [function,options] Apr 21, 2021

slorber reviewed Apr 21, 2021

View reviewed changes

slorber added 6 commits May 14, 2021 19:01

Merge branch 'master' into besemuna/iss3934

f7b5a56

# Conflicts: # yarn.lock

minor refactors

cf52a51

simplify initPlugins code

2ee1714

simplify initPlugin + add custom validation error message

b8d26ed

fix snapshots

4287cb3

improve function plugin doc

0c8e545

slorber merged commit 69be003 into facebook:master May 15, 2021

slorber added the pr: new feature This PR adds a new API or behavior. label May 15, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): allow config plugins as functions or [function,options] #4618

feat(v2): allow config plugins as functions or [function,options] #4618

samuelships commented Apr 15, 2021

netlify bot commented Apr 15, 2021 •

edited

github-actions bot commented Apr 15, 2021 •

edited

slorber left a comment

slorber Apr 16, 2021

slorber left a comment

slorber Apr 20, 2021

samuelships Apr 21, 2021

slorber Apr 21, 2021

slorber Apr 20, 2021

slorber Apr 20, 2021

slorber Apr 20, 2021

slorber Apr 20, 2021

slorber Apr 20, 2021

slorber Apr 20, 2021

slorber Apr 20, 2021

slorber Apr 20, 2021

samuelships Apr 21, 2021

samuelships Apr 21, 2021

slorber Apr 21, 2021

netlify bot commented Apr 20, 2021 •

edited

slorber Apr 21, 2021

slorber commented May 15, 2021

		@@ -0,0 +1,5 @@
		module.exports = function (context, options) {
		return {


		import path from 'path';

		import {loadContext} from '@docusaurus/core/src/server/index';

feat(v2): allow config plugins as functions or [function,options] #4618

feat(v2): allow config plugins as functions or [function,options] #4618

Conversation

samuelships commented Apr 15, 2021

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

netlify bot commented Apr 15, 2021 • edited

github-actions bot commented Apr 15, 2021 • edited

slorber left a 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

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

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

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

netlify bot commented Apr 20, 2021 • edited

Choose a reason for hiding this comment

slorber commented May 15, 2021

netlify bot commented Apr 15, 2021 •

edited

github-actions bot commented Apr 15, 2021 •

edited

netlify bot commented Apr 20, 2021 •

edited