From b0783ae0b25e05550416b44825b39b39133b93c1 Mon Sep 17 00:00:00 2001 From: Pedro Cattori Date: Wed, 26 Apr 2023 21:47:48 -0400 Subject: [PATCH] docs(unstable_dev): add docs for setting up new dev server --- docs/pages/v2.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 179 insertions(+), 2 deletions(-) diff --git a/docs/pages/v2.md b/docs/pages/v2.md index 62c933d0b8d..ce7fad89de6 100644 --- a/docs/pages/v2.md +++ b/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 +// +import { broadcastDevReady } from "@remix-run/node"; + +// Path to Remix's server build directory ('build/' by default) +let BUILD_DIR = path.join(process.cwd(), "build"); + +// + +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 ` | +| 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