Build fails when config includes redocusaurus and docusaurus-theme-search-typesense

[GalexyN]

Hi

I'm getting a build error when I compile with 2 plugins in the same config

• redocusaurus 1.3.0
• docusaurus-theme-search-typesense 0.7-0.0

I also wanted to note that I only run into this error when running npm run build if i do npm start everything works fine with both plugins available in the docusaurus config.

I've tried a mix of the following

• rm -rf node_modules package-lock.json and reinstall
• downgrading docusaurus to v2.0.1
• upgrading to docusaurus v2.1.0

I've noticed that if I were to comment out the redocusaurus config in presets of docusaurus.config.js OR themes:['docusaurus-theme-search-typesense'] the build happens smoothly

docusaurus.config.js

  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        blog: false,
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
    [
      'redocusaurus',
      {
        specs: [
          {
            spec: require.resolve('./static/api_spec/open-api-spec.yml'),
            route: '/api',
          },
        ],
        theme: {
          primaryColor: '#2e8555',
          primaryColorDark: '#25c2a0'
        },
      },
    ],
  ],
  themes: ['docusaurus-theme-search-typesense'],

package.json

{
  "name": "json-api-docs",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids",
    "typecheck": "tsc"
  },
  "dependencies": {
    "@docusaurus/core": "^2.1.0",
    "@docusaurus/preset-classic": "^2.1.0",
    "@mdx-js/react": "^1.6.22",
    "clsx": "^1.2.1",
    "docusaurus-theme-search-typesense": "^0.7.0-0",
    "prism-react-renderer": "^1.3.5",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "redocusaurus": "^1.3.0"
  },
  "devDependencies": {
    "@docusaurus/module-type-aliases": "^2.1.0",
    "@tsconfig/docusaurus": "^1.0.5",
    "typescript": "^4.7.4"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "engines": {
    "node": ">=16.14"
  }
}

error message

[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
  Compiled with some errors in 15.89s

main:55529
                {}.DEBUG = namespaces;
                  ^

SyntaxError: Unexpected token '.'
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
    at .../json-api-docs/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
    at .../json-api-docs/node_modules/webpack/lib/MultiCompiler.js:554:14
    at processQueueWorker (.../json-api-docs/node_modules/webpack/lib/MultiCompiler.js:491:6)
    at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.1.0
Node version: v16.14.2

[balazsbotond]

I have the exact same issue. It would be great to be able to use both search and redocusaurus at the same time, but honestly I have no idea where to even start debugging it.

@GalexyN have you found a workaround in the meantime?

[balazsbotond]

I made a minimal example to reproduce the bug, I hope it will help whoever can debug this:

https://github.com/balazsbotond/redocusaurus-typesense-bug-repro

[balazsbotond]

Please note that @GalexyN also reported the same issue here: typesense/docusaurus-theme-search-typesense#23

I've found a closed issue about the same problem in the debug.js project.

A PR which fixed this issue with minimal changes was rejected with the justification that "it wasn't the maintainers' job to fix other people's messes". Another PR which may fix this issue has been open for more than four years.

The original issue offers several possible workarounds by defining webpack plugins but I'm not sure these can be added to a Docusaurus project.

One of my coworkers suggested simply commenting out the offending line in the node_modules folder (node_modules/debug/src/node.js):

function save(namespaces) {
	if (namespaces) {
		// process.env.DEBUG = namespaces;
	} else {
		// If you set a process.env field to null or undefined, it gets cast to the
		// string 'null' or 'undefined'. Just delete instead.
		delete process.env.DEBUG;
	}
}

Which, while being an incredibly hacky solution, is the one we currently use as part of our CI pipeline by running the following sed command after installing npm packages:

sed -i '/process.env.DEBUG = namespaces;/c\// process.env.DEBUG = namespaces;' ./node_modules/debug/src/node.js

Far from ideal, I know, but I hope it helps someone until the root cause is fixed.

[rohit-gohri]

defining webpack plugins but I'm not sure these can be added to a Docusaurus project.

This is very easy to do. We already do it here - https://github.com/rohit-gohri/redocusaurus/blob/main/packages/docusaurus-theme-redoc/src/index.ts#L24-L27

If some one can open a PR, I'll be happy to review and release it. Thanks @balazsbotond for the research on the issue!

[rohit-gohri]

Probably this is the culprit -

redocusaurus/packages/docusaurus-theme-redoc/src/index.ts

Line 29 in 45a314b

'process.env': JSON.stringify({}),

But this was added for some other reason. Better to add a define for DEBUG before this

[Sakura-pgh]

I solved the problem by changing this in docusaurus.config.js

plugins: [
    ...
    async function customPlugin(context, opts) {
      return {
        name: 'custom-plugin',
        configureWebpack(config, isServer, utils, content) {
          // Modify internal webpack config. If returned value is an Object, it
          // will be merged into the final config using webpack-merge;
          // If the returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
          return {
            plugins: [
              new webpack.DefinePlugin({
                // IMPORTANT: To fix debug library‘s bug
                // {}.DEBUG = namespaces; // SyntaxError: Unexpected token '.'
                'process.env.DEBUG': 'process.env.DEBUG',
              })
            ]
          }
        },
      }
    }
  ],

[nicobistolfi]

@Sakura-pgh you made my day ⭐

[Zenahr]

I solved the problem by changing this in docusaurus.config.js

plugins: [
    ...
    async function customPlugin(context, opts) {
      return {
        name: 'custom-plugin',
        configureWebpack(config, isServer, utils, content) {
          // Modify internal webpack config. If returned value is an Object, it
          // will be merged into the final config using webpack-merge;
          // If the returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
          return {
            plugins: [
              new webpack.DefinePlugin({
                // IMPORTANT: To fix debug library‘s bug
                // {}.DEBUG = namespaces; // SyntaxError: Unexpected token '.'
                'process.env.DEBUG': 'process.env.DEBUG',
              })
            ]
          }
        },
      }
    }
  ],

@Sakura-pgh Thank you SO MUCH. You've helped me tremendously in 2024. I was already debugging this issue for 2 days before stumbling on your comment.