remix-run · lpsinger · Aug 25, 2023 · Sep 7, 2023 · Nov 1, 2023
diff --git a/.changeset/cyan-pumpkins-fry.md b/.changeset/cyan-pumpkins-fry.md
@@ -0,0 +1,7 @@
+---
+"@remix-run/dev": minor
+---
+
+Support root route as a folder.
+
+Now your root route can be either a file (`app/root.tsx`) or a folder (`app/root/route.tsx`) just like any other route. This is handy for organizational purposes if your root route depends on a lot of components imported from other files.
diff --git a/docs/file-conventions/routes.md b/docs/file-conventions/routes.md
@@ -370,6 +370,18 @@ app/routes/app._index.tsx
 app/routes/app._index/route.tsx
 ```
 
+Even your root route can be a folder. For example:
+
+```text
+app/
+├── root/
+|   ├── footer.tsx
+|   ├── menu.tsx
+|   └── route.tsx
+└── routes/
+    ├── _index.tsx
+    └── about.tsx
+
 ## Scaling
 
 Our general recommendation for scale is to make every route a folder and put the modules used exclusively by that route in the folder, then put the shared modules outside of routes folder elsewhere. This has a couple benefits:

diff --git a/integration/helpers/create-fixture.ts b/integration/helpers/create-fixture.ts
@@ -343,6 +343,11 @@ async function writeTestFiles(init: FixtureInit, dir: string) {
       let filePath = path.join(dir, filename);
       await fse.ensureDir(path.dirname(filePath));
       let file = init.files![filename];
+      // if we have a app/root/route.tsx then we don't want app/root.tsx to exist
+      if (filename.endsWith("root/route.tsx")) {
+        let rootTsx = path.join(dir, "app", "root.tsx");
+        await fse.remove(rootTsx);
+      }
 
       await fse.writeFile(filePath, stripIndent(file));
     })

diff --git a/integration/root-route-folder-test.ts b/integration/root-route-folder-test.ts
@@ -0,0 +1,75 @@
+import { test, expect } from "@playwright/test";
+
+import { PlaywrightFixture } from "./helpers/playwright-fixture.js";
+import type { Fixture, AppFixture } from "./helpers/create-fixture.js";
+import {
+  createAppFixture,
+  createFixture,
+  js,
+} from "./helpers/create-fixture.js";
+
+let fixture: Fixture;
+let appFixture: AppFixture;
+
+test.describe("root route as a folder", () => {
+  test.beforeAll(async () => {
+    fixture = await createFixture({
+      files: {
+        "app/root/route.tsx": js`
+          import { Links, Meta, Outlet, Scripts } from "@remix-run/react";
+
+          export default function Root() {
+            return (
+              <html lang="en">
+                <head>
+                  <Meta />
+                  <Links />
+                </head>
+                <body>
+                  <div id="content">
+                    <h1>Root</h1>
+                    <Outlet />
+                  </div>
+                  <Scripts />
+                </body>
+              </html>
+            );
+          }
+        `,
+
+        "app/routes/_index.tsx": js`
+          export default function () {
+            return <h2>Index</h2>;
+          }
+        `,
+      },
+    });
+
+    appFixture = await createAppFixture(fixture);
+  });
+
+  test.afterAll(() => {
+    appFixture.close();
+  });
+
+  test.describe("without JavaScript", () => {
+    test.use({ javaScriptEnabled: false });
+    runTests();
+  });
+
+  test.describe("with JavaScript", () => {
+    test.use({ javaScriptEnabled: true });
+    runTests();
+  });
+
+  function runTests() {
+    test("renders matching routes (index)", async ({ page }) => {
+      let app = new PlaywrightFixture(appFixture, page);
+      await app.goto("/");
+      expect(await app.getHtml("#content")).toBe(`<div id="content">
+  <h1>Root</h1>
+  <h2>Index</h2>
+</div>`);
+    });
+  }
+});
diff --git a/packages/remix-dev/config.ts b/packages/remix-dev/config.ts
@@ -9,7 +9,10 @@ import type { RouteManifest, DefineRoutesFunction } from "./config/routes";
 import { defineRoutes } from "./config/routes";
 import { ServerMode, isValidServerMode } from "./config/serverModes";
 import { serverBuildVirtualModule } from "./compiler/server/virtualModules";
-import { flatRoutes } from "./config/flat-routes";
+import {
+  findRootRoute,
+  flatRoutes,
+} from "./config/flat-routes";
 import { detectPackageManager } from "./cli/detectPackageManager";
 import { logger } from "./tux";
 
@@ -523,10 +526,11 @@ export async function resolveConfig(
 
   let publicPath = addTrailingSlash(appConfig.publicPath || "/build/");
 
-  let rootRouteFile = findEntry(appDirectory, "root");
+  let rootRouteFile = findRootRoute(appDirectory);
   if (!rootRouteFile) {
     throw new Error(`Missing "root" route file in ${appDirectory}`);
   }
+  rootRouteFile = path.relative(appDirectory, rootRouteFile);
 
   let routes: RouteManifest = {
     root: { path: "", id: "root", file: rootRouteFile },

diff --git a/packages/remix-dev/config/flat-routes.ts b/packages/remix-dev/config/flat-routes.ts
@@ -72,6 +72,21 @@ class PrefixLookupTrie {
   }
 }
 
+export function findRootRoute(appDirectory: string) {
+  let routeFileForFolder = findRouteModuleForFolder(
+    appDirectory,
+    path.join(appDirectory, "root"),
+    []
+  );
+  let routeFileForFile = findConfig(appDirectory, "root", routeModuleExts);
+  if (routeFileForFolder && routeFileForFile) {
+    throw new Error(
+      `Conflicting root route modules: ${routeFileForFolder}, ${routeFileForFile}`
+    );
+  }
+  return routeFileForFolder || routeFileForFile;
+}
+
 export function flatRoutes(
   appDirectory: string,
   ignoredFilePatterns: string[] = [],
@@ -82,7 +97,7 @@ export function flatRoutes(
     .filter((re: any): re is RegExp => !!re);
   let routesDir = path.join(appDirectory, prefix);
 
-  let rootRoute = findConfig(appDirectory, "root", routeModuleExts);
+  let rootRoute = findRootRoute(appDirectory);
 
   if (!rootRoute) {
     throw new Error(