docusaurus icon indicating copy to clipboard operation
docusaurus copied to clipboard

Remove `@mdx-js/react` from templates

Open zpao opened this issue 1 year ago • 2 comments

This shouldn't need to be an explicit dependency. The preset is already depending on it.

Motivation

Cleaner dependencies! There are a couple reasons

  1. The classic typescript starter template is 200MB of dependencies.
  2. This is explicitly required anywhere in the website so it shouldn't be a dependency.

Test Plan

Used the TS starter to create a website. Removed this dependency. Site still works in development mode. Included MDX blog post still works correctly.

zpao avatar Aug 02 '22 23:08 zpao

[V2]

Name Link
Latest commit c7d99fb15e1242224c6a503ea07e03b4c354da00
Latest deploy log https://app.netlify.com/sites/docusaurus-2/deploys/62e9b2a0356a5a0008c330b3
Deploy Preview https://deploy-preview-7889--docusaurus-2.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

netlify[bot] avatar Aug 02 '22 23:08 netlify[bot]

⚡️ Lighthouse report for the deploy preview of this PR

URL Performance Accessibility Best Practices SEO PWA Report
/ 🟠 84 🟢 98 🟢 100 🟢 100 🟠 80 Report
/docs/installation 🟠 79 🟢 100 🟢 100 🟢 100 🟢 90 Report

github-actions[bot] avatar Aug 02 '22 23:08 github-actions[bot]

😧 TIL. That's much messier than I thought.

Alright. I'll abandon this then. The only initial thought I had around this was actually doing the opposite and pull things out of the core/preset/plugin, and then make these starters more explicit in the dependencies. So you get @docusaurus/mdx-loader and @mdx-js/react in your project dependencies which are clearly related (but easy to remove if you don't want to use mdx) instead of @docusaurus/core (which installs the mdx loader) and then mdx itself.

That's a pretty big departure from the current (mostly) kitchen sink approach so it's not something to be considered lightly, nor something I have enough invested in to really test out myself. Maybe one day I'll come back to it.

zpao avatar Aug 03 '22 18:08 zpao

Yeah, a lot of stuff we have in the init template is to make PnP happy out-of-the-box. Otherwise we could have gone for a much leaner list. The more dependencies we let the user manage, the less likely they are going to manage it well.

Josh-Cena avatar Aug 04 '22 01:08 Josh-Cena

We don't have to use @mdx-js/react pragma in the MDX loader, we could as well create a custom Docusauurs pragma that does nothing but forward to the original pragma?

Maybe we could hide all those dependencies in a @docusaurus/mdx package? At least it could have the same version as other core packages, and it would look a bit cleaner 🤷‍♂️

It looks to me some users are trying to upgrade to MDX 2 (while they shouldn't) and inadvertently break their sites. Maybe if we decided on the MDX version they use, it wouldn't happen: https://github.com/facebook/docusaurus/discussions/7887#discussioncomment-3348648


Note: it's quite unlikely someone would use Docusaurus without MDX in the short term, but it's possible that in the future we allow alternative parsers and some users will use Docusaurus with blog/docs and use another Markdown parser than MDX

slorber avatar Aug 08 '22 11:08 slorber