Add comment about Webpack plugin to fail builds on warnings

packages/storybook/.storybook/webpack-plugin-fail-build-on-warning.js

@@ -14,6 +14,22 @@
  * limitations under the License.
  */
 
+/**
+ * When building storybook, we can have warnings which may cause issues in the future. One of the example case is
+ * https://github.com/spotify/backstage/issues/718. To make sure new warnings are not introduced with new PRs, we
+ * want to fail CI builds if there are warnings when building storybook.
+ *
+ * This webpack plugin makes sure the CI builds fail on Webpack warnings. We also have a whitelist of warnings here
+ * which we think are non-critical.
+ *
+ * Note that this implementation will not detect other warnings emitted by storybook build that are separate from
+ * Webpack. A better solution over this plugin should be preferred, possibly on Storybook level (CLI options etc.)
+ *
+ * The case with #718 is caused because we are using `ts-loader` for `webpack` to load all our JS/TS files, but we
+ * have disabled type checking during build. This is done by setting `transpileOnly` to `true` in storybook/main.js
+ * and it improves the Storybook build speed. Because of this, Webpack emits warnings when we try to re-export types.
+ * Reference: https://github.com/TypeStrong/ts-loader#transpileonly
+ */
 class WebpackPluginFailBuildOnWarning {
   // Ignore the following warnings in the Webpack build.
   warningsWhitelist = new Set([