Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(core): simplify plugin API, support route.props (experimental) #10042

Merged
merged 27 commits into from
Apr 16, 2024

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented Apr 12, 2024

EXPERIMENTAL

This feature is considered experimental for now.

It is preferable that third-party plugin authors wait for it to become stable/documented before relying on it.

Motivation

The plugin API is currently needlessly complicated and confusing.

Even the most basic example involves too much ceremony:
https://docusaurus.io/docs/api/plugin-methods/lifecycle-apis

export default function friendsPlugin(context, options) {
  return {
    name: 'docusaurus-friends-plugin',
    async contentLoaded({content, actions}) {
      const {createData, addRoute} = actions;
      // Create friends.json
      const friends = ['Yangshun', 'Sebastien'];
      const friendsJsonPath = await createData(
        'friends.json',
        JSON.stringify(friends),
      );

      // Add the '/friends' routes, and ensure it receives the friends props
      addRoute({
        path: '/friends',
        component: '@site/src/components/Friends.js',
        modules: {
          // propName -> JSON file path
          friends: friendsJsonPath,
        },
        exact: true,
      });
    },
  };
}

We want to make this simpler, the user shouldn't need to think about filesystem paths and created modules, but just "declare" that the component/route should receive.

export default function friendsPlugin(context, options) {
  return {
    name: 'docusaurus-friends-plugin',
    async contentLoaded({content, actions}) {
      actions.addRoute({
        path: '/friends',
        component: '@site/src/components/Friends.js',
        exact: true,
        props: {
		  friends: ['Yangshun', 'Sebastien']
        }
      });
    },
  };
}

This new route.props API can already greatly simplify our own plugins.

Note: the route.modules API will remain useful when a module need to be shared between multiple routes. However, we'll later also refactor it to not use the confusing createData() API.

We'll progressively migrate all contentLoaded APIs toward a more declarative model, and eventually make it synchronous to ensure it does not perform any IO operation. This will further permit us to optimize the DX. We can bail out of useless computations if we have everything in memory instead of having to query the filesystem.

Test Plan

unit tests + dogfood on our own plugins

Test links

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

@slorber slorber added the pr: new feature This PR adds a new API or behavior. label Apr 12, 2024
@slorber slorber requested a review from Josh-Cena as a code owner April 12, 2024 16:41
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Apr 12, 2024
Copy link

netlify bot commented Apr 12, 2024

[V2]

Name Link
🔨 Latest commit eeef26a
🔍 Latest deploy log https://app.netlify.com/sites/docusaurus-2/deploys/661e630c65390f000868b645
😎 Deploy Preview https://deploy-preview-10042--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 configuration.

Copy link

github-actions bot commented Apr 12, 2024

⚡️ Lighthouse report for the deploy preview of this PR

URL Performance Accessibility Best Practices SEO PWA Report
/ 🟠 71 🟢 98 🟢 96 🟢 100 🟠 88 Report
/docs/installation 🟠 67 🟢 96 🟢 100 🟢 100 🟠 88 Report
/docs/category/getting-started 🟠 75 🟢 100 🟢 100 🟢 90 🟠 88 Report
/blog 🟠 70 🟢 100 🟢 100 🟢 90 🟠 88 Report
/blog/preparing-your-site-for-docusaurus-v3 🟠 63 🟢 96 🟢 100 🟢 100 🟠 88 Report
/blog/tags/release 🟠 71 🟢 100 🟢 100 🟠 80 🟠 88 Report
/blog/tags 🟠 75 🟢 100 🟢 100 🟢 90 🟠 88 Report

Copy link

github-actions bot commented Apr 12, 2024

Size Change: -6.8 kB (0%)

Total Size: 1.59 MB

Filename Size Change
website/.docusaurus/registry.js 247 kB -2.94 kB (-1%)
website/.docusaurus/routesChunkNames.json 109 kB -1.08 kB (-1%)
website/build/assets/js/main.********.js 808 kB -2.78 kB (0%)
ℹ️ View Unchanged
Filename Size
website/.docusaurus/codeTranslations.json 2 B
website/.docusaurus/docusaurus.config.mjs 26.7 kB
website/.docusaurus/globalData.json 91.2 kB
website/.docusaurus/i18n.json 930 B
website/.docusaurus/routes.js 156 kB
website/.docusaurus/site-metadata.json 2.17 kB
website/build/assets/css/styles.********.css 113 kB
website/build/index.html 38 kB

compressed-size-action

@slorber slorber marked this pull request as draft April 12, 2024 17:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants