Uncaught Runtime Errors

[SirPhemmiey]

Describe the bug

I am trying to integrate this package into my existing docusaurus documentation and i'm running into issues with running the docs. I get this error everytime i load/serve it up and sometimes as soon as i click on the sidebar that contains the API

Expected behavior

I expect it to work as usual. I expect it to load up the mdx generated pages

Current behavior

It's currently throwing an error. I've tried different combinations of versions, it's still not working.

Steps to reproduce

Screenshots

Your Environment

First Version

 "@docusaurus/core": "3.4.0",
    "@docusaurus/preset-classic": "3.4.0",
    "@mdx-js/react": "^3.0.0",
    "prism-react-renderer": "2.3.0",
    "docusaurus-plugin-openapi-docs": "3.0.0-beta.10",
    "docusaurus-theme-openapi-docs": "3.0.0-beta.10",

Second Version

  "@docusaurus/core": ">=2.4.1 <=2.4.3",
    "@docusaurus/preset-classic": ">=2.4.1 <=2.4.3",
    "@mdx-js/react": "^1.6.22",
    "clsx": "^1.1.1",
    "docusaurus-plugin-openapi-docs": "2.1.0",
    "docusaurus-theme-openapi-docs": "2.1.0",

my docusaurus.config.js file

// import { themes as prismThemes } from 'prism-react-renderer';

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'title',
  tagline: '',
  url: 'url',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',

  // Even if you don't use internalization, you can use this field to set useful
  // metadata like html lang. For example, if your site is Chinese, you may want
  // to replace "en" with "zh-Hans".
  // i18n: {
  //   defaultLocale: 'en',
  //   locales: ['en'],
  // },

  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // docRootComponent: '@theme/DocRoot',
          docLayoutComponent: '@theme/DocPage',
          docItemComponent: '@theme/ApiItem',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],
  plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'docs', // plugin id
        docsPluginId: 'classic', // id of plugin-content-docs or preset for rendering docs
        config: {
          lebowski: {
            specPath: '../lebowski/open-api/adrequest-proxy-spec.yaml',
            outputDir: 'docs/ad-request-proxy/OpenAPI',
            sidebarOptions: {
              // optional, instructs plugin to generate sidebar.js
              groupPathsBy: 'tag', // group sidebar items by operation "tag"
            },
          },
        },
      },
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: 'AdTech docs',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            href: 'ref_link',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Getting started',
            items: [
              {
                label: 'Getting started',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Github',
            items: [
              {
                label: 'AdTech monorepo',
                href: 'ref_link',
              },
              {
                label: 'Proxy Ads',
                href: 'ref_link',
              },
              {
                label: 'Proxy Events',
                href: 'ref_link',
              },
            ],
          },
          {
            title: 'Related documentation',
            items: [
              {
                label: 'Kevel API docs',
                to: 'https://dev.kevel.com/reference/request',
              },
            ],
          },
        ],
      },
      prism: {
        // theme: prismThemes.github,
        // darkTheme: prismThemes.dracula,
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
  themes: ['docusaurus-theme-openapi-docs'],
};

module.exports = config;

[sserrata]

Hi @SirPhemmiey, I'd pay close attention to dependencies, making sure to not have a mismatch between docusaurus and the plugin. I'd also make sure all packages are installed since you appear to be encountering a rather low-level error.

[SirPhemmiey]

HI @sserrata , thanks for your response.

To (re)validate what you said about dependencies mismatch, i use the exact package versions that the demo uses.

 "@docusaurus/core": "2.4.3",
    "@docusaurus/plugin-google-gtag": "2.4.3",
    "@docusaurus/preset-classic": "2.4.3",
    "@mdx-js/react": "^1.6.22",
    "clsx": "^1.1.1",
    "docusaurus-plugin-openapi-docs": "^2.1.3",
    "docusaurus-theme-openapi-docs": "^2.1.3",

and i still get the same issue:

[SirPhemmiey]

related https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/607

[SirPhemmiey]

hi @sserrata , any leads here please?

[sserrata]

Hi @SirPhemmiey, sorry, I'm not able to reproduce this error/state. We're planning to update/refresh the installation docs which will hopefully make things a bit more clear, and help users avoid such issues.

[SirPhemmiey]

@sserrata okay thanks. If it helps, i'm trying to integrate it into an existing docusaurus project

[sserrata]

Thanks, any chance you could provide reproduction steps or a link to a repo that reproduces the error?

[robbieaverill]

I'm experiencing the same error. As soon as I enable themes: ['docusaurus-theme-openapi-docs'] in my project, build results in these warnings:

[WARNING] {"moduleIdentifier":".../node_modules/.pnpm/@[email protected]_@[email protected][email protected][email protected]__react@18._tbvvrqzkpwxcrrvyytxy5mferu/node_modules/@docusaurus/mdx-loader/lib/index.js??ruleSet[1].rules[8].use[0]!.../docs/api/file/my-api-document.api.mdx","moduleName":"./docs/api/file/my-api-document.api.mdx","loc":"1765:41-51","message":"export 'default' (imported as 'SchemaItem') was not found in '@theme/SchemaItem' (possible exports: __esModule)","compilerPath":"client"}

When I serve the site and run a generated API page in the browser, the page doesn't render, and I see this in the console:

ReferenceError: exports is not defined
    at 9692 (6802.afa9858e.js:1:20057)
    at r (runtime~main.6b80db94.js:1:136)
    at 73007 (8d4d3923.89f9cb80.js:1:260)
    at Function.r (runtime~main.6b80db94.js:1:136)
    at s.invoke (main.9b7ffa07.js:102:291300)
    at r.run (main.9b7ffa07.js:102:286589)
    ...

I'm unable to reproduce this with a fresh install of Docusaurus and this plugin, although I'm continuing to try.

Possible contributing factors:

• I'm using Rush (pnpm) as a package manager
• I'm installing the library into an existing Docusaurus site, rather than creating a fresh install with this plugin as the template

[robbieaverill]

@sserrata I've managed to create a reproduction with some minimal config: https://stackblitz.com/edit/github-wad2ay.

Notes:

• This includes a minimal example in docs/api/file of one of the generated MDX files from my schema. I didn't include the schema as it is private, although I could massage it slightly if you need.
• Run yarn build and you will see the "WARNING" noted above, about the exports being unavailable for @theme/SchemaItem
• Run yarn serve then go to Tutorial -> api. You will see the exports is not defined error in the console.

[programm-ingovals]

I´m having this same issue. In my case I added Docusaurus to a NX monorepo.

I'm thinking this could possibly be a mismatch on webpack or some kind of dependency kerfuffle.

[drwelby]

I'm also hitting this migrating a site from Docusaurus 2 to 3, in case anyone wants to compare notes. I'm seeing a couple different things:

• Though the bulk of the warnings are for @theme/SchemaItem, I see a couple for @theme/MimeTabs and @theme/ApiTabs
• The pages render with npm run serve but the API sidebar is empty and says "Loading..."
• One of my very normal index.md files crashes and therefore I get broken link warnings to its index.html

Update: bootstrapping a new Docusaurus 3 skeleton site and copying the content across resulted in a working site. I'll try to compare some of the webpack and babel settings for some clues.

[iursevla]

@drwelby any luck?

[drwelby]

@iursevla I think so! I added the browserslist from the Docusaurus skeleton:

"browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 3 chrome version",
      "last 3 firefox version",
      "last 5 safari version"
    ]
  }

and then ran

npm run clear
npm run build

And it's building successfully.

[iursevla]

@drwelby thanks for the reply. It doesn't work for me but it might be something on my side. If you have some minutes can you tell me if you can run the demo locally? I opened this issue yesterday, related with the demo page. I cannot use it locally and I'm trying to understand if it something on my end or it is really broken.

By running the demo I mean:

1. clone the project
2. cd into demo directory and yarn install+ yarn start
3. Navigate to one of the open API endpoints and see if you can view it on the browser.

[drwelby]

@iursevla your errors seem to be unrelated to the ones encountered by the others in this thread. Unfortunately, I could not get the demo running to check.

[iursevla]

@drwelby It seems to be fixed on 4.1.0. Everything is fine now (https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/980)

[Nicolas-Menettrier]

same issue on the latest version (4.4.0 at this date), with docusaurus 3.7.0

edit: I tried to copy/paste the template project into my nx monorepo and I still get the same issue

[liam552]

Adding this to my babel.config.js seems to fix the problem:

  overrides: [
    {
      test: /(docusaurus-theme-openapi-docs|docusaurus-plugin-openapi-docs)/,
      sourceType: 'unambiguous',
    },
  ],

The problem seems to be because my project's Babel thinks all the built files in docusaurus-theme-openapi-docs/lib and docusaurus-plugin-openapi-docs/lib are ESM. In reality, some files are CJS and some are ESM. Specifically, it seems like the files which are built from TypeScript are CJS but the files which are built from plain JS (e.g. json2xml.js) are ESM.