Glue
This website includes several different technologies that do not fit neatly together out-of-the-box. This page identifies some of the things that have been done to make these different elements act like a team.
Copying Styles
Docusaurus does not rely on a static file for it's global CSS. Instead, it generates a new CSS file (with a new name) on each build.
This makes rendering Storybook with styles that mirror the Docusaurus styles a bit of a challenge.
The solution has been to add a custom Docusaurus plugin that runs after the build, and populates the styles in a known location with a stable name that Storybook stories can then import.
CopyStylesPlugin applied to the Docusaurus configuration
Assumptions
-
Docusaurus global styles will always be a single CSS file
cautionThis imposes a limitation on the build order. Docusaurus must build before Storybook. For this reason, the preproduction and production builds have Storybook place its build output directly in the 'build' directory (as opposed to 'static' which would be the normal Docusaurus practice)
Blog Truncation
Docusaurus allows you to set a custom token for determining where, when shown as part of a list, a blog post will be truncated.
Docusaurus does not automatically strip the new token from the blog post content when viewed outside of a list.
See this related blog post
The fix for this was to add a custom Remark plugin to the docusaurus configuration
Webpack
Storybook and Docusaurus both rely on Webpack, but with different basic assumptions.
File Formats
MDX
The bulk of the content that will be passed to custom React components is defined as MDX. Storybook knows how to ingest MDX fies when they are definitions for stories or documentation pages within the Storybook realm, but when MDX is imported as part of a component-under-test, Storybook fails.
SVG
Docusaurus is, by default, configured to import SVG files as React components using SVGR. Storybook does not know about this dependency, even with the babel configuration in place
see my Logo component for an examples of SVG images being imported, then used as React components.
When a component-under-test imports SVG in this way, Storybook fails, because Storybook is trying to import the SVG as text.
Solution
The solution fixes both of these issues, with the added benefit of aligning the Docusaurus and Storybook Babel configurations (which solved some additional issues with JSX loading correctly).
The solution is a small module that transforms a webpack configuration. Currently the only transformations are applied to the 'module.rules' array, but the module is easily extensible to apply to other portions of the config object.
A rule is an object conforming to the TypeScript type RuleSetRule, provided by
webpack.
A Transform is a function that accepts a RuleSetRule[] and produces another
RuleSetRule[], assumed to be a transformation of the first set. Used to apply
a single rule.
The webpackFinal function applies the above logic to the original configuration logic.
This approach is highly maintainable and extensible
The current rules applied:
- Ensure Storybook is using the same babel config as Docusaurus (solving JSX and MDX issues)
- Exclude Storybook from importing SVG files using any default configuration
- Prompt Storybook to import SVG using SVGR (as Docusaurus does)