This site runs best with JavaScript enabled.

Super Simple Start to Remix

Software Engineer, React Training, Testing JavaScript Training

Photo by Jan Huber

The simplest distraction-free version of a remix app

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 npm init remix 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. Get a license

Remix is paid software. That's right! Instead of sucking the maintainers of their time and energy, you're actually giving them more resources to make the framework even better by becoming a user! Cool right?!

So to get a license, go to and purchase the license that makes the most sense for you.

With your very own license key (which you can find on your remix dashboard), you're ready to begin.

Let's imagine your key is 1278430678990lol4dnice39b4try14123.

2. Installing Remix

You install remix packages just like you install all other packages on npm, except because it's paid software, Remix hosts it's own package registry for remix packages. This means that you list remix packages in your package.json and you can use npm install or yarn add or whatever like usual, but you need to tell the package manager where to get the remix packages. You need to tell npm that when it's installing remix packages, it needs to use remix's registry instead of the official npm registry.

Here's how we do that. Create a file in your project called .npmrc:

1# ~/Desktop/super-simple-start-to-remix/.npmrc

So now when npm comes across any package within the @remix-run scope, it'll use the registry. Go ahead and try installing one:

1npm install @remix-run/node
3npm ERR! code E403
4npm ERR! 403 403 Forbidden - GET - Missing authorization
5npm ERR! 403 In most cases, you or one of your dependencies are requesting
6npm ERR! 403 a package version that is forbidden by your security policy.
8npm ERR! A complete log of this run can be found in:
9npm ERR! /Users/kentcdodds/.npm/_logs/2021-05-03T22_34_06_763Z-debug.log

Oh yeah, we need to make sure the remix registry knows we're authorized to download remix packages. The way we do this is by providing an authToken by updating our .npmrc with this:

1# ~/Desktop/super-simple-start-to-remix/.npmrc

BUT WAIT! We don't want to put our license right there in plain sight for anyone to grab, especially if we plan on pushing this to source control. So instead, we'll put our license key in an environment variable and reference that environment variable.

So let's update the .npmrc to not reference our key directly, and interpolate an environment variable instead:

1# ~/Desktop/super-simple-start-to-remix/.npmrc

So now, try setting that variable and then installing. Here's how you do that on macOS:

3npm install @remix-run/node


Personally, I'm not a fan of setting that environment variable every time I open a terminal window and need to install my dependencies, so I suggest you set that environment variable on your system:

With that set up, we can now install the other packages we need to get things started:

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

3. Configuring Remix

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

1module.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.

4. Building the app with Remix

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

2 "scripts": {
3 "build": "remix build"
4 },
5 "dependencies": {
6 "@remix-run/node": "^0.17.0",
7 "@remix-run/react": "^0.17.0",
8 "react": "^17.0.2",
9 "react-dom": "^17.0.2",
10 "remix": "^0.17.0"
11 },
12 "devDependencies": {
13 "@remix-run/dev": "^0.17.0"
14 }

Before we run that command though, we're going to need a few files:

1mkdir app
2touch app/entry.client.jsx
3touch app/entry.server.jsx
4touch app/root.jsx

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.

Now, let's run the build:

1npm run build
3Building Remix app in production mode...
4Built in 28ms

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

2├── app
3│ ├── entry.client.jsx
4│ ├── entry.server.jsx
5│ └── root.jsx
6├── package-lock.json
7├── package.json
8└── remix.config.js

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

2├── app
3│ ├── entry.client.jsx
4│ ├── entry.server.jsx
5│ └── root.jsx
6├── build
7│ ├── assets.json
8│ └── index.js
9├── package-lock.json
10├── package.json
11├── public
12│ └── build
13│ ├── _shared
14│ │ └── chunk-DH6LPQ4Z.js
15│ ├── entry.client-LKK3OBJD.js
16│ ├── manifest-C0FC4AB2.js
17│ └── root-CJI57JUZ.js
18└── remix.config.js

Sweet! We built it... Now what?

5. 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:

1import * as React from 'react'
3function App() {
4 const [count, setCount] = React.useState(0)
5 return (
6 <html>
7 <head>
8 <title>My First Remix App</title>
9 </head>
10 <body>
11 <p>This is a remix app. Hooray!</p>
12 <button onClick={() => setCount(c => c + 1)}>{count}</button>
13 </body>
14 </html>
15 )
18export 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:

1import ReactDOM from 'react-dom'
2import {RemixBrowser} from 'remix'
4ReactDOM.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:

1import ReactDOMServer from 'react-dom/server'
2import {RemixServer} from 'remix'
4function handleRequest(
5 request,
6 responseStatusCode,
7 responseHeaders,
8 remixContext,
9) {
10 const markup = ReactDOMServer.renderToString(
11 <RemixServer context={remixContext} url={request.url} />,
12 )
14 return new Response(`<!DOCTYPE html>${markup}`, {
15 status: responseStatusCode,
16 headers: {
17 ...Object.fromEntries(responseHeaders),
18 'Content-Type': 'text/html',
19 },
20 })
23export 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.

One other thing I'll note is that the remix package is actually a lightweight (and public) package that simply re-exports things from @remix-run/node (server-side stuff) and @remix-run/react (client-side stuff).

6. Running our Remix server

Remix supports running just about anywhere. It has built-in support and adapters for a growing list of environments including anywhere that runs express (and/or docker containers), architect, and vercel (soon netlify, firebase, and cloudflare workers). Depending on where you plan to deploy, you may want to use the tools provided by that platform. For us, we'll go for the express approach. We can create our own express server if we want, but since we don't need any extra bells and whistles for our express server, we can use what's offered by default from @remix-run/serve. So let's get that installed:

1npm install @remix-run/serve

Note that this is a regular dependency because we'll use this to server our app in production. Now let's add dev script to our package.json:

2 "scripts": {
3 "build": "remix build",
4 "dev": "remix run"
5 },
6 "dependencies": {
7 "@remix-run/node": "^0.17.0",
8 "@remix-run/react": "^0.17.0",
9 "react": "^17.0.2",
10 "react-dom": "^17.0.2",
11 "remix": "^0.17.0"
12 },
13 "devDependencies": {
14 "@remix-run/dev": "^0.17.0"
15 }

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

1Watching Remix app in development mode...
2Remix App Server started at http://localhost:3000
3💿 Built in 102ms

That output shows that remix run 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 102ms: 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 run 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 may 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

7. Hydrating our Remix app

But oh no! If we click that button nothings 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 the script tag. Remix conveniently gives us a component we can render to render that script tag:

1// app/root.jsx
2import * as React from 'react'
3import {Scripts} from 'remix'
5function App() {
6 const [count, setCount] = React.useState(0)
7 return (
8 <html>
9 <head>
10 <title>My First Remix App</title>
11 </head>
12 <body>
13 <p>This is a remix app. Hooray!</p>
14 <button onClick={() => setCount(c => c + 1)}>{count}</button>
15 <Scripts />
16 </body>
17 </html>
18 )
21export default App

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


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:

1<!DOCTYPE html>
3 <head>
4 <title>My First Remix App</title>
5 </head>
6 <body>
7 <p>This is a remix app. Hooray!</p>
8 <button>0</button>
9 <link rel="modulepreload" href="/build/_shared/chunk-UKIVUHZH.js" />
10 <link rel="modulepreload" href="/build/root-ZWUBXRA3.js" />
11 <script>
12 window.__remixContext = {
13 matches: [
14 {
15 params: {},
16 pathname: '/',
17 route: {
18 id: 'root',
19 path: '/',
20 module: '/build/root-ZWUBXRA3.js',
21 hasAction: false,
22 hasLoader: false,
23 },
24 },
25 ],
26 componentDidCatchEmulator: {
27 trackBoundaries: true,
28 renderBoundaryRouteId: null,
29 loaderBoundaryRouteId: null,
30 error: undefined,
31 },
32 routeData: {root: null},
33 }
34 </script>
35 <script src="/build/manifest-6B36E634.js"></script>
36 <script type="module">
37 import * as route0 from '/build/root-ZWUBXRA3.js'
38 window.__remixRouteModules = {root: route0}
39 </script>
40 <script src="/build/entry.client-4YFGIIEC.js" type="module"></script>
41 </body>

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.

8. 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:

1npm run build
3Building Remix app in production mode...
4Built in 52ms

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

2 "scripts": {
3 "build": "remix build",
4 "dev": "remix run",
5 "start": "remix-serve build"
6 },
7 "dependencies": {
8 "@remix-run/node": "^0.17.0",
9 "@remix-run/react": "^0.17.0",
10 "react": "^17.0.2",
11 "react-dom": "^17.0.2",
12 "remix": "^0.17.0"
13 },
14 "devDependencies": {
15 "@remix-run/dev": "^0.17.0"
16 }

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:

2 "scripts": {
3 "build": "remix build",
4 "dev": "remix run",
5 "start": "cross-env NODE_ENV=production remix-serve build"
6 },
7 "dependencies": {
8 "@remix-run/node": "^0.17.0",
9 "@remix-run/react": "^0.17.0",
10 "@remix-run/serve": "^0.17.0",
11 "cross-env": "^7.0.3",
12 "react": "^17.0.2",
13 "react-dom": "^17.0.2",
14 "remix": "^0.17.0"
15 },
16 "devDependencies": {
17 "@remix-run/dev": "^0.17.0"
18 }

Cool, so let's get it started:

1npm start
3> @ start /Users/kentcdodds/Desktop/super-simple-start-to-remix
4> cross-env NODE_ENV=production remix-serve build
6Remix App Server started at http://localhost:3000

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

The working app



You have a lot of options for actually deploying your Remix app to production and when you set up Remix the easy way (via npm init remix) 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, npm init remix 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


Discuss on TwitterEdit post on GitHub

Share article

Get Really Good at React

Blast Off

Write professional React.

Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He'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.

Join the Newsletter

Kent C. Dodds