Incorporate the v3_routeConfig future flag for Remix.

[seanparsons]

Upgrade instructions

Please refer to the Remix documentation for more details on v3_routeConfig future flag: https://remix.run/docs/en/main/start/future-flags#v3_routeconfig

1. Update your vite.config.ts.

   export default defineConfig({
     plugins: [
       hydrogen(),
       oxygen(),
       remix({
   -      presets: [hydrogen.preset()],
   +      presets: [hydrogen.v3preset()],
       future: {
         v3_fetcherPersist: true,
         v3_relativeSplatPath: true,
         v3_throwAbortReason: true,
         v3_lazyRouteDiscovery: true,
         v3_singleFetch: true,
   +      v3_routeConfig: true,
       },
     }),
     tsconfigPaths(),
   ],

2. Update your package.json and install the new packages. Make sure to match the Remix version along with other Remix npm packages and ensure the versions are 2.16.1 or above:

     "devDependencies": {
       "@remix-run/dev": "^2.16.1",
   +    "@remix-run/fs-routes": "^2.16.1",
   +    "@remix-run/route-config": "^2.16.1",

3. Add a routes.ts file. This is your new Remix route configuration file.

   import {flatRoutes} from '@remix-run/fs-routes';
   import {type RouteConfig} from '@remix-run/route-config';
   import {hydrogenRoutes} from '@shopify/hydrogen';
   
   export default hydrogenRoutes([
     ...(await flatRoutes()),
     // Manual route definitions can be added to this array, in addition to or instead of using the `flatRoutes` file-based routing convention.
     // See https://remix.run/docs/en/main/guides/routing for more details
   ]) satisfies RouteConfig;

WHY are these changes introduced?

These changes are to support an upgrade to the next version of Remix, by using the future flag and supporting libraries to get the code ready for that upgrade in place before the upgrade itself happens.

WHAT is this pull request doing?

• Added the v3_routeConfig flag set to true.
• Created a hydrogen.v3preset function which excludes the routes attribute that the hydrogen.preset function includes because that is incompatible with the flag being turned on.
• Added a hydrogenRoutes function which transforms the route specified in routes.ts to include the virtual routes.
• Rewrote getVirtualRoutes to work without using any node libraries so that it can run in MiniOxygen.
• Updated the example projects to have them use the flag and the changes necessary to use the flag.
• Set the LANG environment variable in the cli package so that the date formatting uses the US formatting.
• build.test.ts now closes resources so that the test doesn't fail due to the hanging file watchers.
• build.ts sets the server.watch configuration option as that may be necessary to disable the file watching.
• hydrogen/dev.ts shuts down the watcher on the viteServer when finishing up.
• setup.test.ts makes sure to include the routes.ts file.
• classic-compiler/dev.ts makes sure to filter out the virtual routes when disableVirtualRoutes is true.
• remix-config.ts constructs a value routesViteNodeContext which is necessary when resolving the config if v3_routeConfig is enabled.
• route-validator.ts is now null safe when assigning currentRoute.path.
• get-virtual-routes.test.ts now checks for the jsx files instead of the tsx files of the virtual routes.
• Patched @remix-run/dev to not watch in remixVitePlugin when in a test because the file watchers cannot be reached to switch them off which causes tests relying on that to fail.
• Patched vite to handle the watch properties of the config to set it if the value is null as that has meaning in that particular case.

HOW to test your changes?

• Follow the steps as described in https://remix.run/docs/en/main/start/future-flags#v3_routeconfig to bring your project in line with the expectations therein.
• Wrap the routes in routes.ts with the hydrogenRoutes function, to add the supporting routes.
• Change the hydrogen preset from hydrogen.preset() to hydrogen.v3preset().

Post-merge steps

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation

Amended changes

The following changes were reverted/amended in #2829 .

3. Move the Layout component export from root.tsx into its own file. Make sure to supply an <Outlet> so Remix knows where to inject your route content.

   // /app/layout.tsx
   import {Outlet} from '@remix-run/react';
   
   export default function Layout() {
     const nonce = useNonce();
     const data = useRouteLoaderData<RootLoader>('root');
   
     return (
       <html lang="en">
         ...
         <Outlet />
         ...
       </html>
     );
   }
   
   // Remember to remove the Layout export from your root.tsx

4. Add a routes.ts file. This is your new Remix route configuration file.

   import { flatRoutes } from "@remix-run/fs-routes";
   import { layout, type RouteConfig } from "@remix-run/route-config";
   import { hydrogenRoutes } from "@shopify/hydrogen";
   
   export default hydrogenRoutes([
     // Your entire app reading from routes folder using Layout from layout.tsx
     layout("./layout.tsx", await flatRoutes()),
   ]) satisfies RouteConfig;

• common.ts now makes sure to include routes.ts and layout.tsx.
• local.test.ts slightly tweaked to make it easier to find out what files are missing and also now correctly takes account of the content that was shifted from root.tsx to layout.tsx.
• replacers.ts looks for layout instead of root.

[shopify]

Oxygen deployed a preview of your refactor/v3_routeconfig_flag branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
third-party-queries-caching	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 21, 2025 9:10 PM
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 21, 2025 9:10 PM
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 21, 2025 9:10 PM
classic-remix	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 21, 2025 9:10 PM
custom-cart-method	✅ Successful (Logs)	Preview deployment	Inspect deployment	March 21, 2025 9:10 PM

Learn more about Hydrogen's GitHub integration.

[juanpprieto]

I would wrap this instruction on a diff -/+ block instead

[juanpprieto]

Looking great Sean!

Tophat found no issues

[juanpprieto]

A reminder that we will need to add these new dependencies to our changelog.json entry when the time comes to release this

[wizardlyhel]

Updated this PR so it's just a single patch on @remix-run/dev
Related issue: remix-run/remix#10324

[wizardlyhel]

/snapit

[github-actions]

🫰✨ Thanks @wizardlyhel! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

"@shopify/cli-hydrogen": "0.0.0-snapshot-20250321172553",
"@shopify/hydrogen": "0.0.0-snapshot-20250321172553",
"@shopify/hydrogen-codegen": "0.0.0-snapshot-20250321172553",
"@shopify/mini-oxygen": "0.0.0-snapshot-20250321172553",
"@shopify/remix-oxygen": "0.0.0-snapshot-20250321172553"

Create a new project with all the released packages running npm create @shopify/hydrogen@<snapshot_version>
To try a new CLI plugin version, add @shopify/cli-hydrogen as a dependency to your project using the snapshot version.

[wizardlyhel]

/snapit

[github-actions]

🫰✨ Thanks @wizardlyhel! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

"@shopify/cli-hydrogen": "0.0.0-snapshot-20250321203919",
"@shopify/hydrogen": "0.0.0-snapshot-20250321203919",
"@shopify/hydrogen-codegen": "0.0.0-snapshot-20250321203919",
"@shopify/mini-oxygen": "0.0.0-snapshot-20250321203919",
"@shopify/remix-oxygen": "0.0.0-snapshot-20250321203919"

Create a new project with all the released packages running npm create @shopify/hydrogen@<snapshot_version>
To try a new CLI plugin version, add @shopify/cli-hydrogen as a dependency to your project using the snapshot version.

[wizardlyhel]

/snapit

[github-actions]

🫰✨ Thanks @wizardlyhel! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

"@shopify/cli-hydrogen": "0.0.0-snapshot-20250321210338",
"@shopify/hydrogen": "0.0.0-snapshot-20250321210338",
"@shopify/hydrogen-codegen": "0.0.0-snapshot-20250321210338",
"@shopify/mini-oxygen": "0.0.0-snapshot-20250321210338",
"@shopify/remix-oxygen": "0.0.0-snapshot-20250321210338"

Create a new project with all the released packages running npm create @shopify/hydrogen@<snapshot_version>
To try a new CLI plugin version, add @shopify/cli-hydrogen as a dependency to your project using the snapshot version.

[jasonloeve]

@wizardlyhel , I may have missed it but moving the layout out of root along with imports we loose the ability to have styled error pages / error messages wrapped in layout ?

[rbshop]

@jasonloeve Looks like this was done in error whilst attempting to clean up the code. We'll revert this and cut a new release ASAP. Thanks for the heads up - edit: I was wrong to say this was to clean up code, it was actually done to support some virtual routes that are exposed during local dev. Either way, we'll get this fixed ASAP