flow experience needs a lot of work around flowconfig and flow-typed

[indigoviolet]

This is not going to be a very specific bug report, and I'm sure none of this will be a surprise to the flow team, but despite that I believe it is worth re-emphasizing. No disrespect is intended!

I'm a big fan of flow's core feature set - which is awesome - but the developer experience around it can really use a lot of improvement. Some of the notably painful things I've encountered in a couple years of using flow over several projects (with pretty smart developers who are motivated to use flow):

• Setting up a flowconfig on a project can be extremely frustrating. Specifically, the module.name_mapper module.system.node.resolve_dirname options are quite poorly documented (eg https://github.com/facebook/flow/issues/5180 and related issues), have surprising and opaque behavior. It is surprisingly difficult to teach flow the structure of a project (woe betide you if you have a slightly weird shared folder at a different level from your flowconfig or something), and the unable to resolve module errors are not very helpful to fix them (e.g I just struggled with one problem where a bad module.file_ext call was hiding some important modules). Flow's configuration for these unfortunately has very little in common with the other tools that do similar things (eg. webpack).

• It's really easy to get into a broken state where it looks like flow is working and there are no errors, but it's actually your flowconfig that's broken. This is pretty damaging to developer trust, and a huge pain to recover from. We've resorted to constructing a broken file in CI and verifying that flow breaks with that expected error, but I'm not sure that is sufficient.

• flow-typed is just not there IMO. I recognize how incredibly difficult this problem is, of getting all the major libraries typed and keeping them up to date - but at the same time, flow is only achieving some small fraction of its potential benefit in the current situation. Adding a flow-typed library will probably add hundreds of errors into your codebase, making it quite an unattractive proposition, and then it will randomly break and be wrong in many situations.

• A corollary of the previous point: I bet most developers have no idea what fraction of their codebase is well typed. The gradual typing premise makes a lot of sense, but it then falls to flow to guide developers to completion. flow needs to do a lot more to (a) demonstrate to users how much type information is missing (b) how to fill in the gaps in the most efficient way - for example, which modules are the biggest blind spots; how to quickly add visibility without having to fix everything, but still fix things when they are touched.

Flow is such an awesome tool, I really hope that it grows out of these limitations so that people can take full advantage of its potential. Much love and thanks for the work that has gone into this!

[jbrown215]

This is really good feedback. Thank you!

Adding a flow-typed library will probably add hundreds of errors into your codebase

There is an incremental solution here, where you can add the library and suppress the errors. At that point, you have the same coverage as you had before, but you can incrementally get rid of the suppressions to increase your coverage. The tool named tool at the root of this repo can be used to automatically suppress all errors with a message. Try running ./tool add-comments --help for more information on usage.

I bet most developers have no idea what fraction of their codebase is well typed

This sounds like a really useful metric to have! Unfortunately we don't have anyone with time to work on it right now, but I really hope we do have this capability at some point.

[ArmorDarks]

I'm very appreciative about what Flow team doing. Flow seems like a great thing. But all that said is true, unfortunately.

Flow-typed didn't work well for us too. I have a strong feeling that there should be a better way to distribute, consume, and what is very important, use, extend and override already defined typing within libraries instead of consuming flow-typed. Because I must assure that flow-typed is a kind of a hell to maintain and for the library developer and for the consumer.

Inability to extend and override already declared typings is extremely troublesome. For instance, some Vue-related packages trying to build better typings for the Vue libraries, but since they can't consume and extend already existing Vue typings in flow-typed, they just forced to copy them by hand.

Another extreme pain point is development on Windows. Not only Flow is significantly slower on Windows, but it carries extreme bugs for months! And the main plugin for VS Code flow-for-vscode due to Windows-related issues is unusable too, and nothing changes for months.