Add Flow instructions and tweak howto

template/README.md

@@ -5,9 +5,42 @@ You can find the most recent version of this guide [here](https://github.com/fac
 
 We are always open to [your feedback](https://github.com/facebookincubator/create-react-app/issues).
 
+## Folder Structure
+
+After creation, you project should look like this:
+
+```
+my-app/
+  README.md
+  index.html
+  favicon.ico
+  node_modules/
+  package.json
+  src/
+    App.css
+    App.js
+    index.css
+    index.js
+    logo.svg
+```
+
+For the project to build, **these files must exist with exact filenames**:
+
+* `index.html` is the page template;
+* `favicon.ico` is the icon you see in the browser tab;
+* `src/index.js` is the JavaScript entry point.
+
+You can delete or rename the other files.
+
+You may create subdirectories inside `src`. For faster rebuilds, only files inside `src` are processed by Webpack.  
+You need to **put any JS and CSS files inside `src`**, or Webpack won’t see them.
+
+You can, however, create more top-level directories.  
+They will not be included in the production build so you can use them for things like documentation.
+
 ## Available Scripts
 
-In this directory, you can run:
+In the project directory, you can run:
 
 ### `npm start`
 
@@ -87,7 +120,7 @@ Learn more about ES6 modules:
 
 ### Add a Stylesheet
 
-This project setup uses [Webpack](https://webpack.github.io/) for handling all assets. Webpack offers a custom way of “extending” the concept of `import` beyond JavaScript. To express that a JavaScript file depends on a CSS file, you need to import it from the JavaScript file:
+This project setup uses [Webpack](https://webpack.github.io/) for handling all assets. Webpack offers a custom way of “extending” the concept of `import` beyond JavaScript. To express that a JavaScript file depends on a CSS file, you need to **import the CSS from the JavaScript file**:
 
 #### `Button.css`
 
@@ -115,7 +148,7 @@ class Button extends Component {
 
 In development, expressing dependencies this way allows your styles to be reloaded on the fly as you edit them. In production, all CSS files will be concatenated into a single minified `.css` file in the build output.
 
-However **you are welcome to ignore it and put all your CSS in `src/index.css` if you prefer so.**   It is imported from `src/index.js`, and you can always remove that import if you migrate to a different build tool.
+If you are concerned about using Webpack-specific semantics, you can put all your CSS right into `src/index.css`. It would still be imported from `src/index.js`, but you could always remove that import if you later migrate to a different build tool.
 
 ### Post-Process CSS
 
@@ -154,7 +187,7 @@ There is currently no support for preprocessors such as Less, or for sharing var
 
 With Webpack, using static assets like images and fonts works similarly to CSS.
 
-You can `import` an image right in a JavaScript. This tells Webpack to include that image in the bundle. The *result* of the import is the image filename from the build output folder.
+You can **`import` an image right in a JavaScript module**. This tells Webpack to include that image in the bundle. Unlike CSS imports, importing an image or a font gives you a string value. This value is the final image path you can reference in your code.
 
 Here is an example:
 
@@ -180,15 +213,67 @@ This works in CSS too:
 }
 ```
 
-Webpack finds all relative module references in CSS (they start with `./`) and replaces them with the final paths from the compiled bundle.
+Webpack finds all relative module references in CSS (they start with `./`) and replaces them with the final paths from the compiled bundle. If you make a typo or accidentally delete an important file, you will see a compilation error, just like when you import a non-existent JavaScript module. The final filenames in the compiled bundle are generated by Webpack from content hashes. If the file content changes in the future, Webpack will give it a different name in production so you don’t need to worry about long-term caching of assets.
+
+Please be advised that this is also a custom feature of Webpack.
+
+**It is not required for React** but many people enjoy it (and React Native uses a similar mechanism for images). However it may not be portable to some other environments, such as Node.js and Browserify. If you prefer to reference static assets in a more traditional way outside the module system, please let us know [in this issue](https://github.com/facebookincubator/create-react-app/issues/28), and we will consider support for this.
+
+### Adding Flow
+
+Flow typing is currently [not supported out of the box](https://github.com/facebookincubator/create-react-app/issues/72) with the default `.flowconfig` generated by Flow. If you run it, you might get errors like this:
+
+```
+node_modules/fbjs/lib/Deferred.js.flow:60
+ 60:     Promise.prototype.done.apply(this._promise, arguments);
+                           ^^^^ property `done`. Property not found in
+495: declare class Promise<+R> {
+     ^ Promise. See lib: /private/tmp/flow/flowlib_34952d31/core.js:495
+
+node_modules/fbjs/lib/shallowEqual.js.flow:29
+ 29:     return x !== 0 || 1 / (x: $FlowIssue) === 1 / (y: $FlowIssue);
+                                   ^^^^^^^^^^ identifier `$FlowIssue`. Could not resolve name
+
+src/App.js:3
+  3: import logo from './logo.svg';
+                      ^^^^^^^^^^^^ ./logo.svg. Required module not found
+
+src/App.js:4
+  4: import './App.css';
+            ^^^^^^^^^^^ ./App.css. Required module not found
+
+src/index.js:5
+  5: import './index.css';
+            ^^^^^^^^^^^^^ ./index.css. Required module not found
+```
+
+To fix this, change your `.flowconfig` to look like this:
+
+```
+[libs]
+./node_modules/fbjs/flow/lib
 
-If you make a typo or accidentally delete an important file, you will see a compilation error, just like when you import a non-existent JavaScript module.
+[options]
+esproposal.class_static_fields=enable
+esproposal.class_instance_fields=enable
 
-The final filenames in the compiled bundle are generated by Webpack from content hashes. If the file content changes in the future, Webpack will give it a different name in production so you don’t need to worry about long-term caching of assets.
+module.name_mapper='^\(.*\)\.css$' -> 'react-scripts/config/flow/css'
+module.name_mapper='^\(.*\)\.\(jpg\|png\|gif\|eot\|svg\|ttf\|woff\|woff2\|mp4\|webm\)$' -> 'react-scripts/config/flow/file'
 
-Please be advised that this is also a custom feature of Webpack. **It is not required for React** but many people enjoy it (and React Native uses a similar mechanism for images). However it may not be portable to some other environments, such as Node.js and Browserify.
+suppress_type=$FlowIssue
+suppress_type=$FlowFixMe
+```
+
+Re-run flow, and you sholdn’t get any extra issues.
+
+If you later `eject`, you’ll need to replace `react-scripts` references with the `<PROJECT_ROOT>` placeholder, for example:
+
+```
+module.name_mapper='^\(.*\)\.css$' -> '<PROJECT_ROOT>/config/flow/css'
+module.name_mapper='^\(.*\)\.\(jpg\|png\|gif\|eot\|svg\|ttf\|woff\|woff2\|mp4\|webm\)$' -> '<PROJECT_ROOT>/config/flow/file'
+```
 
-If you’d prefer to add and reference static assets in a more traditional way outside the module system, please let us know [in this issue](https://github.com/facebookincubator/create-react-app/issues/28), and we will add support for this.
+We will consider integrating more tightly with Flow in the future so that you don’t have to do this.
 
 ### Something Missing?