Module Constraints

In order for Remix to run your app in both the server and browser environments, your application modules and third-party dependencies need to be careful about module side effects.

  • Server-only code - Remix will remove server-only code but it can’t if you have module side effects that use server-only code.
  • Browser-only code - Remix renders on the server so your modules can’t have module side effects or first-rendering logic that call browser-only APIs

Server Code Pruning

The Remix compiler will automatically remove server code from the browser bundles. Our strategy is actually pretty straightforward, but requires you to follow some rules.

  1. It creates a “proxy” module in front of your route module
  2. The proxy module only imports the browser specific exports

Consider a route module that exports loader, meta, and a component:

  1. import { json } from "@remix-run/node"; // or cloudflare/deno
  2. import { useLoaderData } from "@remix-run/react";
  4. import { prisma } from "../db";
  5. import PostsView from "../PostsView";
  7. export async function loader() {
  8.   return json(await prisma.post.findMany());
  9. }
  11. export function meta() {
  12.   return { title: "Posts" };
  13. }
  15. export default function Posts() {
  16.   const posts = useLoaderData<typeof loader>();
  17.   return <PostsView posts={posts} />;
  18. }

The server needs everything in this file but the browser only needs the component and meta. In fact, it’ll be completely broken if it includes the prisma module in the browser bundle. That thing is full of node-only APIs!

To remove the server code from the browser bundles, the Remix compiler creates a proxy module in front of your route and bundles that instead. The proxy for this route would look like:

  1. export { meta, default } from "./routes/posts.tsx";

The compiler will now analyze the code in routes/posts.tsx and only keep code that’s inside of meta and the component. The result is something like this:

  1. import { useLoaderData } from "@remix-run/react";
  3. import PostsView from "../PostsView";
  5. export function meta() {
  6.   return { title: "Posts" };
  7. }
  9. export default function Posts() {
  10.   const posts = useLoaderData<typeof loader>();
  11.   return <PostsView posts={posts} />;
  12. }

Pretty slick! This is now safe to bundle up for the browser. So what’s the problem?

No Module Side Effects

If you’re unfamiliar with side effects, you’re not alone! We’ll help you identify them now.

Simply put, a side effect is any code that might do something. A module side effect is any code that might do something when a module is loaded.

A module side effect is code that executes by simply importing a module

Taking our code from earlier, we saw how the compiler can remove the exports and their imports that aren’t used. But if we add this seemingly harmless line of code your app will break!

  1. import { json } from "@remix-run/node"; // or cloudflare/deno
  2. import { useLoaderData } from "@remix-run/react";
  4. import { prisma } from "../db";
  5. import PostsView from "../PostsView";
  7. console.log(prisma);
  9. export async function loader() {
  10.   return json(await prisma.post.findMany());
  11. }
  13. export function meta() {
  14.   return { title: "Posts" };
  15. }
  17. export default function Posts() {
  18.   const posts = useLoaderData<typeof loader>();
  19.   return <PostsView posts={posts} />;
  20. }

That console.log does something. The module is imported and then immediately logs to the console. The compiler won’t remove it because it has to run when the module is imported. It will bundle something like this:

  1. import { useLoaderData } from "@remix-run/react";
  3. import { prisma } from "../db"; //😬
  4. import PostsView from "../PostsView";
  6. console.log(prisma); //🥶
  8. export function meta() {
  9.   return { title: "Posts" };
  10. }
  12. export default function Posts() {
  13.   const posts = useLoaderData<typeof loader>();
  14.   return <PostsView posts={posts} />;
  15. }

The loader is gone but the prisma dependency stayed! Had we logged something harmless like console.log("hello!") it would be fine. But we logged the prisma module so the browser’s going to have a hard time with that.

To fix this, remove the side effect by simply moving the code into the loader.

  1. import { json } from "@remix-run/node"; // or cloudflare/deno
  2. import { useLoaderData } from "@remix-run/react";
  4. import { prisma } from "../db";
  5. import PostsView from "../PostsView";
  7. export async function loader() {
  8.   console.log(prisma);
  9.   return json(await prisma.post.findMany());
  10. }
  12. export function meta() {
  13.   return { title: "Posts" };
  14. }
  16. export default function Posts() {
  17.   const posts = useLoaderData<typeof loader>();
  18.   return <PostsView posts={posts} />;
  19. }

This is no longer a module side effect (runs when the module is imported), but rather a side effect of the loader (runs when the loader is called). The compiler will now remove both the loader and the prisma import because it isn’t used anywhere else in the module.

Occasionally, the build may have trouble tree-shaking code that should only run on the server. If this happens, you can use the convention of naming a file with the extension .server before the file type, for example db.server.ts. Adding .server to the filename is a hint to the compiler to not worry about this module or its imports when bundling for the browser.

Higher Order Functions

Some Remix newcomers try to abstract their loaders with “higher order functions”. Something like this:

  1. import { redirect } from "@remix-run/node"; // or cloudflare/deno
  3. export function removeTrailingSlash(loader) {
  4.   return function (arg) {
  5.     const { request } = arg;
  6.     const url = new URL(request.url);
  7.     if (
  8.       url.pathname !== "/" &&
  9.       url.pathname.endsWith("/")
  10.     ) {
  11.       return redirect(request.url.slice(0, -1), {
  12.         status: 308,
  13.       });
  14.     }
  15.     return loader(arg);
  16.   };
  17. }

And then try to use it like this:

  1. import { json } from "@remix-run/node"; // or cloudflare/deno
  3. import { removeTrailingSlash } from "~/http";
  5. export const loader = removeTrailingSlash(({ request }) => {
  6.   return json({ some: "data" });
  7. });

You can probably now see that this is a module side effect so the compiler can’t prune out the removeTrailingSlash code.

This type of abstraction is introduced to try to return a response early. Since you can throw a Response in a loader, we can make this simpler and remove the module side effect at the same time so that the server code can be pruned:

  1. import { redirect } from "@remix-run/node"; // or cloudflare/deno
  3. export function removeTrailingSlash(url) {
  4.   if (url.pathname !== "/" && url.pathname.endsWith("/")) {
  5.     throw redirect(request.url.slice(0, -1), {
  6.       status: 308,
  7.     });
  8.   }
  9. }

And then use it like this:

  1. import { json } from "@remix-run/node"; // or cloudflare/deno
  3. import { removeTrailingSlash } from "~/http";
  5. export const loader = async ({ request }: LoaderArgs) => {
  6.   removeTrailingSlash(request.url);
  7.   return json({ some: "data" });
  8. };

It reads much nicer as well when you’ve got a lot of these:

  1. // this
  2. export const loader = async ({ request }: LoaderArgs) => {
  3.   return removeTrailingSlash(request.url, () => {
  4.     return withSession(request, (session) => {
  5.       return requireUser(session, (user) => {
  6.         return json(user);
  7.       });
  8.     });
  9.   });
  10. };
  1. // vs. this
  2. export const loader = async ({ request }: LoaderArgs) => {
  3.   removeTrailingSlash(request.url);
  4.   const session = await getSession(request);
  5.   const user = await requireUser(session);
  6.   return json(user);
  7. };

If you want to do some extra-curricular reading, google around for “push vs. pull API”. The ability to throw responses changes the model from a “push” to a “pull”. This is the same reason folks prefer async/await over callbacks, and React hooks over higher order components and render props.

Browser-Only Code on the Server

Unlike the browser bundles, Remix doesn’t try to remove browser only code from the server bundle because the route modules require every export to render on the server. This means it’s your job to be mindful of code that should only execute in the browser.

This will break your app:

  1. import { loadStripe } from "@stripe/stripe-js";
  3. const stripe = await loadStripe(window.ENV.stripe);
  5. export async function redirectToStripeCheckout(
  6.   sessionId: string
  7. ) {
  8.   return stripe.redirectToCheckout({ sessionId });
  9. }

You need to avoid any browser-only module side effects like accessing window or initializing APIs in the module scope.

Initializing Browser-Only APIs

The most common scenario is initializing a third-party API when your module is imported. There are a couple ways to easily deal with this.

Document Guard

This ensures the library is only initialized if there is a document, meaning you’re in the browser. We recommend document over window because server runtimes like Deno have a global window available.

  1. import firebase from "firebase/app";
  3. if (typeof document !== "undefined") {
  4.   firebase.initializeApp(document.ENV.firebase);
  5. }
  7. export { firebase };

Lazy Initialization

This strategy defers initialization until the library is actually used:

  1. import { loadStripe } from "@stripe/stripe-js";
  3. export async function redirectToStripeCheckout(
  4.   sessionId: string
  5. ) {
  6.   const stripe = await loadStripe(window.ENV.stripe);
  7.   return stripe.redirectToCheckout({ sessionId });
  8. }

You may want to avoid initializing the library multiple times by storing it in a module-scoped variable.

  1. import { loadStripe } from "@stripe/stripe-js";
  3. let _stripe;
  4. async function getStripe() {
  5.   if (!_stripe) {
  6.     _stripe = await loadStripe(window.ENV.stripe);
  7.   }
  8.   return _stripe;
  9. }
  11. export async function redirectToStripeCheckout(
  12.   sessionId: string
  13. ) {
  14.   const stripe = await getStripe();
  15.   return stripe.redirectToCheckout({ sessionId });
  16. }

While none of these strategies remove browser modules from the server bundle, it’s okay because the APIs are only called inside of event handlers and effects, which are not module side effects.

Rendering with Browser Only APIs

Another common case is code that calls browser-only APIs while rendering. When server rendering in React (not just Remix), this must be avoided because the APIs don’t exist on the server.

This will break your app because the server will try to use local storage

  1. function useLocalStorage(key: string) {
  2.   const [state, setState] = useState(
  3.     localStorage.getItem(key)
  4.   );
  6.   const setWithLocalStorage = (nextState) => {
  7.     setState(nextState);
  8.   };
  10.   return [state, setWithLocalStorage];
  11. }

You can fix this by moving the code into useEffect, which only runs in the browser.

  1. function useLocalStorage(key: string) {
  2.   const [state, setState] = useState(null);
  4.   useEffect(() => {
  5.     setState(localStorage.getItem(key));
  6.   }, [key]);
  8.   const setWithLocalStorage = (nextState) => {
  9.     setState(nextState);
  10.   };
  12.   return [state, setWithLocalStorage];
  13. }

Now localStorage is not being accessed on the initial render, which will work for the server. In the browser, that state will fill in immediately after hydration. Hopefully it doesn’t cause a big content layout shift though! If it does, maybe move that state into your database or a cookie so you can access it server side.

useLayoutEffect

If you use this hook React will warn you about using it on the server.

This hook is great when you’re setting state for things like:

  • The position of an element when it pops up (like a menu button)
  • The scroll position in response to user interactions

The point is to perform the effect at the same time as the browser paint so that you don’t see the popup show up at 0,0 and then bounce into place. Layout effects let the paint and the effect happen at the same time to avoid this kind of flashing.

It is not good for setting state that is rendered inside of elements. Just make sure you aren’t using the state set in a useLayoutEffect in your elements and you can ignore React’s warning.

If you know you’re calling useLayoutEffect correctly and just want to silence the warning, a popular solution in libraries is to create your own hook that doesn’t call anything on the server. useLayoutEffect only runs in the browser anyway, so this should do the trick. Please use this carefully, because the warning is there for a good reason!

  1. import * as React from "react";
  3. const canUseDOM = !!(
  4.   typeof window !== "undefined" &&
  5.   window.document &&
  6.   window.document.createElement
  7. );
  9. const useLayoutEffect = canUseDOM
  10.   ? React.useLayoutEffect
  11.   : () => {};

Third-Party Module Side Effects

Some third party libraries have their own module side effects that are incompatible with React server rendering. Usually it’s trying to access window for feature detection.

These libraries are incompatible with server rendering in React and therefore incompatible with Remix. Fortunately, very few third party libraries in the React ecosystem do this.

We recommend finding an alternative. But if you can’t, we recommend using patch-package to fix it up in your app.