Documentation does not seem to provide much insight on what is an idiomatic way to write packages like what file extension to use how to build and publish to allow others consume your packages without needing to customize their configurations.

I will just assume that setup used by graphql-js is an idiomatic way to go about it:

• Author source in src/ directory as module.js files.
• Use babel to transpile to plain JS.
• Publish to npm.

Problem with such setup is that users of my library loose all of the type information that original source contained. There are ways to workaround it but they either require flow configuration on the consumer side or non trivial build step from the publisher side.

Proposal

I would like to propose following things to improve current situation & grow number of flow typed packages distributed over npm.

1. Documentation should certainly include a guide on how to author and publish flow typed package.
2. I would suggest to make module.flow an idiomatic file extension for flow typed files. For following reasons:
   1. Flow extends JS syntax so sharing same file extensions does not really makes sense.
   2. If you author files flow code in module.js you can't really generate compiled JS files alongside of them.
3. In 0.19 introduced useful feature, that allows putting module.js.flow along the side of module.js in which case flow would give precedence to module.js.flow over module.js when importing ./module. Unfortunately no attempt to load module.flow is made. It would actually make sense to alter algorithm slightly so that flow would try module.flow then module.js.flow and then module.js which in fact would match node's algorithm more closely which attempts to load module and then module.js.

This would enable users to author their packages in module.flow files and then compile all module.flow files to module.js files along the side them. Publishing such package into npm also would preserve all the type information for consumers, since flow would first look for dep/module.flow (which will be an original source) before dep/module.js.

Note: Technically you could achieve more or less same even if your flow code was authored in module.js files but that would require copying and renaming them to module.js.flow which as far as I can tell has no trivial cross platform solution & requiring extra scripts isn't great. Another alternative is to just author code as module.js.flow and generate module.js files, it's just authoring in .js.flow file extension seems awkward.