Remix CLI

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

Options

remix dev

Runs the Remix compiler in watch mode and spins up your app server.

The Remix compiler will:

1. Set NODE_ENV to development
2. Watch your app code for changes and trigger rebuilds
3. Restart your app server whenever rebuilds succeed
4. Send code updates to the browser via Live Reload and HMR + Hot Data Revalidation

🎥 For an introduction and deep dive into HMR and HDR in Remix, check out our videos:

• HMR and Hot Data Revalidation 🔥
• Mental model for the new dev flow 🧠
• Migrating your project to v2 dev flow 🚚

With custom app server

If you used a template to get started, hopefully it's already integrated with remix dev out-of-the-box. If not, you can follow these steps to integrate your project with remix dev:

1. Replace your dev scripts in package.json and use -c to specify your app server command:

   {
     "scripts": {
       "dev": "remix dev -c \"node ./server.js\""
     }
   }
   

2. Ensure 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: build.mode,
     })
   );
   
   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 Remix compiler, but CloudFlare does not support async I/O like fetch outside of request handling.

Options

Options priority order is: 1. flags, 2. config, 3. defaults.

For example:

/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
  dev: {
    // ...any other options you want to set go here...
    manual: true,
    tlsKey: "./key.pem",
    tlsCert: "./cert.pem",
  },
};

Setting a custom port

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/index.js"

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.

Manual mode

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.

You can see if app server restarts are a bottleneck for your project by comparing the times reported by remix dev:

• rebuilt (Xms) 👉 the Remix compiler took X milliseconds to rebuild your app
• app server ready (Yms) 👉 Remix restarted your app server, and it took Y milliseconds to start with the new code changes

Pick up changes from other packages

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.

How to set up MSW

To use Mock Service Worker in development, you'll need to:

1. Run MSW as part of your app server
2. Configure MSW to not mock internal "dev ready" messages to the Remix compiler

Make sure that you are setting up your mocks for your app server within the -c flag so that the REMIX_DEV_ORIGIN environment variable is available to your mocks. For example, you can use NODE_OPTIONS to set Node's --require flag when running remix-serve:

{
  "scripts": {
    "dev": "remix dev -c \"npm run dev:app\"",
    "dev:app": "cross-env NODE_OPTIONS=\"--require ./mocks\" 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 ...
);

How to integrate with a reverse proxy

Let's say you have the app server and Remix compiler both running on the same machine:

• App server 👉 http://localhost:1234
• Remix compiler 👉 http://localhost:5678

Then, you set up a reverse proxy in front of the app server:

• Reverse proxy 👉 https://myhost

But the internal HTTP and WebSocket connections to support hot updates will still try to reach the Remix compiler's unproxied origin:

• Hot updates 👉 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:

• Hot updates 👉 https://myhost / wss://myhost ✅

Performance tuning and debugging

Path imports

Currently, when Remix rebuilds your app, the compiler has to process your app code along with any of its dependencies. The compiler tree-shakes 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 tree shake 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.

Debugging bundles

Depending 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.

Troubleshooting

HMR: React Fast Refresh Limitations

React Fast Refresh does not preserve state for class components. This includes higher-order components that internally return classes:

export class ComponentA extends Component {} // ❌

export const ComponentB = HOC(ComponentC); // ❌ won't work if HOC returns a class component

export function ComponentD() {} // ✅
export const ComponentE = () => {}; // ✅
export default function ComponentF() {} // ✅

Function components must be named, not anonymous, for React Fast Refresh to track changes:

export default () => {}; // ❌
export default function () {} // ❌

const ComponentA = () => {};
export default ComponentA; // ✅

export default function ComponentB() {} // ✅

React Fast Refresh can only handle component exports. While Remix manages special route exports like meta, links, and header for you, any user-defined, will cause full reloads:

// these exports are specially handled by Remix to be HMR-compatible
export const meta = { title: "Home" }; // ✅
export const links = [
  { rel: "stylesheet", href: "style.css" },
]; // ✅
export const headers = { "Cache-Control": "max-age=3600" }; // ✅

// these exports are treeshaken by Remix, so they never affect HMR
export const loader = () => {}; // ✅
export const action = () => {}; // ✅

// This is not a Remix export, nor a component export
// so it will cause a full reloads for this route
export const myValue = "some value"; // ❌

export default function Route() {} // ✅

👆 Routes probably shouldn't be exporting random values like that anyway. If you want to reuse values across routes, stick them in their own non-route module:

export const myValue = "some value";

React Fast Refresh cannot track changes for a component when hooks are being added or removed from it, causing full reloads just for the next render. After the hooks has been added, changes should result in hot updates again. For example, if you add useLoaderData to your component, you may lose state local to that component for that render.

In some cases React cannot distinguish between existing components being changed and new components being added. React needs keys to disambiguate these cases and track changes when sibling elements are modified.

These are all limitations of React and React Refresh, not Remix.

HDR: every code change triggers HDR

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
}

HDR: harmless console errors when loader data is removed

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.

HDR: performance

When the Remix compiler builds (and rebuilds) your app, you may notice a slight slowdown as the compiler needs to crawl the dependencies for each loader. That way Remix 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.