DocsPreferredVersionContextProvider error when launching page.

[Babilinski]

Description

Docusaurus site versions 2.0.0-beta.16 and 2.0.0-beta.15 do not work with the typesense search plugin. Starting page after configuring the website results in the following error .

This page crashed.
Can't find docs preferred context, maybe you forgot to use the "DocsPreferredVersionContextProvider"?

Steps to reproduce

After creating a new docusaurus site using the command on their getting started page:

npx create-docusaurus@latest my-website classic

Adding "docusaurus-theme-search-typesense": "^0.3.0", to the dependencies section in the package.json file

Installing the plugin using

 npm install --legacy-peer-deps

and configuring my config.js file I launch my website using npm run start and see the following error

This page crashed.
Can't find docs preferred context, maybe you forgot to use the "DocsPreferredVersionContextProvider"?

Expected Behavior

Website should load and search bar should be present.

Actual Behavior

Website crashes

Metadata

Typsense Version: docusaurus-theme-search-typesense": "^0.3.0"

OS: Windows and Mac

[Babilinski]

This is the config file for the docusaurus site

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

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

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'My Site',
  tagline: 'Dinosaurs are cool',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  themes: ['docusaurus-theme-search-typesense'],
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          editUrl: 'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      }),
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: 'My Site',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
        },
        items: [
          {
            type: 'doc',
            docId: 'intro',
            position: 'left',
            label: 'Tutorial',
          },
          {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/facebook/docusaurus',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Docs',
            items: [
              {
                label: 'Tutorial',
                to: '/docs/intro',
              },
            ],
          },
          {
            title: 'Community',
            items: [
              {
                label: 'Stack Overflow',
                href: 'https://stackoverflow.com/questions/tagged/docusaurus',
              },
              {
                label: 'Discord',
                href: 'https://discordapp.com/invite/docusaurus',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/docusaurus',
              },
            ],
          },
          {
            title: 'More',
            items: [
              {
                label: 'Blog',
                to: '/blog',
              },
              {
                label: 'GitHub',
                href: 'https://github.com/facebook/docusaurus',
              },
            ],
          },
        ],
        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
      },
      typesense: {
      typesenseCollectionName: 'typesense', // Replace with your own doc site's name. Should match the collection name in the scraper settings.
      
      typesenseServerConfig: {
        nodes: [
          {
            host: 'host.docker.internal',
            port: 8108,
            protocol: 'http',
          },
        ],
        apiKey: 'xyz', //insert admin key here
      },

      // Optional: Typesense search parameters: https://typesense.org/docs/0.21.0/api/documents.md#search-parameters
      typesenseSearchParameters: {},

      // Optional
      contextualSearch: false, //should be true, but turned it off to see if this was the source of the "context" bug
    },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;

[Babilinski]

This is the packge.json file

{
  "name": "my-website",
  "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"
  },
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.16",
    "@docusaurus/preset-classic": "2.0.0-beta.16",
    "@mdx-js/react": "^1.6.22",
    "docusaurus-theme-search-typesense": "^0.3.0",
    "clsx": "^1.1.1",
    "prism-react-renderer": "^1.2.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  },
  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

[jasonbosco]

@Babilinski I've run into this issue once before when using npm link to test the plugin locally, but I've not seen it when installing from npm (strange I know).

I've reached out to the docusaurus team to see if they have any thoughts on this.

[Josh-Cena]

Hi, this is very likely a dependency deduplicating problem. You have theme-classic and theme-typesense that both depend on theme-common, and the latter exports the DocsPreferredVersionContextProvider. If the packages fail to deduplicate, there will be two copies of theme-common in the node_modules tree, and theme-typesense will import an empty context that's not filled by theme-classic.

Could you try deleting node_modules and lock file and reinstalling?

[jasonbosco]

@Josh-Cena Thank you for that pointer about duplicate instances in the node_modules tree. I tried to clear node_modules and the lock file in both theme-typesense and in my docusaurus testground. But I still saw the same error.

I then moved @docusaurus/core and @docusaurus/theme-common from dependencies to peerDependencies in the theme's package.json and the error went away and the search bar was rendered as expected! I only added those two packages to dependencies instead of peerDependencies because I saw that's how the Algolia theme was structured. Is it ok to move them to peer dependencies or could something else in the plugin architecture break with this change?

Side note: @Babilinski I've published this change in 0.4.0-0. Could you give it a shot now?

[Josh-Cena]

I suspect it's fine. It's indeed bad practice to rely on package hoisting, but we don't want the users to install theme-common either.

Moving theme-common to peer dependencies is not ideal, maybe even worse. Yarn berry dictates that every peer dependency be provided by its direct ancestor (as a hard dependency, or relaying it as peer dependency), not some other random package in the tree. Which means if a user installs both preset-classic and theme-typesense, the two packages either both declare theme-common as hard dependency, or they require the user to install theme-common. There unfortunately doesn't exist a good way (that I can think of) to fix this behavior without introducing errors elsewhere.

Is theme-common hoisted to the root in your repro? Or is it in node_modules/@docusaurus/theme-classic/node_modules/@docusaurus/theme-common or something like that?

[jasonbosco]

I see theme-common in the root node_modules directory:

$ tree -d -L 1 node_modules/@docusaurus/
node_modules/@docusaurus/
|-- core
|-- cssnano-preset
|-- logger
|-- mdx-loader
|-- module-type-aliases
|-- plugin-content-blog
|-- plugin-content-docs
|-- plugin-content-pages
|-- plugin-debug
|-- plugin-google-analytics
|-- plugin-google-gtag
|-- plugin-sitemap
|-- preset-classic
|-- react-loadable
|-- theme-classic
|-- theme-common
|-- theme-search-algolia
|-- theme-translations
|-- types
|-- utils
|-- utils-common
`-- utils-validation

22 directories

[Josh-Cena]

I mean, it's certainly at the root (that's the default behavior of package managers), but it could also be non-deduped in theme-typesense...

[jasonbosco]

By "it could also be non-deduped in theme-typesense" I'm guessing you meant add theme-common as a direct dependency of theme-typesense?

If so, given that adding theme-common to dependencies in theme-typesense causes the DocsPreferredVersionContextProvider error (when used with other themes), I was wondering if we should ask users to directly install theme-common in their docusaurus site, so it's shared between all themes? But you mentioned:

we don't want the users to install theme-common either

Any particular reason we don't want users to do this?

[Josh-Cena]

Because the fewer packages we ask users to install, the better :D I would need to inspect this later.

[augustluhrs]

Hello! I work with @Babilinski and can confirm that the above fix got our theme to work correctly. thanks so much!

[jmccann]

Just want to be sure what the workarounds for this are currently.

It seems I could "fork" this project and modify some of its dependencies that should work with 2.0.0-beta.16? Is that the only workaround for now? (per #10 (comment)) ... seems this approach isn't a good long term solution though?

Are there any other thoughts/tricks I can do in my site's own package.json to get around this?

[Josh-Cena]

Could people encountering this issue give their package manager? It could be due to differing behaviors between package managers.

[jasonbosco]

I was able to replicate the original issue with both yarn and npm.