The Remix CLI comes from the @remix-run/dev
package. It also includes the compiler. Make sure it is in your package.json
devDependencies
so it doesn't get deployed to your server.
To get a full list of available commands and flags, run:
npx @remix-run/dev -h
remix build
Builds your app for production. This command will set process.env.NODE_ENV
to production
and minify the output for deployment.
remix build
Option | flag | config | default |
---|---|---|---|
Generate sourcemaps for production build | --sourcemap |
N/A | false |
remix dev
Builds your app and spins up the Remix dev server alongside your app server.
The dev server will:
NODE_ENV
to development
🎥 For an introduction and deep dive into HMR and HDR in Remix, check out our videos:
What is "Hot Data Revalidation"?
Like HMR, HDR is a way of hot updating your app without needing to refresh the page. That way you can keep your app state as your edits are applied in your app. HMR handles client-side code updates like when you change the components, markup, or styles in your app. Likewise, HDR handles server-side code updates.
That means any time your change a loader
on your current page (or any code that your loader
depends on), Remix will re-fetch data from your changed loader.
That way your app is always up-to-date with the latest code changes, client-side or server-side.
To learn more about how HMR and HDR work together, check out Pedro's talk at Remix Conf 2023.
remix-serve
Enable the v2 dev server:
/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
future: {
v2_dev: true,
},
};
That's it!
If you used a template to get started, hopefully it has integration with the v2 dev server out-of-the-box.
If not, you can follow these steps to integrate your project with v2_dev
:
/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
future: {
v2_dev: true,
},
};
package.json
and use -c
to specify your app server command:{
"dev": "remix dev -c \"node ./server.js\""
}
broadcastDevReady
is called when your app server is up and running:import path from "node:path";
import { broadcastDevReady } from "@remix-run/node";
import express from "express";
const BUILD_DIR = path.resolve(__dirname, "build");
const build = require(BUILD_DIR);
const app = express();
// ... code for setting up your express app goes here ...
app.all(
"*",
createRequestHandler({
build,
mode: process.env.NODE_ENV,
})
);
const port = 3000;
app.listen(port, () => {
console.log(`👉 http://localhost:${port}`);
if (process.env.NODE_ENV === "development") {
broadcastDevReady(build);
}
});
For CloudFlare, use logDevReady
instead of broadcastDevReady
.
Why? broadcastDevReady
uses fetch
to send a ready message to the dev server,
but CloudFlare does not support async I/O like fetch
outside of request handling.
Options priority order is: 1. flags, 2. config, 3. defaults.
Option | flag | config | default | description |
---|---|---|---|---|
Command | -c / --command |
command |
remix-serve <server build path> |
Command the dev server will run to spin up your app server |
Manual | --manual |
manual |
false |
See guide for manual mode |
Port | --port |
port |
Dynamically chosen open port | Internal port used for hot updates |
TLS key | --tls-key |
tlsKey |
N/A | TLS key for configuring local HTTPS |
TLS certificate | --tls-cert |
tlsCert |
N/A | TLS certificate for configuring local HTTPS |
To set options in your config, replace v2_dev: true
with an object.
For example:
/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
future: {
v2_dev: {
// ...any other options you want to set go here...
manual: true,
tlsKey: "./key.pem",
tlsCert: "./cert.pem",
},
},
};
The remix dev --port
option sets the internal port used for hot updates.
It does not affect the port your app runs on.
To set your app server port, set it the way you normally would in production.
For example, you may have it hardcoded in your server.js
file.
If you are using remix-serve
as your app server, you can use its --port
flag to set the app server port:
remix dev -c "remix-serve --port 8000 ./build"
In contrast, the remix dev --port
option is an escape-hatch for users who need fine-grain control of network ports.
Most users, should not need to use remix dev --port
.
By default, remix dev
will restart your app server whenever a rebuild occurs.
If you'd like to keep your app server running without restarts across rebuilds, check out our guide for manual mode.
If you are using a monorepo, you might want Remix to perform hot updates not only when your app code changes, but whenever you change code in any of your apps dependencies.
For example, you could have a UI library package (packages/ui
) that is used within your Remix app (packages/app
).
To pick up changes in packages/ui
, you can configure watchPaths to include your packages.
To use Mock Service Worker in development, you'll need to:
remix dev
will provide the REMIX_DEV_ORIGIN
environment variable for use in your app server.
For example, if you are using binode to integrate with MSW,
make sure that the call to binode
is within the remix dev -c
subcommand.
That way, the MSW server will have access to the REMIX_DEV_ORIGIN
environment variable:
{
"scripts": {
"dev": "remix dev -c \"npm run dev:app\"",
"dev:app": "binode --require ./mocks -- @remix-run/serve:remix-serve ./build"
}
}
Next, you can use REMIX_DEV_ORIGIN
to let MSW forward internal "dev ready" messages on /ping
:
import { rest } from "msw";
const REMIX_DEV_PING = new URL(
process.env.REMIX_DEV_ORIGIN
);
REMIX_DEV_PING.pathname = "/ping";
export const server = setupServer(
rest.post(REMIX_DEV_PING.href, (req) => req.passthrough())
// ... other request handlers go here ...
);
For this example, let's use mkcert. After you have it installed, make sure to:
NODE_EXTRA_CA_CERTS
for Node compatibilitymkcert -install # create a local CA
export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" # tell Node to use our local CA
Now, create the TLS key and certificate:
mkcert -key-file key.pem -cert-file cert.pem localhost
👆 You can change localhost
to something else if you are using custom hostnames.
Next, use the key.pem
and cert.pem
to get HTTPS working locally with your app server.
This depends on what you are using for your app server.
For example, here's how you could use HTTPS with an Express server:
import fs from "node:fs";
import https from "node:https";
import path from "node:path";
import express from "express";
const BUILD_DIR = path.resolve(__dirname, "build");
const build = require(BUILD_DIR);
const app = express();
// ... code setting up your express app goes here ...
const server = https.createServer(
{
key: fs.readFileSync("path/to/key.pem"),
cert: fs.readFileSync("path/to/cert.pem"),
},
app
);
const port = 3000;
server.listen(port, () => {
console.log(`👉 https://localhost:${port}`);
if (process.env.NODE_ENV === "development") {
broadcastDevReady(build);
}
});
Now that the app server is set up, you should be able to build and run your app in production mode with TLS. To get the dev server to interop with TLS, you'll need to specify the TLS cert and key you created:
remix dev --tls-key=key.pem --tls-cert=cert.pem -c "node ./server.js"
Alternatively, you can specify the TLS key and cert via the v2_dev.tlsCert
and v2_dev.tlsKey
config options.
Now your app server and dev server are TLS ready!
Let's say you have the app server and dev server both running on the same machine:
http://localhost:1234
http://localhost:5678
Then, you setup a reverse proxy in front of the app server and dev server:
https://myhost
But the internal HTTP and WebSocket connections to support hot updates will still try to reach the dev server's unproxied origin:
http://localhost:5678
/ ws://localhost:5678
❌To get the internal connections to point to the reverse proxy, you can use the REMIX_DEV_ORIGIN
environment variable:
REMIX_DEV_ORIGIN=https://myhost remix dev
Now, hot updates will be sent correctly to the proxy:
https://myhost
/ wss://myhost
✅Currently, when Remix rebuilds your app, the compiler has to process your app code along with any of its dependencies. The compiler treeshakes unused code from app so that you don't ship any unused code to browser and so that you keep your server as slim as possible. But the compiler still needs to crawl all the code to know what to keep and what to treeshake away.
In short, this means that the way you do imports and exports can have a big impact on how long it takes to rebuild your app. For example, if you are using a library like Material UI or AntD you can likely speed up your builds by using path imports:
- import { Button, TextField } from '@mui/material';
+ import Button from '@mui/material/Button';
+ import TextField from '@mui/material/TextField';
In the future, Remix could pre-bundle dependencies in development to avoid this problem entirely. But today, you can help the compiler out by using path imports.
Dependending on your app and dependencies, you might be processing much more code than your app needs. Check out our bundle analysis guide for more details.
Hot Module Replacement is supposed to keep your app's state around between hot updates.
But in some cases React cannot distinguish between existing components being changed and new components being added.
React needs key
s to disambiguate these cases and track changes when sibling elements are modified.
Additionally, when adding or removing hooks, React Refresh treats that as a brand-new component.
So if you add useLoaderData
to your component, you may lose state local to that component.
These are limitations of React and React Refresh, not Remix.
Hot Data Revalidation detects loader changes by trying to bundle each loader and then fingerprinting the content for each. It relies on tree shaking to determine whether your changes affect each loader or not.
To ensure that tree shaking can reliably detect changes to loaders, make sure you declare that your app's package is side effect free:
{
"sideEffects": false
}
When you delete a loader or remove some of the data being returned by that loader, your app should be hot updated correctly. But you may notice console errors logged in your browser.
React strict-mode and React Suspense can cause multiple renders when hot updates are applied. Most of these render correctly, including the final render that is visible to you. But intermediate renders can sometimes use new loader data with old React components, which is where those errors come from.
We are continuing to investigate the underlying race condition to see if we can smooth that over. In the meantime, if those console errors bother you, you can refresh the page whenever they occur.
When the v2 dev server builds (and rebuilds) your app, you may notice a slight slowdown as the dev server needs to crawl the dependencies for each loader. That way the dev server can detect loader changes on rebuilds.
While the initial build slowdown is inherently a cost for HDR, we plan to optimize rebuilds so that there is no perceivable slowdown for HDR rebuilds.