feat(svgr): create new Docusaurus SVGR plugin #10677
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
slorber
added
the
Argos
✅ [V2]
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Size Change: +52 kB (+0.46%) Total Size: 11.3 MB
ℹ️ View Unchanged
|
⚡️ Lighthouse report for the deploy preview of this PR
|
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
|
Size Change: +54.8 kB (+0.47%) Total Size: 11.7 MB
ℹ️ View Unchanged
|
2 tasks
This was referenced Nov 14, 2024
|
I'm not going to merge it right now because I'd like to do another patch release for v3.6 |
|
Did this feature mean that referencing
We weren't lol. |
|
@CMCDragonkai so what I understand is that you are trying to upgrade this site Polykey-Docs to Docusaurus v3.7, and see a different behavior right? Indeed you are not using the preset, curious to understand why? Although I agree, I think the retro-compatibility is not good enough and I broke some use-cases in v3.7. I'll try to figure out how to fix it. |
This was referenced Jan 6, 2025
|
As far as I understand the error comes from using SVGs in font declarations: @font-face {
font-family: "Open Sans";
src: url("/fonts/OpenSans-Semibold-webfont.eot");
src: url("/fonts/OpenSans-Semibold-webfont.eot?#iefix")
format("embedded-opentype"),
url("/fonts/OpenSans-Semibold-webfont.woff") format("woff"),
url("/fonts/OpenSans-Semibold-webfont.ttf") format("truetype"),
url("/fonts/OpenSans-Semibold-webfont.svg#open_sanssemibold") format("svg");
font-weight: 600;
font-style: normal;
}It's surprising that CSS loader tries to require those assets, I think I reported a bug in the past (edit, found it: webpack-contrib/css-loader#1256) But still a thing we supported before, so I'll restore that behavior in #10820. A fix will be in v3.7.1. |
|
We were loading SVGs just with a CSS background image. :root {
--custom-navbar-search-input-icon: url('/static/images/Search.svg');
}And we got that build error. We were scratching our heads, so we compared versions and discovered that docusaurus had changed their underlying version - which to me this is a breaking change... We don't use the preset because we have a custom theme, so we loaded individual plugins as needed. We fixed it by loading the plugin that you introduced directly into our docusaurus configuration, and it worked. Sometimes we also make use of assets that docusaurus's existing webpack configuration doesn't support, so we customise loader plugin too: /**
* Process additional extensions under the static assets
*/
const pluginLoaders = () => {
return {
name: 'custom-loaders',
configureWebpack(_config, isServer) {
return {
module: {
rules: [
{
test: /\.(?:gltf|bin|obj|usdz|glb)$/i,
use: [
{
loader: 'file-loader',
options: {
name: path.posix.join(
'assets',
'files',
'[name]-[contenthash].[ext]',
),
emitFile: !isServer,
},
},
],
},
],
},
};
},
};
};Ideally the docs should be clearer about how to support these additional static assets... |
Not sure what you mean by "underlying version"? If you upgraded Docusaurus, then it's you who changed the version right? It isn't supposed to happen automatically, at least if you use a lock file. Now I agree: this behavior should not break in v3.x so I mistakenly shipped a breaking change that I'm reverting in the upcoming v3.7.1 release.
I see thanks for providing the context.
Yes it works, although it's a bit awkward to have to do so if you don't plan to use SVGR. That's why I'm fixing it for v3.7.1: so that you don't need to do this awkward thing.
The doc explains you can use Also, we try to abstract the underlying bundler as best as we can. If someday we decide to change bundler and use let's say Rolldown, Bun, or esbuilt, then your code breaks. We don't particularly want to encourage you to extend our webpack config unless you really need to (which you need in this case). We won't provide "pre-made recipes", if you do it, you must understand what you are doing and be ready to read the whole webpack doc if needed. That being say, we'll later explore using Unplugin so that we can let users extend the bundler in a more portable/agnostic way. And having a first-class Docusaurus feature to register new file/image extensions could make sense too. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
We historically include SVGR in core by default
This works but it's a bit annoying since it doesn't make it easy for configuring it, including SVGO optimizations that cause troubles in some cases:
Since we don't really want core to expose configuration options, let's extract all this logic to a dedicated plugin instead, that allows passing plugin options to configure both SVGR and SVGO.
Breaking change?
For v3 retro compatibility, I'm adding the new SVGR plugin to the classic preset. Since everybody uses the preset (afaik),
I'm not going to consider it a breaking change unless someone complains in which case we'll look for a solution that we could implement in a patch release.
Note: better retro-compatibility is possible to achieve. But it's more complex and probably not worth it. If any user doesn't use the preset, that's super easy to install/use the plugin manually.
Note: we may change our current SVGR/SVGO defaults in another PR, but that will be a breaking change. Tracked in #10679.
Usage
Preset:
Plugin:
Note the API is using
svgr.svgrConfigon purpose, it's not a mistake. We might add plugin options that are not directly SVGR options in the future but are more related to the SVGR + Webpack (loader) integration. Or options that decide whether or not to merge the provided config into the default one.Customizing SVGO
Provide custom SVGO options this way:
If you want to use a custom
svgo.config.jsfile you can usesvgoConfig: undefined. When not passing any explicit SVGO config options (which we do by default), the SVGO config file will be used.Test Plan
CI + Argos
Test links
Pages with SVGs:
Docs:
.svgo.config.js.svgo.config.jsRelated issues/PRs
See: