Question about createData and JSON file

[osseonews]

We are using an external CMS for some data. I was reading the docs to understand the functionality of createData in the async contentLoaded plugin API. I see that you can create a JSON file with that and it's stored in the .docusaurus folder for that plugin. I also saw alot of discussions about getting content from an external API and the different approaches suggested. The approach we took was to use the createData to create a JSON file from data we get from the CMS in loadContent() function. We then import that data in a React component, like below and then just use that data as we need to:

import Data from '@site/.docusaurus/{{pluginName}}/default/data.json';

Is there anything wrong with this approach? I didn't see this in any code examples. Usually it seems like the JSON data is passed to some component as a prop when running addRoute in the API, but is there is anything wrong with just importing the JSON file in a component, when it's not used in a route? I haven't seen any issues doing it this way, and just wondering why this is not a recommended approach in many instances, because the ability to create JSON files on build is a very helpful feature.

[Josh-Cena]

We then import that data in a React component, like below and then just use that data as we need to:

There's virtually none, for your own use case. This is what usePluginData basically does under the hood. The only thing that comes to mind at this moment is you are coupling your theme component to a plugin name and a plugin ID, but that's almost a non-concern for private usage.

[slorber]

To be honest I have never been a fan of createData. First it doesn't handle name conflicts automatically, and forces you to choose a name/path when you just want to inject data in a component as React props.

That's why I plan to improve the plugin API over time, starting with route.props support in v3.3: #10042

export default function friendsPlugin(context, options) {
  return {
    name: 'docusaurus-friends-plugin',
    async contentLoaded({content, actions}) {
      actions.addRoute({
        path: '/friends',
        component: '@site/src/components/Friends.js',
        exact: true,
        props: {
		  friends: ['Yangshun', 'Sebastien']
        }
      });
    },
  };
}

It is also possible that we'll introduce another method such as createModule(json) that wouldn't require a name (eventually we could pass an optional one as a hint to make it easier to inspect/debug files on the filesystem, and maybe we'll only use this in docusaurus start and docusaurus build --dev, but not docusaurus build). And it's also possible that we automatically add a hash in the filename for optimization reasons.

---

Back to your case:

import Data from '@site/.docusaurus/{{pluginName}}/default/data.json';

Yes that would work, you can also do this BTW:

import Data from '@generated/{{pluginName}}/default/data.json';

But as @Josh-Cena said you are coupling to the json path.

Note that doing this does not give you any advantage over just using fs.writeFile. You could also download your CMS data ahead of the Docusaurus build as a pre-build step, and put that json data anywhere you want.

So, that's fine to use createData atm, but I can't guarantee this API will never disappear. In any case if we remove it some day, it wouldn't be hard to replace it with your own fs calls.

[osseonews]

Thanks. Do you have any examples of using fs.writefile to do this, I wasn't aware you could use this in a plugin. Also, by downloading CMS data ahead of time, you mean putting something in the package.json before the docusaurus command?

[slorber]

I don't have a particular example using fs.writeFile, it is a standard Node API with tons of examples online, nothing is specific to Docusaurus itself.

You can just create a node script and run node downloadCMSData.js && yarn docusaurus build, that would work. Do whatever you want in downloadCMSData.js to generate the json files you need to import in your Docusaurus site.

[osseonews]

Alright thanks. I actually took a look at the sitemaps plugin and the code there worked for my use case also. Thanks!