Error when using symlinked docs folder: Module parse failed: Assigning to rvalue

[kewp]

🐛 Bug Report

Tried to run the 'classic' template following the getting started steps https://v2.docusaurus.io/docs/installation

npx @docusaurus/init@next init my-website classic

Failed when running npm run start. Lots of errors. (only showing partial log)

c:\Users\karl\firkin-www>npm run start

> [email protected] start c:\Users\karl\firkin-www
> docusaurus start

Starting the development server...

× Client
  Compiled with some errors in 3.36s

i ｢wds｣: Project is running at http://localhost:3000/
i ｢wds｣: webpack output is served from /
i ｢wds｣: Content not from webpack is served from c:\Users\karl\firkin-www
i ｢wds｣: 404s will fallback to /index.html


c:/users/karlp/firkin-www/docs/doc1.md 1:2
Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: doc1
| title: Style Guide
 @ c:/users/karlp/firkin-www/.docusaurus/registry.js 1:3494-3536 1:3394-3471
 @ c:/users/karlp/firkin-www/node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ c:/users/karlp/firkin-www/.docusaurus/routes.js
 @ c:/users/karlp/firkin-www/node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi c:/users/karlp/firkin-www/node_modules/react-dev-utils/webpackHotDevClient.js c:/users/karlp/firkin-www/node_modules/@docusaurus/core/lib/client/clientEntry.jsc:/users/karlp/firkin-www/docs/doc2.md 1:2
Module parse failed: Assigning to rvalue (1:2)

Your Environment

• Docusaurus version used: 2.0.0-alpha.61
• Environment name and version: node 12.8.3
• Operating system and version: Windows 10

[slorber]

I have no idea what's going on but it works for me.

Can someone reproduce this consistently?
Maybe it's specific to your env (like Windows only bug? I don't have Windows).

Can you try with yarn instead of npm? (both works for me)

Have you modified anything at all of the generated project?

Are you sure you are in the correct directory? I see you created my-website, yet the logs show you are in firkin-www

[kewp]

Hey @slorber

I just tried this on another machine (also Windows) and it worked fine. So you may be right - it might just be my env.

To answer your questions, though - I didn't modify anything in the generated project. And I was in the correct directory (the initial command using my-website was wrong).

[slorber]

Ok great to know.

Not sure what I can do about this issue, so I'm closing, but let's reopen it if other users are affected and we get more info.

[limkinZero]

Hi @slorber

I`m trying to use version feature with docusaurus v2 (2.0.0-alpha.61) and get the same error:

× Client
  Compiled with some errors in 150.24ms



./versioned_docs/version-1.1.0/doc1.md 1:2
Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: doc1
| title: Style Guide
 @ ./.docusaurus/registry.js 1:4301-4368 1:4145-4253
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/react-dev-utils/webpackHotDevClient.js ./node_modules/@docusaurus/core/lib/client/clientEntry.js./versioned_docs/version-1.1.0/doc2.md 1:2
Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: doc2
| title: Document Number 2
 @ ./.docusaurus/registry.js 1:4746-4813 1:4590-4698
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/react-dev-utils/webpackHotDevClient.js ./node_modules/@docusaurus/core/lib/client/clientEntry.js./versioned_docs/version-1.1.0/doc3.md 1:2
Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: doc3
| title: This is Document Number 3
 @ ./.docusaurus/registry.js 1:5373-5440 1:5218-5325
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/react-dev-utils/webpackHotDevClient.js ./node_modules/@docusaurus/core/lib/client/clientEntry.js./versioned_docs/version-1.1.0/mdx.md 1:2
Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: mdx
| title: Powered by MDX
 @ ./.docusaurus/registry.js 1:5809-5875 1:5657-5762
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/react-dev-utils/webpackHotDevClient.js ./node_modules/@docusaurus/core/lib/client/clientEntry.js

[slorber]

Hi,

Can you give us more infos on your env?

Are you both on Windows?

Wonder if you use a fs path with spaces in it or something? That can lead to issues sometimes.

[CyborgMaster]

I'm running into the same issue, when trying to use files that a symlink in from another directory. Are you aware of any issues with symlinks?

My errors look like this

../idl/docs/md/all.mdx 1:2
Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: all.proto
| title: All
 @ ./.docusaurus/registry.js 1:4050-4105 1:3886-4014
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/react-dev-utils/webpackHotDevClient.js ./node_modules/@docusaurus/core/lib/client/clientEntry.js../idl/docs/md/bom.mdx 1:2
Module parse failed: Assigning to rvalue (1:2)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
> ---
| id: bom.proto
| title: BOM
 @ ./.docusaurus/registry.js 1:4343-4398 1:4177-4307
 @ ./node_modules/@docusaurus/core/lib/client/exports/ComponentCreator.js
 @ ./.docusaurus/routes.js
 @ ./node_modules/@docusaurus/core/lib/client/clientEntry.js
 @ multi ./node_modules/react-dev-utils/webpackHotDevClient.js ./node_modules/@docusaurus/core/lib/client/clientEntry.js../idl/docs/md/bom_service.mdx 1:2

[CyborgMaster]

It almost seems that docusaurus isn't finding the files and compiling them from markdown into js files? Or maybe webpack can't handle symlinks? I don't have enough background to really say.

[CyborgMaster]

It may have something to do with this webpack/webpack#1643

[kewp]

Yes! @CyborgMaster this is what fixed it for me.

For me, my user folder c:\users\karl is actually a symlink to c:\users\karlp. If I try run npm run start from the symlink folder it fails but it works from the actually one!

I assume what you're thinking is correct - that webpack doesn't understand symbolic links. Somehow some of the files are not being found.

[slorber]

Thanks for reporting this.

Do you think we can do anything about it?

Note we have this resolve.symlinks: true in config (https://webpack.js.org/configuration/resolve/#resolvesymlinks).

By using a local site plugin + configureWebpack you should be able to override any default setting we set, so maybe it's worth checking if you find a final config that works for your usecase?

[kewp]

Not sure how to fix this. I've tried creating a webpack.config.js locally and setting the config you mention, @slorber , but it has no effect. Not sure how to create a local site plugin as you suggest either.

[slorber]

@kewp we don't read any webpack.config.js file.

The doc to create a local plugin is very simple:
https://v2.docusaurus.io/docs/using-plugins#creating-plugins
https://v2.docusaurus.io/docs/lifecycle-apis#configurewebpackconfig-isserver-utils

I think something like that:

module.exports = function(context, options) {
  return {
    name: "custom-docusaurus-plugin",
    configureWebpack(config, isServer, utils) {
      return {
        resolve: {
          symlinks: false
        }
      };
    }
  };
};

[kewp]

Hi @slorber . Yup that worked too :)

[CyborgMaster]

@slorber, that worked for me too. I added the plugin you provided in your comment and now the symlinked files work.

I'm obviously not understanding something here, but it feels completely backwards to me that in order to get docs that are symlinked in to work we have to set resolve symlinks: false in the webpack config. But hey, it works.

Thanks for you help! This may be super specific to our setup so I don't know if it belongs in the docusaurus docs or not, but it was certainly tricky to figure out.

[slorber]

Also saw this webpack setting and found it confusing, but as far as I understand it, true means webpack will try to "replace" the symlink by its real location, not that it will enable some kind of mode that works with symlinks.

I don't know either why in Docusaurus we have symlinks: true exactly, not sure we'll be able to know now

[slorber]

Another issue with this symlinks error: #3579

Maybe we should consider switching symlinks to false by default. Not sure about the impact of this, so we'd rather be prepared to revert if users report bugs after release

[BiosSun]

Set resolve.symlinks: false is works. But when I modify the docs, the local site does not auto refresh and display the new modified content.

In the latest version of watchpack (v2.x), it added a followSymlinks option to solve this problem, but this requires us to upgrade webpack to the latest v5.x version.

[plaurent]

The above workaround does not appear to work any longer. I'm running into the same error now, with docusaurus 2.0.0-beta.0 and symlinks out to ../site/* for my docs, src and static folders, and a plugin configured as above.

Might this be due to the updates to webpack v5.x that have been implemented? Does anyone know of a workaround for the current docusaurus?

[plaurent]

To clarify: the plugin workaround does work for npm run build and serving the static site, but does not work for npm run start.

[slorber]

Maybe worth trying updating the watchOptions.followSymlinks option mentioned by @BiosSun

You can edit the devServerConfig locally at node_modules/docusaurus/lib/commands/start.js and restart your server.

I don't think you can change this with current apis , but maybe the following works?

module.exports = function(context, options) {
  return {
    name: "custom-docusaurus-plugin",
    configureWebpack(config, isServer, utils) {
      return {
        resolve: {
          symlinks: false
        },
        devServer: {
          watchOptions: { followSymlinks: false }
        }
      };
    }
  };
};

[felipecrs]

@slorber it does not seem to work, sadly.

[bravo-kernel]

FWIW I just had the exact same issue after upgrading to 2.0.0-beta.0.

Removing node_modules followed by a yarn install solved it for me.

[silverqx]

I have the same problem and symlinks: false solve it, add this to docusaurus.config.js and you are ready to go on symlinked folders, also HMR works ok 👌:

plugins: [
  function (context, options) {
    return {
      name: 'webpack-configuration-plugin',
      configureWebpack(config, isServer, utils) {
        return {
          resolve: {
            symlinks: false,
          }
        };
      }
    };
  },
],

[slorber]

yes, we can now pass plugins as inline config functions :)

I'm not sure to understand why we have symlink: true in our webpack config anymore, so I think we could just remove that and see if anyone complains. Just be aware that I may have to revert it if any significant bug is reported about that change.

[slorber]

FYI I coudn't find any reason to use symlink: true.
The code introducing this is very old and does not explain this setting (2ab412e)

Going to revert to false in #5126

Using a symlinked folder as source docs seems to work fine (in dev/watchmode + prod)

Using symlinks inside the regular docs folder does not really work, and probably require more work so that features such as auto-generated sidebars etc work as intended.

Do you all have the same use-case to create a single symlink for the root docs folder?

[silverqx]

FYI I coudn't find any reason to use symlink: true.

I see it the same way, users should be able to use symlinked docs folder.

Do you all have the same use-case to create a single symlink for the root docs folder?

I'm going to use it this way, I hope that this was only one problem which I come across. I'm going to use it this way because I want to have documentation to be a part of the main project and create a new repository for the docusaurus.

So I will have two repos, main project eg. xyz and second repo xyz-github.io which will generate documentation with docusaurus and deploy to github.io. xyz-github.io will have symlinked docs folder to xyz/docs folder.

Going to revert to false in #5126

Nice thank you 🙏 For me it makes sense.

[felipecrs]

So I will have two repos, main project eg. xyz and second repo xyz-github.io which will generate documentation with docusaurus and deploy to github.io. xyz-github.io will have symlinked docs folder to xyz/docs folder.

That's very much like my use case as well, just to say.

[slorber]

great, we'll figure out later if using symlinks inside the docs root folder is necessary.

If you have this need please explain your usecase.

I've added a new docs plugin instance using a root symlink so that we keep this behavior working over time. CI builds fine on linux/windows: https://deploy-preview-5126--docusaurus-2.netlify.app/docs-tests

[slorber]

Unfortunately, I have to revert the change I made (#5164).

There is a bug in Webpack 5 caching and using resolve.symlinks: false lead to deploying a Docusaurus site with stale cache entries.

If you implement a Docusaurus plugin as part of a monorepo and change some UI code, your new deployment (dev + prod) may not see your changes. Not many sites will be affected by this in practice (theme components should be fine fine), but it's particularly painful for ourselves: Docusaurus PR Netlify deploy previews show stale UI components.

If you decide to stick to using webpack.resolve.symlinks = false in your site for symlinks reasons, and have some monorepo UI lib symlinked, I recommend to run docusaurus clear to be free of nasty side-effects.

Also, I'm not sure using symlinks: false is a good solution, and webpack contributors do not seem to agree it's a good idea to use false either.

I'd like to recommend another workaround: instead of using symlinks: false, you can try to resolve the symlink to the real location, directly in your config:

    [
      '@docusaurus/plugin-content-docs',
      {
        routeBasePath: 'docs',
        sidebarPath: 'sidebars.js',
        path: fs.realpathSync('docs-symlink'),
      },
    ],

Please let me know if this workaround works for your site.

We'll only try to apply symlinks: false again if some come up with a case where it does not work and we can't find any other solution (repros / linked repos appreciated)

[nitinkatyal1314]

@slorber it does not seem to work, sadly.

Can confirm on this. With { symlink: false} HMR does not work. Tried using the { followsymlinks: true} option in devServer conf, but it does not work as intended. The app recompiles on changes but the browser does not refreshes the content.

FYI - I am not using a docusaurus plugin. Just changing webpack.dev.config.js

[leograba]

If one has a docs multi-instance and wants to share a directory with partials between two docs instances, would the symlink approach work?

[slorber]

@leograba the canary now allows putting mdx docs anywhere (#5299) so you shouldn't need symlinks anymore: just import the mdx files where you want to use them.

However keep in mind the link resolution in those partials is "simpler", it doesn't resolve relative md file paths but only regular relative/abslute links. Also there's a TOC limitation (#3915)

[leograba]

@slorber thanks! I have tested it with the canary release 0.0.0-3900 and it worked well.

About the link resolution, I have previously noticed that that the "simpler" link resolution also affects referring to a different doc in a multi-docs setup, so I've been already using relative links. I'll keep in mind the limitations of relative links instead of relative file paths.

About the TOC, keeping an eye on (#3915) :)

[slorber]

Yes, only the docs plugin resolve relative md file paths currently and it's limited to the scope of a single instance. We need some additional infrastructure so that plugins can expose to each others a filePath => absolute url mapping. But anyway if 2 instances have different version schemes you'd rather avoid such links because it won't play well with versioning, as the versined docs would be in a totally different folders. In such case we'll probably need to support something like [SomeLink](@site/docs/myDoc.md) to make those links easier to version.

[slorber]

The Webpack 5 caching bug should be resolved in webpack/webpack#14019
Using symlinks: false should be safe again in webpack 5.51.0
Let me know how it works for you.