Cannot get Elements to work in Docusaurus

[vaibhavshn]

Hello 👋🏽

I'm on the latest docusaurus version and I'm trying to use the API component, but it is giving errors - webpack 5 polyfill related.

Here's a link to a test repo: https://github.com/vaibhavshn/docs-test

Error Log

✖ Client
  Compiled with some errors in 894.53ms

ℹ ｢wds｣: Project is running at http://localhost:3000/
ℹ ｢wds｣: webpack output is served from /
ℹ ｢wds｣: Content not from webpack is served from /Users/vaibhav/dev/test/docs-test
ℹ ｢wds｣: 404s will fallback to /index.html


Module not found: Error: Can't resolve 'buffer' in '/Users/vaibhav/dev/test/docs-test/node_modules/@stoplight/yaml-ast-parser/dist/src/type'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "buffer": require.resolve("buffer/") }'
        - install 'buffer'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "buffer": false }
Module not found: Error: Can't resolve 'stream' in '/Users/vaibhav/dev/test/docs-test/node_modules/duplexer'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "stream": require.resolve("stream-browserify") }'
        - install 'stream-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "stream": false }
Module not found: Error: Can't resolve 'stream' in '/Users/vaibhav/dev/test/docs-test/node_modules/event-stream'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "stream": require.resolve("stream-browserify") }'
        - install 'stream-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "stream": false }
Module not found: Error: Can't resolve 'buffer' in '/Users/vaibhav/dev/test/docs-test/node_modules/event-stream'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "buffer": require.resolve("buffer/") }'
        - install 'buffer'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "buffer": false }
Module not found: Error: Can't resolve 'stream' in '/Users/vaibhav/dev/test/docs-test/node_modules/from'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "stream": require.resolve("stream-browserify") }'
        - install 'stream-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "stream": false }
Module not found: Error: Can't resolve 'stream' in '/Users/vaibhav/dev/test/docs-test/node_modules/map-stream'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "stream": require.resolve("stream-browserify") }'
        - install 'stream-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "stream": false }
Module not found: Error: Can't resolve 'buffer' in '/Users/vaibhav/dev/test/docs-test/node_modules/string_decoder/node_modules/safe-buffer'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "buffer": require.resolve("buffer/") }'
        - install 'buffer'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "buffer": false }
Module not found: Error: Can't resolve 'stream' in '/Users/vaibhav/dev/test/docs-test/node_modules/through'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "stream": require.resolve("stream-browserify") }'
        - install 'stream-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "stream": false }
Module not found: Error: Can't resolve 'lodash/fp' in '/Users/vaibhav/dev/test/docs-test/node_modules/@stoplight/elements-core'
Did you mean 'fp.js'?
BREAKING CHANGE: The request 'lodash/fp' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
Module not found: Error: Can't resolve 'lodash/fp' in '/Users/vaibhav/dev/test/docs-test/node_modules/@stoplight/elements'
Did you mean 'fp.js'?
BREAKING CHANGE: The request 'lodash/fp' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
Module not found: Error: Can't resolve '@stoplight/http-spec/oas2' in '/Users/vaibhav/dev/test/docs-test/node_modules/@stoplight/elements'
Did you mean 'index.js'?
BREAKING CHANGE: The request '@stoplight/http-spec/oas2' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
Module not found: Error: Can't resolve '@stoplight/http-spec/oas3' in '/Users/vaibhav/dev/test/docs-test/node_modules/@stoplight/elements'
Did you mean 'index.js'?
BREAKING CHANGE: The request '@stoplight/http-spec/oas3' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
Module not found: Error: Can't resolve './dist/abort-controller' in '/Users/vaibhav/dev/test/docs-test/node_modules/abort-controller'
Did you mean 'abort-controller.mjs'?
BREAKING CHANGE: The request './dist/abort-controller' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.

I fixed most of the errors by adding resolve.fallback in the config, but still getting error related to lodash/fp when I run npm start (dev mode) and abort-controller when i run npm run build.

Errors

When running npm start and visiting the page:

When running npm run build:

Error Log

BREAKING CHANGE: The request '@stoplight/http-spec/oas2' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
Module not found: Error: Can't resolve '@stoplight/http-spec/oas3' in '/Users/vaibhav/dev/test/docs-test/node_modules/@stoplight/elements'
Did you mean 'index.js'?
BREAKING CHANGE: The request '@stoplight/http-spec/oas3' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
Module not found: Error: Can't resolve './dist/abort-controller' in '/Users/vaibhav/dev/test/docs-test/node_modules/abort-controller'
Did you mean 'abort-controller.mjs'?
BREAKING CHANGE: The request './dist/abort-controller' failed to resolve only because it was resolved as fully specified
(probably because the origin is strict EcmaScript Module, e. g. a module with javascript mimetype, a '*.mjs' file, or a '*.js' file where the package.json contains '"type": "module"').
The extension in the request is mandatory for it to be fully specified.
Add the extension to the request.
Client bundle compiled with errors therefore further build is impossible.

I've used this config to get rid of all other errors except the two ones I've mentioned above:

const config = {
  plugins: [
    // fixes process is not defined error
    new webpack.DefinePlugin({
      process: {
        env: {},
      },
    }),
  ],
  resolve: {
    fallback: {
      buffer: require.resolve('buffer'),
      events: require.resolve('events'),
      stream: require.resolve('stream-browserify'),

      // doesn't work in browser when you visit /api
      lodash: require.resolve('lodash'),

      // build time errors
      '@stoplight/http-spec/oas2': false,
      '@stoplight/http-spec/oas3': false,

      // cannot solve this
      'abort-controller': require.resolve('abortcontroller-polyfill'), // also used `abort-controller`
    },
  },
};

[vaibhavshn]

Solved it!

Used this webpack config:

const config = {
  module: {
    rules: [
      {
        test: /\.m?js/,
        resolve: {
          fullySpecified: false,
        },
      },
    ],
  },
  plugins: [
    new ProvidePlugin({
      process: require.resolve('process/browser'),
    }),
  ],
  resolve: {
    fallback: {
      buffer: require.resolve('buffer'),
      stream: false,
      path: false,
      process: false,
    },
  },
};

This helped: https://github.com/stoplightio/elements/pull/1640/files/db2a2a547aa4a3b567c02d254ff080c8cdddcfbd#diff-cafe2123a72c4ce3a9f7e9ee4b0e188256eb02d7ec1e54fa2cadfac99b22f92b

[yhuard]

Hi! I've set up this repo to reproduce the error: https://github.com/yhuard/docusaurus-stoplight-elements

There's a simple page using @stoplight/elements' API component: https://github.com/yhuard/docusaurus-stoplight-elements/blob/main/src/pages/api.tsx

And a custom webpack config: https://github.com/yhuard/docusaurus-stoplight-elements/blob/main/docusaurus.config.js#L44

If I run yarn build locally (macOS 12.2.1), everything is fine:

~/dev/yhuard/docusaurus-stoplight-elements main* 34s
❯ yarn build
yarn run v1.22.17
$ docusaurus build
[INFO] [en] Creating an optimized production build...

✔ Client
  

✔ Server
  Compiled successfully in 41.45s

[zustand persist middleware] The given storage for item 'mosaic-theme' does not contain a 'removeItem' method, which will be required in v4.

✔ Client
  

● Server █████████████████████████ cache (99%) shutdown IdleFileCachePlugin
 stored

[SUCCESS] Generated static files in build.
[INFO] Use `npm run serve` command to test your build locally.
✨  Done in 51.32s.

I've also added a Dockerfile and docker-compose.yml to build the website in a Linux environment.

When I run docker-compose, the build fails:

~/dev/yhuard/docusaurus-stoplight-elements main* 48s
❯ docker-compose up --build
[+] Building 37.1s (14/14) FINISHED                                                                                                                                                                      
 => [internal] load build definition from Dockerfile                                                                                                                                                0.0s
 => => transferring dockerfile: 367B                                                                                                                                                                0.0s
 => [internal] load .dockerignore                                                                                                                                                                   0.0s
 => => transferring context: 212B                                                                                                                                                                   0.0s
 => [internal] load metadata for docker.io/library/node:16.13.2-alpine3.15                                                                                                                          0.7s
 => [internal] load build context                                                                                                                                                                   0.0s
 => => transferring context: 3.06kB                                                                                                                                                                 0.0s
 => [ 1/10] FROM docker.io/library/node:16.13.2-alpine3.15@sha256:2f50f4a428f8b5280817c9d4d896dbee03f072e93f4e0c70b90cc84bd1fcfe0d                                                                  0.0s
 => CACHED [ 2/10] WORKDIR /usr/src/app                                                                                                                                                             0.0s
 => CACHED [ 3/10] COPY package.json yarn.lock ./                                                                                                                                                   0.0s
 => CACHED [ 4/10] RUN yarn install --frozen-lockfile --silent && yarn cache clean                                                                                                                  0.0s
 => [ 5/10] COPY babel.config.js docusaurus.config.js sidebars.js tsconfig.json ./                                                                                                                  0.0s
 => [ 6/10] COPY blog blog                                                                                                                                                                          0.0s
 => [ 7/10] COPY docs docs                                                                                                                                                                          0.0s
 => [ 8/10] COPY src src                                                                                                                                                                            0.0s
 => [ 9/10] COPY static static                                                                                                                                                                      0.0s
 => ERROR [10/10] RUN yarn build                                                                                                                                                                   36.0s
------                                                                                                                                                                                                   
 > [10/10] RUN yarn build:                                                                                                                                                                               
#14 0.383 yarn run v1.22.15                                                                                                                                                                              
#14 0.409 $ docusaurus build                                                                                                                                                                             
#14 1.699 [INFO] [en] Creating an optimized production build...                                                                                                                                          
#14 2.282 ℹ Compiling Client                                                                                                                                                                             
#14 2.304 ℹ Compiling Server
#14 31.28 ✔ Client: Compiled successfully in 29.01s
#14 34.84 [zustand persist middleware] The given storage for item 'mosaic-theme' does not contain a 'removeItem' method, which will be required in v4.
#14 35.11 [ERROR] Docusaurus Node/SSR could not render static page with path /api because of following error:
#14 35.11 TypeError: Cannot read properties of undefined (reading 'allocUnsafe')
#14 35.11     at Module.88004 (main:238454:304)
#14 35.11     at __webpack_require__ (main:240492:42)
#14 35.11     at Object.18194 (main:6537:42)
#14 35.11     at __webpack_require__ (main:240492:42)
#14 35.11     at Object.7494 (main:4819:21)
#14 35.11     at __webpack_require__ (main:240492:42)
#14 35.11     at Object.79027 (main:4433:20)
#14 35.11     at __webpack_require__ (main:240492:42)
#14 35.11     at Object.76700 (main:4371:17)
#14 35.11     at __webpack_require__ (main:240492:42)
#14 35.38 ✔ Server: Compiled with some errors in 33.08s
#14 35.38 
#14 35.38 
#14 35.38 Error: Server-side rendering fails due to the error above.
#14 35.42 [ERROR] Unable to build website for locale en.
#14 35.49 [ERROR] Error: Failed to compile with errors.
#14 35.49     at /usr/src/app/node_modules/@docusaurus/core/lib/webpack/utils.js:207:24
#14 35.49     at /usr/src/app/node_modules/webpack/lib/MultiCompiler.js:554:14
#14 35.49     at processQueueWorker (/usr/src/app/node_modules/webpack/lib/MultiCompiler.js:491:6)
#14 35.49     at processTicksAndRejections (node:internal/process/task_queues:78:11)
#14 35.94 error Command failed with exit code 1.
#14 35.94 info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
------
failed to solve: rpc error: code = Unknown desc = executor failed running [/bin/sh -c yarn build]: exit code: 1

I'm using the webpack configuration that you mentioned.

[jvyang]

Try this:

// src/components/stoplight/index.tsx
import { API } from '@stoplight/elements';
import React from 'react';

export default function Stoplight() {
  return (
    <API
      apiDescriptionUrl="https://api.apis.guru/v2/specs/github.com/1.1.4/openapi.yaml"
      router="hash"
    />
  );
}

// src/pages/api.tsx
import React, { Suspense } from 'react';
import Layout from "@theme/Layout";
import "@stoplight/elements/styles.min.css";
import BrowserOnly from "@docusaurus/BrowserOnly";

const LazyApi = React.lazy(() => (import('../components/stoplight')));

function lazyApi() {
  return <LazyApi />;
}

function fallbackElement() {
  return <div>Loading</div>;
}

export default function Api() {
  return (
    <Layout title="API example">
      <BrowserOnly>
        {
          () =>
            <Suspense fallback={fallbackElement()}>
              {lazyApi()}
            </Suspense>
        }
      </BrowserOnly>
    </Layout>
  );
}

[yhuard]

Hi @jvyang, thanks for the suggestion, it's more elegant than my solution 👍 (although it does the same job in the end ;))

I've pushed the changes yhuard/docusaurus-stoplight-elements@ba545f9 so if anyone is interested by running Docusaurus + Stoplight together, here's a working example.

But still, I'm curious: were you able to compile my repo? (previous commit: yhuard/docusaurus-stoplight-elements@f55eebb) Or did you also face the same error on Ubuntu as the one I reported?

[jvyang]

I did experience the same issue you had. But I'm glad it all worked out!

[bucanero]

Hi @yhuard , your repo example was really useful as I was looking for a way to integrate Docusaurus with Stoplight and your code did the trick.

The only thing to report is that I had an error when building on case-sensitive systems, so on your api.tsx file I had to change this line (due to the fact that the file is called Stoplight.tsx):

-const LazyStoplight = React.lazy(() => import("../components/stoplight"));
+const LazyStoplight = React.lazy(() => import("../components/Stoplight"));

I hope this helps. Cheers