Back to overview

Super Simple Start to Remix

May 3rd, 2021 14 min read

by Jan Huber
by Jan Huber
No translations available.Add translation

Please keep in mind that this is a "Super Simple Start" article. That means that target audience for this article is people who have experience with Remix and are curious about how the bits and pieces work without all the nice things Remix provides for you out of the box. Because of that, this article might make it seem like Remix is harder to use than it really is. This is not a good article to read if you're just getting started with Remix or want an introduction to it.

I'll write a good beginner's guide article soon.

Remix has me more excited about building better websites than anything else since I started using React back in 2015. I have so much to say about it, but for this blog post, we're going to remove as many distractions as possible and give remix the "super simple start" treatment. So, even though Remix has a fancy npx create-remix@latest thing you can run (which is much easier than what I'm going to show you), we're going to skip that and build a simple remix app from absolutely nothing to running so we can inspect each bit required to get it going.

Before we get started, create a folder for our project. I'm going to be super original and put mine on the desktop with the folder name "super-simple-start-to-remix". Alright, now we're ready to go!

1. Installing Remix

We can install Remix together with the other packages we need to get things started like we always do:

npm install react react-dom
npm install --save-dev @remix-run/dev

2. Configuring Remix

Cool, with those things installed, let's configure Remix. Create a remix.config.js:

module.exports = {}

Yup, that's all you need. The defaults all work fine, but remix won't build without the config file, so we'll create that.

3. Building the app with Remix

Let's add a build script to our package.json:

{
  "scripts": {
    "build": "remix build"
  },
  "dependencies": {
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "devDependencies": {
    "@remix-run/dev": "^1.0.4"
  }
}

Sweet, let's run the build!

npm run build

Building Remix app in production mode...
Missing "entry.client" file in ~/Desktop/super-simple-start-to-remix/app

Ah, yeah, let's add that file:

mkdir app
touch app/entry.client.jsx

And run the build again:

npm run build

Building Remix app in production mode...
Missing "entry.server" file in ~/Desktop/super-simple-start-to-remix/app

Ok, let's add that one:

touch app/entry.server.jsx

And again:

npm run build

Building Remix app in production mode...
Missing "root" file in ~/Desktop/super-simple-start-to-remix/app

Maybe this is the last one?

touch app/root.jsx

Ok, let's run the build one more time:

npm run build

Building Remix app in production mode...
Built in 234ms

Success! Let's check out our file structure now. Here it is pre-build (ignoring node_modules):

.
├── app
│   ├── entry.client.jsx
│   ├── entry.server.jsx
│   └── root.jsx
├── package-lock.json
├── package.json
└── remix.config.js

And once we run npm run build remix creates a few files for us:

.
├── app
│   ├── entry.client.jsx
│   ├── entry.server.jsx
│   └── root.jsx
├── build
│   ├── assets.json
│   └── index.js
├── package-lock.json
├── package.json
├── public
│   └── build
│       ├── _shared
│       │   └── chunk-DH6LPQ4Z.js
│       ├── entry.client-CY7AAJ4Q.js
│       ├── manifest-12E650A9.js
│       └── root-JHXSOSD4.js
└── remix.config.js

Note: Remix supports TypeScript out of the box, but we're keeping this simple. Also, because we plan to use JSX in these files, they need the .jsx extension. Remix uses esbuild which requires a .jsx or .tsx extension if you want to use JSX.

Sweet! We built it... Now what?

4. Coding our Remix App

Remix is a server-side rendering React framework. So far we've just got it compiling things for us. Let's actually get a server running and show something on the screen.

Let's start by filling in the root.jsx with something. This is the root element Remix will render:

import * as React from 'react'

function App() {
  const [count, setCount] = React.useState(0)
  return (
    <html>
      <head>
        <title>My First Remix App</title>
      </head>
      <body>
        <p>This is a remix app. Hooray!</p>
        <button onClick={() => setCount(c => c + 1)}>{count}</button>
      </body>
    </html>
  )
}

export default App

It's neat that we get to render the <html> element right? Yeah, that's cooler than you think it is I promise you.

Ok, next, let's fill in the entry.client.jsx:

import ReactDOM from 'react-dom'
import {RemixBrowser} from 'remix'

ReactDOM.hydrate(<RemixBrowser />, document)

What's that? We're... HYDRATING the document?! How neat is that?!

And finally, let's fill in the entry.server.jsx:

import ReactDOMServer from 'react-dom/server'
import {RemixServer} from 'remix'

function handleRequest(
  request,
  responseStatusCode,
  responseHeaders,
  remixContext,
) {
  const markup = ReactDOMServer.renderToString(
    <RemixServer context={remixContext} url={request.url} />,
  )

  return new Response(`<!DOCTYPE html>${markup}`, {
    status: responseStatusCode,
    headers: {
      ...Object.fromEntries(responseHeaders),
      'Content-Type': 'text/html',
    },
  })
}

export default handleRequest

This one's pretty cool too. So we export a default function that accepts everything we need, and we get to return the response. That Response object is a real Response object (or, at least the node-equivalent of one). Learn more on freaking MDN! (Sorry, I just really love this part of Remix).

I really love how much control we get here. We are in charge of calling renderToString and hydrate. That gives us a lot of power and it also means we don't need to learn extra special APIs Remix made for us and they don't need to make extra-special options to customize any of this, because the control is in our hands. Very cool.

Alright, let's try running the build again!

npm run build

Building Remix app in production mode...
The path "remix" is imported in app/entry.server.jsx but remix is not listed in your package.json dependencies. Did you forget to install it?

 > app/entry.client.jsx:2:27: error: Could not resolve "remix" (mark it as external to exclude it from the bundle)
    2 │ import {RemixBrowser} from 'remix'
~~~~~~~


Build failed with 1 error:
app/entry.client.jsx:2:27: error: Could not resolve "remix" (mark it as external to exclude it from the bundle)
Built in 258ms

Oh, right, we're using the remix package for the RemixBrowser and RemixServer components. Let's install that:

npm install remix

Now let's try the build again:

npm run build

Building Remix app in production mode...

 > node_modules/remix/browser/index.js:11:14: error: Could not resolve "./client"
    11 │ export * from './client';
~~~~~~~~~~

  > node_modules/remix/browser/index.js:12:14: error: Could not resolve "./server"
    12 │ export * from './server';
~~~~~~~~~~

  > node_modules/remix/browser/index.js:13:14: error: Could not resolve "./platform"
    13 │ export * from './platform';
~~~~~~~~~~~~


Build failed with 3 errors:
node_modules/remix/browser/index.js:11:14: error: Could not resolve "./client"
node_modules/remix/browser/index.js:12:14: error: Could not resolve "./server"
node_modules/remix/browser/index.js:13:14: error: Could not resolve "./platform"
Built in 274ms

Ah! What's going on here? Well, the remix package itself is actually rather simple. All it does is act as a sort of "proxy" for the other packages we're going to be using. There's a @remix-run/react for the react-specific stuff. And then there are @remix-run/{adapter} packages that we can use for server-side platform-specific stuff. Currently, here are all the adapters we can use currently:

Deploy anywhere you can ship node and/or a docker container:

  • @remix-run/node
  • @remix-run/express
  • @remix-run/serve

Deploy to specific platforms (serverless etc.):

  • @remix-run/architect
  • @remix-run/vercel
  • @remix-run/netlify
  • @remix-run/cloudflare-workers

More adapters are coming:

The primary thing these adapters do is convert the Request/Response from the platform-specific objects to the Web-standard Request/Response (or a polyfilled version of that).

For our simple app, we're going to use @remix-run/serve which is built on top of @remix-run/express which actually is built on top of @remix-run/node. So this can deploy anywhere you can deploy a node server. The cool thing is that if you want to deploy anywhere else you totally can and you just need to swap out the adapter you're using in the package.json and so long as your own code and other dependencies are supported by the platform, you should be good to go.

So let's install the packages we're going to need.

npm install @remix-run/react @remix-run/serve

Next we need to set up the remix package to act as a proxy for us, so let's run:

npx remix setup node

Successfully setup Remix for node.

Now let's run the build again:

npm run build

Building Remix app in production mode...
Built in 255ms

Sweet! It worked 🎉

Now, I don't know about you, but as nice as it is that remix is going to be our "proxy" package, I don't want to have to run that setup script any time I install dependencies. So let's add a postinstall script to do that automatically for us:

{
  "scripts": {
    "postinstall": "remix setup node",
    "build": "remix build"
  },
  "dependencies": {
    "@remix-run/react": "^1.0.4",
    "@remix-run/serve": "^1.0.4",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "remix": "^1.0.4"
  },
  "devDependencies": {
    "@remix-run/dev": "^1.0.4"
  }
}

I also highlighted the lines above that are the other dependencies we've added to our project.

Sweet. So now we actually have something real that'll run and build. Onto the next step!

5. Running our Remix server

Alright, so we want to "develop" our app right? So let's add dev script to our package.json:

{
  "scripts": {
    "postinstall": "remix setup node",
    "build": "remix build",
    "dev": "remix dev"
  },
  "dependencies": {
    "@remix-run/react": "^1.0.4",
    "@remix-run/serve": "^1.0.4",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "remix": "^1.0.4"
  },
  "devDependencies": {
    "@remix-run/dev": "^1.0.4"
  }
}

And now if we run npm run dev we'll get this output:

Watching Remix app in development mode...
Remix App Server started at http://localhost:3000
💿 Built in 314ms

That output shows that remix dev does two things:

  1. Remix App Server started at http://localhost:3000: This comes from remix-serve which is running a simple express server based on what's in the build directory.
  2. 💿 Built in 314ms: This comes from remix build which is running in watch mode and development mode.

Whenever we make a change, the output in build is updated and the express server picks up those changes.

One other thing remix dev does is start a websocket with the browser to support live reload. Currently there's no support for "Hot Module Replacement" (HMR) and I'm actually totally cool with that. I never trusted HMR in apps anyway (though it's awesome in tools like storybook) and always did a full-page refresh even with HMR setup. Additionally, since a lot of the code you write with remix is server-side, you typically want a full-page refresh anyway to get all the server-side code to run again. All that said, HMR will come in the future.

Ok, great, let's get this opened up! Navigate to localhost:3000 and poof:

Browser window with the text "This is a remix app. Hooray!"" And a button with the number 0 in it

6. Hydrating our Remix app

But oh no! If we click that button nothing happens. Weird... I thought this was a react app. Let's take a look at the network tab:

Network tab showing two GET requests, one for the document and the other for a favicon

Notice anything missing? Oh yeah! No JavaScript! Yup, that's right, with Remix you get to choose whether you load any JavaScript at all. And it's not a configuration thing. Remember how we are in charge of the entire document starting from <html>? Cool right? So let's update our app/root.jsx to include the script tag. Remix conveniently gives us a component we can render to render that script tag:

import * as React from 'react'
import {Scripts} from 'remix'

function App() {
  const [count, setCount] = React.useState(0)
  return (
    <html>
      <head>
        <title>My First Remix App</title>
      </head>
      <body>
        <p>This is a remix app. Hooray!</p>
        <button onClick={() => setCount(c => c + 1)}>{count}</button>
        <Scripts />
      </body>
    </html>
  )
}

export default App

Also that missing favicon thing is annoying so I'll add this cool CD as a favicon:

CD

Just put that .ico file in the public directory. @remix-run/serve will automatically serve files in that directory and the browser (which by looks for that file by default) will be able to get it that way.

Neato, let's try that now:

Network tab with scripts getting loaded

And if we "view source" on the document here's what we get:

<!DOCTYPE html>
<html>
  <head>
    <title>My First Remix App</title>
  </head>
  <body>
    <p>This is a remix app. Hooray!</p>
    <button>0</button>
    <link rel="modulepreload" href="/build/_shared/chunk-DLVV55I2.js" />
    <link rel="modulepreload" href="/build/root-2UAEY3HA.js" />
    <script>
      window.__remixContext = {
        matches: [
          {
            params: {},
            pathname: '/',
            route: {
              id: 'root',
              path: '',
              module: '/build/root-2UAEY3HA.js',
              hasAction: false,
              hasLoader: false,
              hasCatchBoundary: false,
              hasErrorBoundary: false,
            },
          },
        ],
        componentDidCatchEmulator: {
          trackBoundaries: true,
          trackCatchBoundaries: true,
          catchBoundaryRouteId: null,
          renderBoundaryRouteId: null,
          loaderBoundaryRouteId: null,
          error: undefined,
          catch: undefined,
        },
        routeData: {root: null},
        actionData: undefined,
      }
    </script>
    <script src="/build/manifest-14A81006.js"></script>
    <script type="module">
      import * as route0 from '/build/root-2UAEY3HA.js'
      window.__remixRouteModules = {root: route0}
    </script>
    <script src="/build/entry.client-7F2IUO4V.js" type="module"></script>
  </body>
</html>

So that's neat. Not only does Remix add script tags, but it also preloads things for us, so we don't have a waterfall (you'll notice the network tab has all resources starting to load at the same time). This gets even more interesting when we start routing, but we'll keep things simple.

7. Running Production Mode locally

Alright, let's build and run this thing locally. So first we need to run the production build to get everything minified and have React optimize itself for production:

npm run build

Building Remix app in production mode...
Built in 281ms

Now, let's add a start script to run remix-serve for our build directory:

{
  "scripts": {
    "postinstall": "remix setup node",
    "build": "remix build",
    "dev": "remix dev",
    "start": "remix-serve ./build"
  },
  "dependencies": {
    "@remix-run/react": "^1.0.4",
    "@remix-run/serve": "^1.0.4",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "remix": "^1.0.4"
  },
  "devDependencies": {
    "@remix-run/dev": "^1.0.4"
  }
}

One other thing we'll want to do is set the NODE_ENV to production so any dependencies we use that operate slightly differently in production mode will work as expected, so let's add cross-env and set the NODE_ENV with that:

{
  "scripts": {
    "postinstall": "remix setup node",
    "build": "remix build",
    "dev": "remix dev",
    "start": "cross-env NODE_ENV=production remix-serve ./build"
  },
  "dependencies": {
    "@remix-run/react": "^1.0.4",
    "@remix-run/serve": "^1.0.4",
    "cross-env": "^7.0.3",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "remix": "^1.0.4"
  },
  "devDependencies": {
    "@remix-run/dev": "^1.0.4"
  }
}

Cool, so let's get it started:

npm start

> @ start ~/Desktop/super-simple-start-to-remix
> cross-env NODE_ENV=production remix-serve build

Remix App Server started at http://localhost:3000

And if we open that up, we'll see it's working perfectly:

The working app

Hooray!

Conclusion

You have a lot of options for actually deploying your Remix app to production and when you set up Remix the easy way (via npx create-remix@latest) it'll let you choose which supported service you'd like to use and it'll spit out all the config and instructions to get started that you need, so I'm not going to cover that here.

There is so much more to Remix, but this is a "super simple start" so I wanted to do as little as possible to show you where all the moving pieces are to get something up and running with Remix. Like I said, npx create-remix@latest makes all this a snap, but hopefully this walkthrough helped you get an idea of what parts of remix does what.

You can find the code for this walkthrough here: kentcdodds/super-simple-start-to-remix

Enjoy!

Kent C. Dodds
Written by Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's Co-Founder and Director of Developer Experience at Remix! Kent's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.

Learn more about Kent

Want to learn more?

Join Kent in a live workshop

If you found this article helpful.

You will love these ones as well.