diff --git a/README.md b/README.md index ec24d939774..741536a0584 100644 --- a/README.md +++ b/README.md @@ -138,6 +138,7 @@ The [User Guide](https://github.com/facebookincubator/create-react-app/blob/mast - [Making a Progressive Web App](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#making-a-progressive-web-app) - [Deployment](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#deployment) - [Advanced Configuration](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#advanced-configuration) +- [Server-side Rendering](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#server-side-rendering) - [Troubleshooting](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#troubleshooting) A copy of the user guide will be created as `README.md` in your project folder. @@ -165,7 +166,7 @@ Please refer to the [User Guide](https://github.com/facebookincubator/create-rea * Autoprefixed CSS, so you don’t need `-webkit` or other prefixes. * A `build` script to bundle JS, CSS, and images for production, with sourcemaps. -**The feature set is intentionally limited**. It doesn’t support advanced features such as server rendering or CSS modules. The tool is also **non-configurable** because it is hard to provide a cohesive experience and easy updates across a set of tools when the user can tweak anything. +**The feature set is intentionally limited**. It doesn’t support advanced features such as CSS modules. The tool is also **non-configurable** because it is hard to provide a cohesive experience and easy updates across a set of tools when the user can tweak anything. **You don’t have to use this.** Historically it has been easy to [gradually adopt](https://www.youtube.com/watch?v=BF58ZJ1ZQxY) React. However many people create new single-page React apps from scratch every day. We’ve heard [loud](https://medium.com/@ericclemmons/javascript-fatigue-48d4011b6fc4) and [clear](https://twitter.com/thomasfuchs/status/708675139253174273) that this process can be error-prone and tedious, especially if this is your first JavaScript build stack. This project is an attempt to figure out a good way to start developing React apps. @@ -183,7 +184,6 @@ You don’t have to ever use `eject`. The curated feature set is suitable for sm Some features are currently **not supported**: -* Server rendering. * Some experimental syntax extensions (e.g. decorators). * CSS Modules. * Importing LESS or Sass directly ([but you still can use them](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-a-css-preprocessor-sass-less-etc)). diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md index 147c9280e24..6b63afe2c6c 100644 --- a/packages/react-scripts/template/README.md +++ b/packages/react-scripts/template/README.md @@ -76,6 +76,7 @@ You can find the most recent version of this guide [here](https://github.com/fac - [S3 and CloudFront](#s3-and-cloudfront) - [Surge](#surge) - [Advanced Configuration](#advanced-configuration) +- [Server-side Rendering](#server-side-rendering) - [Troubleshooting](#troubleshooting) - [`npm start` doesn’t detect changes](#npm-start-doesnt-detect-changes) - [`npm test` hangs on macOS Sierra](#npm-test-hangs-on-macos-sierra) @@ -1562,6 +1563,28 @@ HTTPS | :white_check_mark: | :x: | When set to `true`, Create React App will run PUBLIC_URL | :x: | :white_check_mark: | Create React App assumes your application is hosted at the serving web server's root or a subpath as specified in [`package.json` (`homepage`)](#building-for-relative-paths). Normally, Create React App ignores the hostname. You may use this variable to force assets to be referenced verbatim to the url you provide (hostname included). This may be particularly useful when using a CDN to host your application. CI | :large_orange_diamond: | :white_check_mark: | When set to `true`, Create React App treats warnings as failures in the build. It also makes the test runner non-watching. Most CIs set this flag by default. +## Server-side Rendering + +Create React App has limited support for server-side rendering. The production build is generated as a [UMD module](http://davidbcalhoun.com/2014/what-is-amd-commonjs-and-umd/), which means it can be loaded as a CommonsJS module, an AMD module, or as a global variable. The AMD module name and global variable name is derived from the project name in `package.json`, by turning it into a camel-cased version. For example, 'my-app' becomes 'myApp', and '@org/our-app' becomes 'orgOurApp'. This module can then be used to render static markup on the server. + +Since the production build generates files with a hash in the name, before you can load the bundle you first need to look up the name in `asset-manifest.json`. For example, in a NodeJS app: + +```js +const manifest = require('./build/asset-manifest.json'); +const bundleName = manifest['main.js']; +``` + +When you generate a project with `create-react-app`, `src/index.js` includes an example rendering function as the default export. In a NodeJS app, you might load the bundle and call the render function as following. You then would need to build the final, complete HTML page and send it to the client. + +```js +const renderApp = require(`./build/${bundleName}`).default; +const bodyHtml = renderApp(); +``` + +You can change the render function however you like, e.g. to add Redux or react-router, and pass any parameters to the render function that you need. Please keep in mind that server-side rendering is not a primary goal of Create React App, and only the out-of-the-box configuration is supported. In particular, if you are using code-splitting then you will have to eject since the Webpack target is "web", which won't work on the server chunks are loaded with JSONP. You'll need to generate a [second Webpack config](https://webpack.js.org/concepts/targets/#multiple-targets) with e.g. a "node" target. + +If you're not interested in server-side rendering, feel free to delete the render function from `src/index.js`. + ## Troubleshooting ### `npm start` doesn’t detect changes