From 473ef3a5ece1a6c476eb70a65a4fbde67ef9979c Mon Sep 17 00:00:00 2001 From: Dan Abramov Date: Fri, 2 Sep 2016 20:35:46 +0100 Subject: [PATCH] Disable implicit serving of the source files (#551) * Disable contentBase in development * Document #428 --- scripts/start.js | 17 ++++++++++++++ template/README.md | 58 ++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 71 insertions(+), 4 deletions(-) diff --git a/scripts/start.js b/scripts/start.js index 9880330b1c..32d90d4cdc 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 cb3d197818..9dbada654f 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