docusaurus react integration

[baj1210]

while this is a great project that creates a beautiful stand alone documentation website, it would be even more useful if docusaurus could be used within an exisiting react app that inherits any layout or styles already provisioned in the react app.

Most documentation websites are part of a larger project - the docs/ endpoint is typically part of a larger project that the documentation pertains to.

A standalone documentation site deployed to gitpages or some other 3rd party site is not as helpful as the ability to create documentation for an exisiting project hosted at any domain.

Right now it seems the only way to have docusaurus exist alongside an exisiting react application is to build the docusaurus site and then embed the build/ directory assets within an iframe...

or to create a subdirectory that points to /docs as a standalone react app.

Both of those options aren't ideal. Since docusaurus is built upon react anyway, would it be too much effort to provide a docusaurus-react library that can be imported and used within an exisiting react project so that components and pages could be built that flow seamlessly into the structure of the react application?

[slorber]

Docusaurus is a React framework, and not meant to be embedded into another framework.

Making Docusaurus a plugin to another framework would be complex, and it's likely that we'd only have the bandwidth to support one integration (for example Astro, Next.js or Remix).

We considered that but I'm not sure it's the direction we want to take, considering the complexity to make it work on a single framework, not even mentioning making it work on multiple frameworks.

Also there are already existing solutions covering this:

• Astro already has Starlight
• Next.js has Nextra + Fumadocs.

---

If you want:

• / main site using Next.js, Remix, Astro, CRA, custom...
• /docs Docusaurus site

You don't need an iframe for that, just use baseUrl: '/docs/' in Docusaurus and use your CDN features (such as URL rewrites) to serve the build from example.com/docs. Many sites integrate Docusaurus that way.

Or build your Docusaurus site and then copy the build output to your main site's static/docs folder. But it's better to have 2 distinct CDN deployments and "assemble" them with CDN features. All CDNs support that: Vercel, Netlify, Cloudflare, AWS Cloudfront...

You can also have a docs.example.com subdomain.

[baj1210]

This makes sense - I was not aware of these exisiting solutions that integrate with other frameworks (astro looks interesting).

I'm not using a CDN, but plan to self-host.

I actually spent quite a bit of time attempting to force docusaurus into my existing project. I did change the baseUrl to /docs/ and noticed it then duplicated the docs/ pattern in the url so the example classic theme urls were being routed as localhost:3000/docs/docs/intro/ localhost:3000/docs/docs/tutorial/ etc...

This was probably user error.

The motivation for my proposal was due to the fact that I have a React app at endpoint / and building the docusaurus static site at endpoint /docs created a scenario where I could not link to the /docs from my React app like a typical multipage site without leaving the React app entirely with an external link to /docs that takes the user to a completely different application - with no convenient way of retaining a layout that might bring the user back to the / React app endpoint when they are done reading the documentation.

I tried webpacking and bundling the build directory and collecting all the html, js, and css into a single bundle.js file that I could inject into a react component that I can route to in my app, and this was a bad idea that did not work.

I realized that docusaurus has it's own webpack logic that is under the hood and conflicts with other tools. I tried picking apart the source code, and seeing if I could strip out the vanilla react components from the "framework" but I quickly found myself trapped inside the jaws of Docusaurus Rex as the terrible lizard shredded me alive between rows of razor sharp typescript teeth...

It's a complex codebase for sure.

Somewhere in there, there's a plain React App whose components might form the pieces of the solution I had hoped for, but it's not obvious.

I also noticed that building docusaurus site creates hundreds of [hash].js files under assets/js. I assume that is due to all the plugins?

[slorber]

We don't support having main app at / and Docusaurus at /docs as a single application, that would be very complex to achieve unfortunately. It shouldn't be a big deal if you have 2 applications, the transition from one to another could be relatively seamless even though the layout and logic (auth etc) is not exactly the same.

See for example Figma:

• This is not Docusaurus: https://www.figma.com/developers
• This is Docusaurus: https://www.figma.com/plugin-docs

If your React app is already complex, you'd probably want to isolate your app from the docs on purpose. After all, would you want to build both app every time someone fixes a typo in your docs? You also have to consider the time it takes to deploy the app and the docs.

The hash files are related to Webpack code splitting, not plugins.

[baj1210]

"After all, would you want to build both app every time someone fixes a typo in your docs?"

I'm really glad we had this discussion because I would have only discovered that quirk the hard way. You've convinced me. Thanks for taking the time to explain things