feat: shorthands for themes/plugins/presets configuration #5930

fsmaia · 2021-11-11T17:04:30Z

Motivation

See #5883

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Run manually, packing with npm pack, and installing in a custom docusaurus.config.js
Post the screenshot here
Include this scenario in the test file (init.test.ts), figuring out a way to mock require.resolve (as it won't be physically installed), or then add a demo plugin in the fixture package.json file)

netlify · 2021-11-11T17:11:03Z

✔️ [V2]

🔨 Explore the source changes: ddd3385

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61aa4e160eaabc0007784aa3

😎 Browse the preview: https://deploy-preview-5930--docusaurus-2.netlify.app

github-actions · 2021-11-11T17:11:15Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	91
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

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

fsmaia · 2021-11-11T18:29:34Z

I indexed plugins by type to identify plugin and theme aliases. This affected loadPluginConfigs.

Josh-Cena

Thanks, looks cool

A little POC using our own website will help us see if it's working

packages/docusaurus/src/commands/swizzle.ts

fsmaia · 2021-11-13T18:48:07Z

Thanks, looks cool

A little POC using our own website will help us see if it's working

Actually in the next commit I'll apply this same engine for presets, and I thought about using the examples folder to use the shorthands.

I really care about automated tests, but emulating a Node package resolve is very complex, and I would end up mocking too much and the test would practically be a snapshot over the resolve attempts (asserting mapping a string with some prefixes).

Josh-Cena · 2021-11-14T00:30:01Z

Hmm, just replacing all the names in our docusaurus.config.js is fine

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

fsmaia · 2021-11-14T21:37:00Z

Hmm, just replacing all the names in our docusaurus.config.js is fine

Do you think that the preset part should be applied in a separate PR?

By that I mean accepting, for instance, classic instead of @docusaurus/preset-classic. Btw it's the exact same code (adding a loadPresetModule and a resolvePresetModule).

Josh-Cena · 2021-11-14T23:14:07Z

Do you think that the preset part should be applied in a separate PR?

Yes—I haven't reviewed the impl in detail, but I think it would be trivial to add and weird to not

fsmaia · 2021-11-16T21:02:34Z

I preferred to add this resolver to presets too, as the title/issue already suggests it, and updated it in the examples folder.

It is still working fine:

fsmaia · 2021-11-16T22:54:17Z

Example when an invalid preset/plugin is provided:

examples/classic-typescript/package.json

fsmaia · 2021-11-17T16:21:44Z

Just executed with another project and the theme resolution is working now.

fsmaia · 2021-11-19T08:08:51Z

@Josh-Cena, could you help me identifying why the E2E didn't work?

Josh-Cena · 2021-11-19T09:06:49Z

This is a known problem that I fixed in #5958. Don't worry @fsmaia this will be solved after that one gets merged.

Josh-Cena · 2021-11-27T06:49:36Z

Hey @fsmaia FYI your approach didn't work well with swizzling because of how our swizzling script tries to resolve theme names through the config. To simplify things (I may revisit that script in the future, the setup looks convoluted) I refactored your code to resolve the module names directly after loading the plugin config. The diff also looks much cleaner this way.

fsmaia · 2021-11-29T13:38:22Z

Amazing! Big thanks!

slorber

thanks, LGTM, just did some little modifications

slorber · 2021-12-03T16:36:19Z

packages/docusaurus/src/server/moduleShorthand.ts

+  // eslint-disable-next-line no-restricted-syntax
+  for (const module of modulePatterns) {
+    try {
+      moduleRequire.resolve(module);


ok for that.

Throwing exceptions has a runtime cost, but it's probably not very important here.
I don't know if there's a fail-safe way to resolve a module in nodejs but if there is one, that would be preferable.

slorber · 2021-12-03T16:47:32Z

website/_dogfooding/dogfooding.config.js

@@ -24,7 +24,7 @@ const dogfoodingPluginInstances = [
  ],

  [
-    '@docusaurus/plugin-content-blog',


going to dogfood other forms of plugin names here, it's the purpose of dogfooding to have a variety of settings ;)

slorber · 2021-12-03T16:51:16Z

website/docs/configuration.md

+| --- | --- |
+| `awesome` | `docusaurus-plugin-awesome` |
+| `sitemap` | [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) |
+| `@joshcena` | `@joshcena/docusaurus-plugin` (the only possible resolution!) |


replacing with @mycompany which is more likely to happen and less confusing for docs readers

slorber · 2021-12-03T16:54:35Z

website/docs/configuration.md

@@ -66,15 +125,15 @@ module.exports = {
  // ...
  plugins: [
    [
-      '@docusaurus/plugin-content-blog',


just thinking out loud but maybe we'll want in a future to just be able to use "blog"?

The "content-blog" thing is a bit weird for the users IMHO

Quite similarly I'm not fan of the complexity of our i18n paths, I wish we could just have i18n/fr/blog

slorber · 2021-12-03T17:05:15Z

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

+    ).toThrowErrorMatchingInlineSnapshot(`
+      "Docusaurus was unable to resolve the \\"@docusaurus/plugin-content-doc\\" plugin. Make sure one of the following packages are installed:
+      - @docusaurus/plugin-content-doc
+      - @docusaurus/docusaurus-plugin-plugin-content-doc"


nit: added this test, but this resolve name looks a bit weird.

I'll still merge, but if you feel we should do something about it 🤷‍♂️ feel free to open another PR

facebook/docusaurus#5456 facebook/docusaurus#5589 facebook/docusaurus#5930

facebook/docusaurus#4968 facebook/docusaurus#5456 facebook/docusaurus#5589 facebook/docusaurus#5930

feat(plugins): Add aliases resolver for plugins

f2ee7af

fsmaia requested review from lex111 and slorber as code owners November 11, 2021 17:04

facebook-github-bot added the CLA Signed Signed Facebook CLA label Nov 11, 2021

fsmaia added 2 commits November 11, 2021 16:04

refactor: add PluginConfigs to index plugins by type (plugin or theme)

513b9fa

refactor: add PluginConfigs to index plugins by type (plugin or theme)

bf9d2af

Josh-Cena reviewed Nov 11, 2021

View reviewed changes

packages/docusaurus/src/commands/swizzle.ts Outdated Show resolved Hide resolved

Josh-Cena changed the title ~~Support shorthand for themes/plugins/presets configuration~~ feat: shorthands for themes/plugins/presets configuration Nov 12, 2021

Josh-Cena added the pr: new feature This PR adds a new API or behavior. label Nov 12, 2021

chore: hide implementation detail from the variable name

adb095e

armano2 reviewed Nov 14, 2021

View reviewed changes

packages/docusaurus/src/server/plugins/init.ts Outdated Show resolved Hide resolved

fsmaia added 2 commits November 16, 2021 17:57

feat(presets): Add aliases resolver for presets

d3fa972

chore: use preset alias/shorthand in examples

e24b980

style: apply generic typeguard to plugin resolver

2bc2947

fsmaia requested a review from Josh-Cena November 16, 2021 22:54

Josh-Cena reviewed Nov 17, 2021

View reviewed changes

examples/classic-typescript/package.json Outdated Show resolved Hide resolved

fsmaia and others added 5 commits November 17, 2021 10:02

chore: apply shorthands to create-docusaurus instead of examples

83c49c3

chore: apply shorthands to create-docusaurus instead of examples

6a8b6bf

chore: apply shorthands to create-docusaurus instead of examples

aafc148

chore: apply shorthands to create-docusaurus instead of examples

96080e8

Merge branch 'main' into fsmaia/main

75e9aa9

Josh-Cena mentioned this pull request Nov 20, 2021

docs: added Algolia search to website typescript-eslint/typescript-eslint#4187

Merged

3 tasks

fsmaia mentioned this pull request Nov 26, 2021

Add support for shorthands in extends and plugins stylelint/stylelint#5745

Closed

Josh-Cena added 6 commits November 27, 2021 11:53

Fix e2e

c664a1f

Merge branch 'main' into fsmaia/main

01788bf

Refactors

424f9d8

Fix types

64d976a

Total refactor

3f28a10

Less diff

d7787d3

Doc writeup

0c37a2a

Josh-Cena linked an issue Nov 27, 2021 that may be closed by this pull request

Support shorthand for themes/plugins/presets configuration #5883

Closed

2 tasks

Merge branch 'main' into fsmaia/main

c6170f1

Fix scoped packages

eeff8e3

Josh-Cena added the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Dec 2, 2021

slorber added 2 commits December 3, 2021 17:27

Merge branch 'main' into fsmaia/main

c59b20e

dogfood names

5781c02

slorber approved these changes Dec 3, 2021

View reviewed changes

slorber added 2 commits December 3, 2021 17:57

minor doc change

0b6fb24

add tests for resolveModuleName

ddd3385

slorber reviewed Dec 3, 2021

View reviewed changes

slorber merged commit b366ba5 into facebook:main Dec 3, 2021

Josh-Cena removed the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Dec 9, 2021

valentine added a commit to valentine/docs.hackerspace.sg that referenced this pull request Mar 5, 2023

Sync config type-checking and shorthands from upstream

7803baa

facebook/docusaurus#5456 facebook/docusaurus#5589 facebook/docusaurus#5930

valentine added a commit to valentine/docs.hackerspace.sg that referenced this pull request Mar 5, 2023

Sync config type-checking and shorthands from upstream

e39dec2

facebook/docusaurus#5456 facebook/docusaurus#5589 facebook/docusaurus#5930

valentine added a commit to valentine/docs.hackerspace.sg that referenced this pull request Mar 5, 2023

Sync config code themes, type-checks, shorthands from upstream

69dce75

facebook/docusaurus#4968 facebook/docusaurus#5456 facebook/docusaurus#5589 facebook/docusaurus#5930

valentine added a commit to valentine/docs.hackerspace.sg that referenced this pull request Mar 5, 2023

Sync config code themes, type-checks, shorthands from upstream

404ac29

facebook/docusaurus#4968 facebook/docusaurus#5456 facebook/docusaurus#5589 facebook/docusaurus#5930

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: shorthands for themes/plugins/presets configuration #5930

feat: shorthands for themes/plugins/presets configuration #5930

fsmaia commented Nov 11, 2021

netlify bot commented Nov 11, 2021 •

edited

Loading

github-actions bot commented Nov 11, 2021 •

edited

Loading

fsmaia commented Nov 11, 2021 •

edited

Loading

Josh-Cena left a comment

fsmaia commented Nov 13, 2021

Josh-Cena commented Nov 14, 2021

fsmaia commented Nov 14, 2021 •

edited

Loading

Josh-Cena commented Nov 14, 2021

fsmaia commented Nov 16, 2021 •

edited

Loading

fsmaia commented Nov 16, 2021

fsmaia commented Nov 17, 2021

fsmaia commented Nov 19, 2021

Josh-Cena commented Nov 19, 2021

Josh-Cena commented Nov 27, 2021

fsmaia commented Nov 29, 2021

slorber left a comment

slorber Dec 3, 2021

slorber Dec 3, 2021

slorber Dec 3, 2021

slorber Dec 3, 2021

slorber Dec 3, 2021

slorber Dec 3, 2021

feat: shorthands for themes/plugins/presets configuration #5930

feat: shorthands for themes/plugins/presets configuration #5930

Conversation

fsmaia commented Nov 11, 2021

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

netlify bot commented Nov 11, 2021 • edited Loading

github-actions bot commented Nov 11, 2021 • edited Loading

fsmaia commented Nov 11, 2021 • edited Loading

Josh-Cena left a comment

Choose a reason for hiding this comment

fsmaia commented Nov 13, 2021

Josh-Cena commented Nov 14, 2021

fsmaia commented Nov 14, 2021 • edited Loading

Josh-Cena commented Nov 14, 2021

fsmaia commented Nov 16, 2021 • edited Loading

fsmaia commented Nov 16, 2021

fsmaia commented Nov 17, 2021

fsmaia commented Nov 19, 2021

Josh-Cena commented Nov 19, 2021

Josh-Cena commented Nov 27, 2021

fsmaia commented Nov 29, 2021

slorber left a comment

Choose a reason for hiding this comment

slorber Dec 3, 2021

Choose a reason for hiding this comment

slorber Dec 3, 2021

Choose a reason for hiding this comment

slorber Dec 3, 2021

Choose a reason for hiding this comment

slorber Dec 3, 2021

Choose a reason for hiding this comment

slorber Dec 3, 2021

Choose a reason for hiding this comment

slorber Dec 3, 2021

Choose a reason for hiding this comment

netlify bot commented Nov 11, 2021 •

edited

Loading

github-actions bot commented Nov 11, 2021 •

edited

Loading

fsmaia commented Nov 11, 2021 •

edited

Loading

fsmaia commented Nov 14, 2021 •

edited

Loading

fsmaia commented Nov 16, 2021 •

edited

Loading