As of Flow 0.4.0, you can put your Flow-specific syntax in special comments. If you use these special comments then you do not need to transform away Flow-specific syntax before running your code. While we strongly recommend that you write your code without the special comments, this feature will help people who can't fit a Flow-stripping transformation into their setup. This was one of our most requested features and hopefully it will enable even more people to use Flow!
This feature introduces 3 special comments: /*:, /*::, and /*flow-include. Flow will read the code inside these special comments and treat the code as if the special comment tokens didn't exist. These special comments are valid JavaScript block comments, so your JavaScript engine will ignore the code inside the comments.
The Flow Comment Syntax
There are 3 special comments that Flow currently supports. You may recognize this syntax from Jarno Rantanen's excellent project, flotate.
1. /*:
/*: <your code> */ is interpreted by Flow as : <your code>
function foo(x/*: number*/)/* : string */ { ... }
is interpreted by Flow as
function foo(x: number): string { ... }
but appears to the JavaScript engine (ignoring comments) as
function foo(x) { ... }
2. /*::
/*:: <your code> */ is interpreted by Flow as <your code>
/*:: type foo = number; */
is interpreted by Flow as
type foo = number;
but appears to the runtime (ignoring comments) as
3. /*flow-include
/*flow-include <your code> */ is interpreted by Flow as <your code>. It behaves the same as /*::
/*flow-include type foo = number; */
is interpreted by Flow as
type foo = number;
but appears to the runtime (ignoring comments) as
Note: whitespace is ignored after the /* but before the :, ::, or flow-include. So you can write things like
/* : number */
/* :: type foo = number */
/* flow-include type foo = number */
Future Work
We plan to update our Flow transformation to wrap Flow syntax with these special comments, rather than stripping it away completely. This will help people write Flow code but publish code that works with or without Flow.
Thanks
Special thanks to Jarno Rantanen for building flotate and supporting us merging his syntax upstream into Flow.