diff --git a/packages/react-scripts/template/README.md b/packages/react-scripts/template/README.md
index 25b469fb680..2d174167225 100644
--- a/packages/react-scripts/template/README.md
+++ b/packages/react-scripts/template/README.md
@@ -44,6 +44,7 @@ You can find the most recent version of this guide [here](https://github.com/fac
 - [Proxying API Requests in Development](#proxying-api-requests-in-development)
   - ["Invalid Host Header" Errors After Configuring Proxy](#invalid-host-header-errors-after-configuring-proxy)
   - [Configuring the Proxy Manually](#configuring-the-proxy-manually)
+  - [Configuring a WebSocket Proxy](#configuring-a-websocket-proxy)
 - [Using HTTPS in Development](#using-https-in-development)
 - [Generating Dynamic `<meta>` Tags on the Server](#generating-dynamic-meta-tags-on-the-server)
 - [Pre-Rendering into Static HTML Files](#pre-rendering-into-static-html-files)
@@ -982,6 +983,36 @@ You may also narrow down matches using `*` and/or `**`, to match the path exactl
 }
 ```
 
+### Configuring a WebSocket Proxy
+
+When setting up a WebSocket proxy, there are a some extra considerations to be aware of.
+
+If you’re using a WebSocket engine like [Socket.io](https://socket.io/), you must have a Socket.io server running that you can use as the proxy target. Socket.io will not work with a standard WebSocket server. Specifically, don't expect Socket.io to work with [the websocket.org echo test](http://websocket.org/echo.html).
+
+There’s some good documentation available for [setting up a Socket.io server](https://socket.io/docs/).
+
+Standard WebSockets **will** work with a standard WebSocket server as well as the websocket.org echo test. You can use libraries like [ws](https://github.com/websockets/ws) for the server, with [native WebSockets in the browser](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
+
+Either way, you can proxy WebSocket requests manually in `package.json`:
+
+```js
+{
+  // ...
+  "proxy": {
+    "/socket": {
+      // Your compatible WebSocket server
+      "target": "ws://<socket_url>",
+      // Tell http-proxy-middleware that this is a WebSocket proxy.
+      // Also allows you to proxy WebSocket requests without an additional HTTP request
+      // https://github.com/chimurai/http-proxy-middleware#external-websocket-upgrade
+      "ws": true
+      // ...
+    }
+  }
+  // ...
+}
+```
+
 ## Using HTTPS in Development
 
 >Note: this feature is available with `react-scripts@0.4.0` and higher.