docs(unstable_dev): add docs for setting up new dev server

docs/pages/v2.md

@@ -696,9 +696,186 @@ In your `remix.config.js`, you should specify either `serverModuleFormat: "cjs"`
 
 ## Dev Server
 
-We are still stabilizing the new dev server that enables HMR, several CSS libraries (CSS Modules, Vanilla Extract, Tailwind, PostCSS) and simplifies integration with various servers.
+The new dev server works with _any_ app server and brings support for HMR and Hot Data Revalidation.
 
-We expect a stable `v2_dev` flag in Remix `v1.16.0`. Once that ships, we'll have more instructions here to prepare your app for v2.
+To get started, enable the `unstable_dev` future flag in `remix.config.js`:
+
+```js
+{
+  future: {
+    "unstable_dev": true
+  }
+}
+```
+
+#### Remix App Server
+
+Make sure you are calling `remix dev` in your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "remix dev"
+  }
+}
+```
+
+#### Other app servers
+
+If you have a custom script for your app server, specify how to run your app server with the `-c`/`--command` flag.
+
+For example, to use an Express app server located at `./server.js`:
+
+```json
+{
+  "scripts": {
+    "dev": "remix dev -c 'node ./server.js'"
+  }
+}
+```
+
+Then, call `broadcastDevReady` when your app server is up and running.
+
+For example, in our `./server.js` Express server:
+
+```js
+// <other imports>
+import { broadcastDevReady } from "@remix-run/node";
+
+// Path to Remix's server build directory ('build/' by default)
+let BUILD_DIR = path.join(process.cwd(), "build");
+
+// <code setting up your express server>
+
+app.listen(3000, () => {
+  let build = require(BUILD_DIR);
+  console.log("Ready: http://localhost:" + port);
+
+  // in development, call `broadcastDevReady` _after_ your server is up and running
+  if (process.env.NODE_ENV === "development") {
+    broadcastDevReady(build);
+  }
+});
+```
+
+### Run
+
+```sh
+npm run dev
+```
+
+Then, visit your app server's URL in your browser and start coding!
+
+### Configuration
+
+Configuration priority order is:
+
+1. flags
+2. config
+3. defaults
+
+| Option         | flag               | config           | default                           |
+| -------------- | ------------------ | ---------------- | --------------------------------- |
+| Command        | `-c` / `--command` | `command`        | `remix-serve <server build path>` |
+| HTTP(S) scheme | `--http-scheme`    | `httpScheme`     | `http`                            |
+| HTTP(S) host   | `--http-host`      | `httpHost`       | `localhost`                       |
+| HTTP(S) port   | `--http-port`      | `httpPort`       | Dynamically chosen open port      |
+| Websocket port | `--websocket-port` | `websocketPort`  | Dynamically chosen open port      |
+| No restart     | `--no-restart`     | `restart: false` | `restart: true`                   |
+
+Most users will only need to specify the app server command with `-c`.
+See the _Advanced_ sections below for use-cases of the other options.
+
+### Advanced: No restart
+
+By default, the dev server will restart your app server everytime a rebuild succeeds.
+That way your app server will reboot with all the updated server code.
+
+If you'd rather handle server updates yourself, you can use the `--no-restart` flag:
+
+```json
+{
+  "scripts": {
+    "dev": "remix dev -c 'node ./server.js' --no-restart"
+  }
+}
+```
+
+For example, you could purge the `require` cache of your app server to keep it running while picking up server changes.
+If you do so, you should watch the server build path (`build/` by default) for changes and only purge the `require` cache when changes are detected.
+
+You will also need to call `broadcastDevReady` when your server has picked up the changes.
+
+For example, with `chokidar`:
+
+```js
+// server.dev.js
+const BUILD_PATH = path.resolve(__dirname, "build");
+
+const watcher = chokidar.watch(BUILD_PATH);
+
+watcher.on("change", () => {
+  // 1. purge require cache
+  purgeRequireCache();
+  // 2. load updated server build
+  const build = require(BUILD_PATH);
+  // 3. tell dev server that this app server is now ready
+  broadcastDevReady(build);
+});
+```
+
+### Advanced: Custom scheme/host/port
+
+If you need to set up SSL or Docker networking, you want to explicitly set the dev server's HTTP(s) origin.
+
+Use the `--http-port` and `--websocket-port` flags to force those port numbers to be used:
+
+```json
+{
+  "scripts": {
+    "dev": "remix dev -c 'node ./server.js' --http-port=8001 --websocket-port=8002"
+  }
+}
+```
+
+You can also specify the HTTP(S) scheme and host for the dev server:
+
+```json
+{
+  "scripts": {
+    "dev": "remix dev -c 'node ./server.js' --http-scheme=https --http-host=mycustomhost"
+  }
+}
+```
+
+🚨 Remix **will not** set up HTTPS and custom host for you 🚨
+
+You will need to set up the certificates and hosts files.
+The `--http-scheme` and `--http-port` options are just for you to tell Remix where the dev server will end up running.
+The other options tell Remix _what to do_, but these two tell Remix _what you've done_.
+
+### Migrating from old dev server
+
+If you are using `remix dev` _without_ enabling `unstable_dev`, you are using the old dev server.
+
+To upgrade, you'll need a dedicated app server for development.
+You can use the Remix App Server for that purpose:
+
+```sh
+npm i -D @remix-run/serve
+```
+
+Then, enable the `unstable_dev` future flag in `remix.config.js`:
+
+```js
+{
+  future: {
+    "unstable_dev": true
+  }
+}
+```
+
+That's it!
 
 [future-flags]: ./api-development-strategy
 [remix-config]: ../file-conventions/remix-config