diff --git a/scripts/start.js b/scripts/start.js
index 9880330b1ce..32d90d4cdc3 100644
--- a/scripts/start.js
+++ b/scripts/start.js
@@ -221,6 +221,23 @@ function addMiddleware(devServer) {
function runDevServer(port) {
var devServer = new WebpackDevServer(compiler, {
+ // By default WebpackDevServer also serves files from the current directory.
+ // This might be useful in legacy apps. However we already encourage people
+ // to use Webpack for importing assets in the code, so we don't need to
+ // additionally serve files by their filenames. Otherwise, even if it
+ // works in development, those files will be missing in production, unless
+ // we explicitly copy them. But even if we copy the all the files into
+ // the build output (which doesn't seem to be wise because it may contain
+ // private information such as files with API keys, for example), we would
+ // still have a problem. Since the filenames would be the same every time,
+ // browsers would cache their content, and updating file content would not
+ // work correctly. This is easily solved by importing assets through Webpack
+ // because if it can then append content hashes to filenames in production,
+ // just like it does for JS and CSS. And because we configured "html" loader
+ // to be used for HTML files, even would
+ // get resolved correctly by Webpack and handled both in development and
+ // in production without actually serving it by that path.
+ contentBase: [],
// Enable hot reloading server. It will provide /sockjs-node/ endpoint
// for the WebpackDevServer client so it can learn when the files were
// updated. The WebpackDevServer client is included as an entry point
diff --git a/template/README.md b/template/README.md
index cb3d1978188..9dbada654f7 100644
--- a/template/README.md
+++ b/template/README.md
@@ -24,7 +24,9 @@ You can find the most recent version of this guide [here](https://github.com/fac
- [Adding Custom Environment Variables](#adding-custom-environment-variables)
- [Integrating with a Node Backend](#integrating-with-a-node-backend)
- [Proxying API Requests in Development](#proxying-api-requests-in-development)
-- [Adding `` Tags](#adding-meta-tags)
+- [Adding `` and `` Tags](#adding-link-and-meta-tags)
+ - [Referring to Static Assets from ``](#referring-to-static-assets-from-link-href)
+ - [Generating Dynamic `` Tags on the Server](#generating-dynamic-meta-tags-on-the-server)
- [Running Tests](#running-tests)
- [Filename Conventions](#filename-conventions)
- [Command Line Interface](#command-line-interface)
@@ -526,11 +528,59 @@ If the `proxy` option is **not** flexible enough for you, alternatively you can:
* Enable CORS on your server ([here’s how to do it for Express](http://enable-cors.org/server_expressjs.html)).
* Use [environment variables](#adding-custom-environment-variables) to inject the right server host and port into your app.
-## Adding `` Tags
+## Adding `` and `` Tags
-You can edit the generated `index.html` and add any tags you’d like to it. However, since Create React App doesn’t support server rendering, you might be wondering how to make `` tags dynamic and reflect the current URL.
+You can edit the generated `index.html` and add any tags you’d like to it.
-To solve this, we recommend to add placeholders into the HTML, like this:
+### Referring to Static Assets from ``
+
+>Note: this feature is available with `react-scripts@0.3.0` and higher.
+
+Sometimes, you might want to refer to static assets from `index.html`. Create React App intentionally does not support serving static assets from a folder because it is too easy to forget to arrange cache invalidation for their filenames. Instead, we recommend that all assets are [handled as part of build process with `import`s](#adding-images-and-fonts).
+
+However, you can’t `import` anything from an HTML file. This is why Create React App automatically treats any `` attributes that start with `./` as a hint that this file needs to be included in the build process. For example, you can use paths like this in `index.html`:
+
+```html
+
+
+
+
+```
+
+Webpack will parse those `` attributes and replace them with real paths.
+In production, they will become:
+
+```html
+
+
+
+
+```
+
+For this to work, **make sure to specify paths relatively** so don’t forget the `./`:
+
+```html
+
+
+
+
+
+
+
+
+```
+
+Files starting with `./` in `` attribute will be copied to the `static` folder inside your `build` output, and HTML will reference them instead. Webpack will throw a compilation error if any of these files was accidentally deleted or misspelled.
+
+Their names will also contain the content hashes to make sure the browser cache is busted when the file changes. The only file that is handled specially is `favicon.ico` which, if present and referenced from HTML, will be always placed at the root so that browsers can find it even when requesting files from the server (such as PDF documents).
+
+Currently, only `` attributes are treated this way. If you need similar support for other HTML tags and attributes, please file an issue describing your use case.
+
+If you need to use an asset from code rather than from HTML, please read [Adding Images and Fonts](#adding-images-and-fonts).
+
+### Generating Dynamic `` Tags on the Server
+
+Since Create React App doesn’t support server rendering, you might be wondering how to make `` tags dynamic and reflect the current URL. To solve this, we recommend to add placeholders into the HTML, like this:
```html