fix: move dependencies to peer dependencies

[aramissennyeydd]

Description

Motivation and Context

I'm trying to add this plugin to Backstage's docsite to automatically show OpenAPI-documented APIs (PR: backstage/backstage#27573). I noticed that this package was causing a lot of lockfile churn and bringing in versions that I would expect to be duplicates, but aren't.

How Has This Been Tested?

Locally linked this into my Backstage fork and verified that no additional docusaurus dependencies were duplicated, there was only a single version of each dep.

This is my first contribution to this repo, so please share any additional testing steps I should be taking here 🙇 .

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.

[alvinometric]

Yes! This should help with the recent issues around upgrading

[sserrata]

Hi @aramissennyeydd, I haven't had time to test yet but I think this could potentially work. Am I correct in that the peerDependencies will:

• Be installed if not already installed by user in project
• Raise a warning/error if the user has a conflicting version installed in project (basically refuse to install until the user addresses the conflict)

Yes! This should help with the recent issues around upgrading

Hi @alvinometric, can you explain why/how you think this should help prevent Docusaurus dependency conflicts? Interested to hear your thoughts. Thanks!

[aramissennyeydd]

@sserrata

Be installed if not already installed by user in project

This depends on the package manager, if the user already installed a specific version for their site, this will prevent a secondary version from being installed. In my case, we are using a specific version of docusaurs for our docsite and this package is bringing in a separate version with different resolutions.

Raise a warning/error if the user has a conflicting version installed in project (basically refuse to install until the user addresses the conflict)

Again, depends on the package manager - in general, the default is that it will allow install but add a warning log.

[github-actions]

Visit the preview URL for this PR (updated for commit 4fe47d9):

https://docusaurus-openapi-36b86--pr1019-507tuj9n.web.app

_{(expires Fri, 13 Dec 2024 15:41:02 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: bf293780ee827f578864d92193b8c2866acd459f}

[sserrata]

Thanks @aramissennyeydd, that makes sense.

I suppose this leaves room for users to still end up with dep conflicts, but at least they'd get a warning.

With Docusaurus, there's a potential for breaking changes, even between patch releases, so I've made it a habit to always delete my yarn.lock file between upgrades. I know that's not always practical for all users so if peerDependencies can help alleviate some of that friction I'm all for it.

[karl-cardenas-coding]

@sserrata Did you by chance loose the icon for curl?

When we use the canary, I see that the CSS class has some odd values for the URL.

.openapi-tabs__code-item--http::after {
  content: "";
  display: inline-block;
  width: 32px; /* Explicitly setting width to 32 pixels */
  height: 32px; /* Explicitly setting height to 32 pixels */
  background-image: url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyIDIyTDggMTZMMTIgMTBNMjAgMjJMMjQgMTZMIDIwIDEwIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4=");
  background-size: contain;
  background-repeat: no-repeat;
  background-position: center; /* Center the SVG */
  margin-top: 0.5rem;
}

WHereas other language classes have a normal URL.

.openapi-tabs__code-item--java::after {
  content: "";
  width: var(--code-tab-logo-width);
  height: var(--code-tab-logo-height);
  background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/java/java-original.svg") no-repeat;
  margin-block: auto;
}

[sserrata]

@sserrata Did you by chance loose the icon for curl?

When we use the canary, I see that the CSS class has some odd values for the URL.

.openapi-tabs__code-item--http::after {
  content: "";
  display: inline-block;
  width: 32px; /* Explicitly setting width to 32 pixels */
  height: 32px; /* Explicitly setting height to 32 pixels */
  background-image: url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHBhdGggZD0iTTEyIDIyTDggMTZMMTIgMTBNMjAgMjJMMjQgMTZMIDIwIDEwIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4=");
  background-size: contain;
  background-repeat: no-repeat;
  background-position: center; /* Center the SVG */
  margin-top: 0.5rem;
}

WHereas other language classes have a normal URL.

.openapi-tabs__code-item--java::after {
  content: "";
  width: var(--code-tab-logo-width);
  height: var(--code-tab-logo-height);
  background: url("https://raw.githubusercontent.com/devicons/devicon/master/icons/java/java-original.svg") no-repeat;
  margin-block: auto;
}

If you believe you found a bug please open a separate issue with steps to repro. Before that, I suggest searching through older issues or have a look at the demo as I believe this one has already been addressed. Thanks!

[karl-cardenas-coding]

Thanks @sserrata I placed this in the wrong issue 🤦🏻
But on the bright side. I did find my answer, so thanks for the tip 😄

[Gijsdeman]

This depends on the package manager, if the user already installed a specific version for their site, this will prevent a secondary version from being installed. In my case, we are using a specific version of docusaurs for our docsite and this package is bringing in a separate version with different resolutions.

Using the canary version and yarn 1.22.22. With these changes, the @hookform/error-message is not automatically resolved, which causes the build to fail:

× Module not found: Can't resolve '@hookform/error-message' in '/home/gijs/Documents/documentation/node_modules/docusaurus-theme-openapi-docs/lib/theme/ApiExplorer/ParamOptions/ParamFormItems'
    ╭─[16:24]
 14 │ });
 15 │ const react_1 = __importDefault(require("react"));
 16 │ const error_message_1 = require("@hookform/error-message");
    ·                         ──────────────────────────────────
 17 │ const FormMultiSelect_1 = __importDefault(require("@theme/ApiExplorer/FormMultiSelect"));
 18 │ const slice_1 = require("@theme/ApiExplorer/ParamOptions/slice");
    ╰────

I am also unsure how peer dependencies should be resolved, but I expect this to be undesired behaviour.

[aramissennyeydd]

@Gijsdeman I think you're right, I opened #1023 to fix that one. Do the rest of the peer dependencies work? Going to test this against Backstage's docsite tonight.

[Gijsdeman]

As far as I can tell the rest of the dependencies are resolved correctly.

[aramissennyeydd]

Confirmed on my end that the dependencies are resolving to the same docusaurus version that I have installed in the project and I'm not getting any runtime errors.