Feedback and frustrations from a newbie

[avaragado]

  @nrwl/angular : Not Found
  @nrwl/cli : 9.2.2
  @nrwl/cypress : 9.2.2
  @nrwl/eslint-plugin-nx : 9.2.2
  @nrwl/express : Not Found
  @nrwl/jest : 9.2.2
  @nrwl/linter : 9.2.2
  @nrwl/nest : Not Found
  @nrwl/next : Not Found
  @nrwl/node : 9.2.2
  @nrwl/react : 9.2.2
  @nrwl/schematics : Not Found
  @nrwl/tao : 9.2.2
  @nrwl/web : 9.2.2
  @nrwl/workspace : 9.2.2
  typescript : 3.8.3

I'm a complete newbie to nx, evaluating it for possible adoption at work for our React apps. Previously I've built and maintained build configs across multiple repos manually and would very much like to stop doing that, so nx looks ideal.

I've hit some issues, mostly related to the learning curve. One problem stopped me dead for several hours. I've since resolved that problem but I want to report the frustrations to help you improve the developer experience (thanks to @juristr for prompting me). I realise it's incredibly difficult for those intimately familiar with a project to see things from the perspective of a novice, so I'll go into some depth.

Some background: we use a private 'assets' package containing purely static PNGs. The assets package has a build process that transforms large SVG files to smaller PNGs. At the moment, when the SVGs change we rebuild, version-bump, and republish this package (to a private registry) so our other packages can consume it and import the images as necessary. I wanted to use this as a proof-of-concept for nx.

I'll use bullets to highlight the issues I've had, roughly as I encountered them.

• More information on how to deal with assets in nx would be useful. Searching the docs for 'assets' returns https://nx.dev/react/guides/adding-assets-react, which is helpful but doesn't cover things like:

  • What file types exactly do you support? "Images" is imprecise. This is a trivial but illustrative point: you're relying on shared assumptions to describe your functionality. You don't mention JPEG or GIF, but I assume they're supported. If I want to know the reality as opposed to my assumptions, I need to read your source code.
  • Can I change the 10 kB threshold for inlining? How? If I search the docs for 'webpack' I get no results.

• In workspace.json I noticed an assets configuration setting. This led me to https://nx.dev/react/plugins_web_builders/build which describes assets as a "List of static application assets" but could usefully tell me what nx does with them, how I might reference them in my code, best practices, etc. (Why didn't this page appear in the search results for "assets", I wonder?)

• That same file also mentions webpackConfig, which I might want to use if we need to change the 10 kB threshold: "Path to a function which takes a webpack config, some context and returns the resulting webpack config". What context is this referring to? (Again, this didn't appear in search results for 'webpack', or 'webpackConfig'.) The specific definition of context here doesn't matter: the general point is that most of these descriptions lack crucial information, and to learn that information I'd end up googling and searching your issues and reading your source code.

Regardless, it seems these things relate to static assets: probably not solving my problem. It looked like I needed some kind of library, with a build step driven through nx. @FrozenPandaz hinted this way: https://twitter.com/FrozenPandaz/status/1251213646593753089

I was unsure which would be best: a workspace library, a node library, or a react library. I ended up choosing a node library, which might be wrong. (Right now I was thinking: this is day one and I seem to be bumping at the edges of what nx is comfortable managing.)

• It would be great to improve the descriptions and help people choose the best schematic for their use case. The doc is sparse, and seems to be written assuming you already understand the details:

  • https://nx.dev/react/plugins_workspace_schematics/library: "Create a library"
  • https://nx.dev/react/plugins_react_schematics/library: "Create a library"
  • https://nx.dev/react/plugins_node_schematics/library: "Create a library"

• Almost every page in the React-oriented docs has an "Important" banner telling me I can use JS instead of TS with a simple flag to nx g. This smells to me like a related issue, because the page describing nx generate, https://nx.dev/react/cli/generate, doesn't mention this flag at all. I'm left thinking: what else is missing from this page?

• https://nx.dev/react/plugins_workspace/nrwl-workspace-overview says "Create a plain typescript library". I wasn't sure why this isn't part of a" typescript" plugin, given that node libraries have a "node" plugin. I'm not sure I'd have looked in a section called "Workspace" for a TypeScript library.

• Niggle: in https://nx.dev/react/plugins_workspace/nrwl-workspace-overview all the links go to Angular-related pages.

I found the run-commands builder, which looked relevant, then created my library and managed to get something building, and figured out how to use tsconfig.json's paths to map the scoped library name to a filesystem path. I had everything working.

Then (due to a dumb change I made) it stopped working, and I started to see error messages in builds that made no sense to me:

ERROR in ./app/app.tsx
Module not found: Error: Can't resolve '@myscope/mylibrary' in '/Users/.../src/app'

Linting showed no errors. nx serve worked fine. Renaming the scoped library name in both tsconfig.json and the app made it work; renaming it back made it stop working. Using nx g move to change the library's name made it work; renaming it back made it stop working. Commenting out the build target for the library made it work; uncommenting made it stop working. I started delving into caches, killing and restarting processes, and rebooting, in case something in nx or TypeScript or webpack had come loose. None of that worked.

The mists started to clear when I manually patched the nx webpack config inside node_modules to get some more debug out: in particular, setting logLevel on tsconfig-paths-webpack-plugin to INFO. It was at this point I discovered that nx passes the plugin a massaged tsconfig.json file in which the paths have been changed to somewhere else in the filesystem: specifically, it seems, the outputPath defined in the run-commands configuration (which I hadn't set). The module couldn't be found because that massaged path wasn't the path I was using for my built files. That, tied with the change I made, caused the error. Sure, you can blame it on my change, but the best tools anticipate and help me recover from my own stupidity.

• The doc for outputPath is: 'Tells Nx where the files will be created' (https://nx.dev/react/plugins_workspace_builders/run-commands). It would be great to explain why this matters, and what the default is.

Some additional, unrelated feedback:

• Violation of principle of least surprise: I would expect nx build xxx to build xxx and its dependencies. This is the most likely scenario. https://nx.dev/react/cli/build says "Compiles an application [...]" and that certainly implies dependencies. To include dependencies I need to use --with-deps, but that option isn't documented on that page, nor does it appear in nx build --help. (You could argue "nx build does exactly what it says it does" which is true, but I suggest it's surprising to devs.) I recommend updating the doc to be explicit that it doesn't build dependencies, and to mention --with-deps.

• Longer term, you might want to consider distinguishing high-level from low-level commands: The high-level commands are those people will use often, and in CI. For example, it seems I'm far more likely to use nx affected:build than nx build, but affected:build looks like a lower-level command than build. It feels like nx build should by a high-level command to "do the right thing" by default: build everything that needs building (similar to Makefiles).

• Similarly, when pages like https://nx.dev/react/cli/serve say nx serve <project> is just sugar for nx run <project>:serve I think: nx run is a low-level command that I probably won't use regularly; it's probably not the first thing I need to know when I'm trying to understand what nx serve does.

• Talking of nx affected:

  • nx affected:apps lists apps affected by changes
  • nx affected:libs lists libs affected by changes
  • nx affected lists everything affec-- oh, no, it doesn't. It outputs a usage string. That was a surprise. Is there a way to list everything affected by changes? nx print-affected outputs a bunch of JSON.

• The tutorial is great. I think it needs an extra section on deployments, since that's not really covered. Among other things it would explain what's built under dist and in what structure, and what I need to care about there. For example, there's an nxdeps.json file. Is it important, eg for CI?

OK, that's where I'm at right now. I like nx, it solves a real problem, but I have concerns.

One of the major worries I have about adopting nx -- or any other "we take care of everything!" solution -- is troubleshooting. When I own all the config I suffer the pain but I can also "easily" add debug, tweak settings to make output more verbose, etc. When the tooling owns the config, it needs to treat troubleshooting as a first-class problem. I shouldn't need to understand how the tooling is implemented, and manually modify it under node_modules, to add debug.

The other main worry is broadly "customization": think webpack, babel, typescript, even eslint and prettier, but also any time I might need something a little off-beam. Ideally it wouldn't be necessary; in reality, it is. Guides to customization would be extremely useful. With a large monorepo sprinkled with dozens of tsconfig files, eslint files, etc, it would be good to have some guidance on what I can safely change and what I should leave alone -- especially, what will break nx if I modify it. Plus, how I can debug when things go wrong, as they inevitably will.

I appreciate this is a long post full of multiple issues and rambling, and negativity. Thanks for this project, and thanks for reading.

[avaragado]

This is about to drop off the first page of issues. Is any of it valid, invalid, on the list, the result of a huge and embarrassing misunderstanding on my part...?

[FrozenPandaz]

Thank you for the thorough and detailed feedback! The team is hard at work revising our docsite to provide the best experience and we are specifically taking this feedback into consideration while doing so!

I agree, different technologies have many definitions of what an "asset" is and we need to be more specific when talking about the following:

• Static Assets that are copied into the dist
• Resources that are injected into the code such as svg

I don't think you should be embarassed at all to have misunderstandings and I am very grateful that you were comfortable expressing this to us. Feedback like this is extremely valuable for us to provide better documentation. Sorry for the delayed response. FWIW, we discussed this internally shortly after it was posted.

@isaacplmann can we please updates here when we make changes to the documentation that clarifies this?

[isaacplmann]

I definitely appreciate the feedback on the docs. Just last week, Ben added full-text search to nx.dev, which would help with a couple of your pain points.

I also plan to improve several sections of the docs because of your feedback. Specifically:

• A document helping people choose which kind of library to generate
• Make --with-deps more prominent
• Provide examples of different ways to customize your workspace

[avaragado]

Thanks both. I saw full-text search had been added - that certainly helps, thank you.

[montogeek]

Thanks for the feedback, I spend yesterday and today migrating a Lerna monorepo to nx, CLI is wonderful, but docs are lacking a lot of surprises and small details. Thanks for the --with-deps flag!

Right now I am for example finding how to customize rollup config for a lib so I can do import { ReactComponent as comp} from "path.svg", docs says that you can import them like that, but that only works on apps, not on libs.

[isaacplmann]

@montogeek that sounds like it needs to be reported as an issue so that we can take a look at it.

If you could provide some of the surprises/details that are missing that would help us improve the docs. Also, we're always open to PRs that help improve the docs.

[montogeek]

Yep, I plan to improve the docs and also features.

[sushruth]

Somewhat relevant issue here #3131

[airtonix]

yeah nx.dev feels like an amazing thing i should be using.... but it also makes me feel like I'm probably not going to acheive what I want in any reasonable commercially viable time frame.

It would be great to have more examples... my particular focus is:

• create a react app that doesn't export a html file, but is actually used as <script src="https://my-cdn/the-app--umd.js"></script>
• create a plain html app (no javascript) that is a demo that uses the first point.
• when the second point is built, it should build the first and then change the html to reference the resulting path of the first.

[isaacplmann]

@airtonix thanks for the suggestion. I'll add that to my list of ideas for guides to write.

If you figure it out and would like to contribute a guide, I'm happy to help you with the PR process.

[github-actions[bot]]

This issue has been automatically marked as stale because it hasn't had any recent activity. It will be closed in 14 days if no further activity occurs. If we missed this issue please reply to keep it active. Thanks for being a part of the Nx community! 🙏

[github-actions[bot]]

This issue has been closed for more than 30 days. If this issue is still occuring, please open a new issue with more recent context.