Custom Routes

[blittle]

January 28, 2022 - Original Proposal
February 9, 2022 - Proposal 2
February 10, 2022 - API Routes Clarification
February 14, 2022 - Remove Asynchronous Route definition example

RFC Hydrogen Custom Routes

Currently routing in hydrogen is provided by the file system. If you want to create a new page, simply add a new .server.jsx component to the pages directory of your project. While this is simple and easy to get started with, it becomes difficult to manage at scale with thousands of routes and redirects. The file system also make advanced features like localized paths (/products -> /productos) very difficult.

Custom Routes is a proposed new way for developers to define Hydrogen routes independent of the file system.

Original Proposal

Our original proposal for custom routes involved defining a manifest, that would be passed directly to renderHydrogen:

import {renderHydrogen, redirect} from '@shopify/hydrogen';
import shopifyConfig from './shopify.config';

const routes = import.meta.globEager('./pages/**/*.server.[jt](s|sx)');

const customRoutes = [{
  route: '/old-route',
  handler: () => redirect('/new-route', 302),
}];

export default renderHydrogen(App, {
  shopifyConfig,
  routes,
  customRoutes,
});

While this is pattern is familiar to many developers, and inspired by NextJS, we've reviewed it internally and externally, there are a number of shortcomings with the approach:

1. The routes are defined statically on the outside. You cannot easily customize what routes are available dynamically based on any request. For example, if you want to define different routes available based on the current locale.
2. If the custom routes are dynamic, it's possible that the route definition is going to be asynchronous. The current proposal gives no mechanism for the developer to control what renders while that route definition is being fetched.
3. Adding more complex functionality, like Redwood Route Sets requires us to extend the manifest syntax. Hydrogen owns that complexity, and it's difficult (if not impossible) for the community to add and extend the functionality.

New Proposal

We believe that all of the above problems can be solved by embracing React itself to define custom routes. Instead of providing a static manifest to renderHydrogen, we'll introduce a Hydrogen specific <Route> component that can be used within App.server.jsx:

import {FileRoutes, Router, Route} from '@shopify/hydrogen';
...
export default function App({routes}) {
  return (
    ...
    <Router fallback={<NotFound />}>
      <Route path="/custom-route" page={CustomRoute} />
      <FileRoutes routes={routes} />
    </Router>
    ...
  );
}

This should look very similar to Hydrogen before the 0.10 release. We removed react router in 0.10 because server components do not yet support context (which React Router relies on). We've worked with Meta to come up with a short term solution that brings a limited form of context back. With this new approach, we can bring back the React-Router-like approach. We feel this is superior to the manifest approach for a number of reasons:

1. Dynamic by default and declarative React

This approach is dynamic by default, in that the routes are defined during the request life-cycle. You can easily customize what routes are rendered based on the current request:

export default function App({log, routes, ...serverState}) {
  const {locale} = useShop();
   
  return (
    ...
    <Router fallback={<NotFound />}>
      <Route path={locale === 'es' ? '/productos' : '/products'} page={CustomRoute} />
      <FileRoutes routes={routes} />
    </Router>
    ...
  );
}

You can also completely remove the default file system routing by removing <FileRoutes>:

export default function App({log, routes, ...serverState}) {
  return (
    ...
    <Router fallback={<NotFound />}>
      <Route path="/custom-route" page={CustomRoute} />
    </Router>
    ...
  );
}

Thousands of routes defined directly in App.server.jsx can become difficult to manage. Instead, use standard React component composition to split into multiple server components:

import SpanishRoutes from 'customRoutes/spanish.server';
import EnglishRoutes from 'customRoutes/english.server';
import SharedRoutes from 'customRoutes/shared.server';

export default function App({log, routes, ...serverState}) {
  const {locale} = useShop();
  return (
    ...
    <Router fallback={<NotFound />}>
      <SpanishRoutes locale={locale} />
      <EnglishRoutes locale={locale} />
      <SharedRoutes />
    </Router>
    ...
  );
}

2. Extensibility

Future routing extensibility can be based in React. The community can build custom Routing components without waiting for us to extend the functionality of a manifest approach. For example, someone in the community could build Redwood Route Sets without waiting for Hydrogen.

Additionally, we can still build a manifest approach that just maps to underlying <Route> components.

Relation to API Routes

API Routes exist outside React. Because of this, custom routes defined by React <Route> components cannot be an API route. API routes must exist within the file system. Custom Routes are only for defining React pages.

Custom Router API

Routes Component

A new <Routes> component will be introduced. It will not initially have any props. If you would like to remove all default routing provided by Hydrogen, just remove <Routes>. All routing must be defined within children. Once <Router> is rendered, the request will immediately be processed.

Props:

1. fallback - What to render when no route is found

Example:

<Router fallback={<NotFound />}>...</Router>

FileRoutes Component

This is the DefaultRoutes component renamed. This is where Hydrogen's default file based routing lives. Remove from App.server.jsx if you do not want to use any file system routing. Must be a child within <Router>.

Props:

1. routes - A file glob object from import.meta.globEager

Example:

<FileRoutes routes={import.meta.globEager('./routes/**/*.server.[jt](s|sx)')} />

Route Component

A new <Route> component where you can define a custom route. Must be a child within <Router>.

Props:

1. path - Required to match a path. May contain parameters: /products/:handle.
2. page - The component to render. Can be a component reference.

Examples

<Route path="/products/:handle" page={ProductDetails} />

Redirect Component

A new <Redirect> component to declaratively define redirects more easily

Props:

1. path - The path to match. May contain parameters: /products/:handle
2. to - The destination path to redirect to. May contain matched parameters.
3. permanent - If true will use the 308 status code which instructs clients/search engines to cache the redirect forever, if false will use the 307 status code which is temporary and is not cached.

<Redirect path="/old-products/:handle" to="/new-products/:handle" permanent />

Questions

Are there performance issues with dynamically defining routes on each request?

Yes. Doing so is an advanced use case. We don't expect most hydrogen sites to need to do this. It would be bad for every request to Hydrogen to hit a third party service to get route definitions. We expect Hydrogen in the future to work well with redirects defined in Shopify's storefront admin. We will introduce a <ShopifyRedirect> component with sensible defaults in how often external routes are fetched.

What happens when there are route collisions?

It is possible to define duplicate custom routes, and custom routes that also match file system routes. The first one defined will always win. For example:

export default function App() {
  return <Router>
    // If the file `routes/products.server.jsx`, there will be a collision.
    // Because `FileRoutes` is _before_ the custom Route, it matches first.
    // Move `<Route>` above `<FileRoutes>` to have the custom route take precedence
    <FileRoutes routes={fileRouteDef} />
    <Route path="/products" page={...} />
  </Router>
}

Why not use React Router?

1. React Router requires context. Context is not supported in React Server Components. In the future that will change, maybe we could migrate to React Router at that point in time. Or you could remove Hydrogen routing altogether and just use React Router.
2. Hydrogen inherently does not do client routing. When you navigate on the client, we can't just listen to URL changes and re-render the app in the client. Instead, the client has to go back to the server for React Server Components to re-render on the new page. Because of this, we never will use much of what React Router offers. And we need to build our own abstractions to handle accessibility and server state changes on routing events. If we own the router, we have a lot more control over the user experience.

[bitforcesrl]

Hi @blittle @morganmccunn, it's great to see a discussion around this important topic.
Some feedback
Its trivial to say that common commerce routes are like:

For product page
/[country]/[locale]/[localised-part]/[localised-handle-translated]
/us/en/products/nike-leather-shoes
/it/it/prodotti/nike-scarpe-di-pelle

For product list
/[country]/[locale]/[localised-part]?filters={}&pagination={}&sort={}
/us/en/shoes?filters={color:red}&pagination={page:1, size:10}&sort={prop:price,direction:desc}

Current shopify/liquid limitations are that route parts and product handle are not localised.
like /products/non-localised-handle
It will be great if in hydrogen we could achieve that, it's a must to have for an international e-commerce to get great SEO perf and to crete fine tuned landing pages and marketing campagins

The implementation that @blittle is proposing seems a good start.
i would add the query params, something like this
/shoes/:handle?:sorting&:pagination&:campaign-tag

and the possibility to have a part of the route which is an id to a key-value dictionary ex
/[shoes]/:handle

//routes dictionary
dictionary = {
  'shoes': {
    'it': 'scarpe',
    'en': 'shoes'
  }
}

This requires a companion component and hook (to be used from controllers) to create a navigation helpers that can read from this dictionary
<HydroLink route={['{shoes}', shoesHandle]} label="{t(dict.products)}">
It could help to have a country and locale set by the component himself or can be passed explicitly reading the values from the hook

I suggest to create in hydro some hook that when the user change locale or country the path will be updated accordingly so

//SetLocale.client.jsx
[locale, setLocale] = useLocale()
onLocaleChange(newLocale) {
  setLocale(newLocale)
}

// useLocale.hook.jsx
setLocale(locale) {
  _set:ocale(newLocale);
  setServerState('locale', newLocale); // needed to trigger the react server component refresh /react
  updateRouteVariable('locale', newLocale) // needed to update the route pushing a new element in the history
}

if you don't want to do this in a too much opinionated way you could create two different hook
setLocale()
setLocaleAndRoute()

NOTE:
Since the route parts variable state will be in two places (or three) we should have an easy way to don't create mess with state sync
Example for locale the state will be inside

• the hook (useLocale)
• in the URL route, available as variable inside the server component eg ServerComponent({params}) { const {locale} = params;}
• in the server component input prop needed for the page refresh ex ServerComponent({locale}) { ... }

The main goal of this topic to me is

• An easy and clear way to deal with county locale route parts, that are variables used in route and internally in several components and graphQl queries
• A way to have some localised path parts based on dictionary
• A way to pass query params
• Access to all path parts from components with hooks or server variables

[blittle]

@bitforcesrl you have some great ideas in here. This is probably one of the best usecases I've seen for custom routes outside the file system, where the actual route URL parts themselves are localized. Regarding updating the locale. I think generally changing the locale will always mean a navigation event. So our exposed <Link> component should have a locale prop, as well as the imperative API: let navigate = useNavigate(); navigate('/some/path', { locale: 'es' })

[bitforcesrl]

also country could fit in this scenario navigate('/some/{localised-part}', { locale: 'es' , country: 'en'})
navigate will change the URL and set (batch to avoid two /react call) the new serverState() for locale and country

In this way locale will be passed in the graphQl http-header (i've done that PR :) ) and the country will be used in the @incontext(country: $country) graphQl decorator

[nschomberg]

@blittle I think this looks great. The ability to centralize our routing logic at the entry-server level would be a big win. It would make it so we don't have to duplicate redirect logic across multiple Page Components when porting over our legacy Shopify Theme redirects.

In your proposal, the list of custom routes is hardcoded into the codebase. Have you considered what this might look like if you had a list of redirects that was managed externally?

I'm also curious how you're thinking about dynamic routing use cases (e.g. dynamically splitting traffic between 2 pages for an A/B test). Do you feel like that would be a custom routing concern, or maybe more of a Server Component concern? I'm wondering if we could benefit from another type of route where a (potentially async) function can return a Server Component. Something along the lines of:

const customRoutes = [
  {
    route: '/products/:handle',
    component: async ({ request, response, params }) => {
      let abTestVariant = request.cookies.get('my-ab-test');

      if (!abTestVariant) {
        abTestVariant = await determineAbTestVariant({ params });
        response.headers.set('Set-Cookie', `my-ab-test=${abTestVariant}`);
      }

      return {
        component: abTestVariant === 'page-a' ? PageA : PageB,
        props: { myCustomProp: abTestVariant }
      }
    },
  }
];

[blittle]

Yes @nschomberg, I think you've identified a potential downside to the current proposal. We've worked on this internally and I'll post updates shortly.

[blittle]

@nschomberg @bitforcesrl the proposal has been updated.

[nschomberg]

Looks good to me. Thanks for addressing the feedback!

[bitforcesrl]

@blittle it seems cool! When we could expect to test this new router ?

translated route parts are super
<Route path={locale === 'es' ? '/productos' : '/products'} page={CustomRoute} />

will this works too?
<Route path={locale === 'es' ? '/productos' : '/products'} page={locale === 'es' ? EsProducts : EsProducts} />

how can we lazy import EsProducts and EsProducts ?

[blittle]

Hi @bitforcesrl I'm working on it now! You can follow progress here: Shopify/hydrogen#712

Yes! conditional pages should also be possible. Lazy loading them will be possible too, with the one caveat that you can't lazily define redirects. Once you are lazily doing stuff in a server component, a rendered fallback has already been sent to the client at the suspense boundary. Once you finally load the routes, it is now too late to send a redirect 301 response with location headers, because those headers have already flushed to the client.

[natew]

Hydrogen inherently does not do client routing

Curious - is this an inherent constraint of RSC, a design decision, or just a current limitation? I can see why it's this way in theory at least, but curious the actual technical reasoning.

One nice thing about client-side is that you can animate into your new state immediately, show a loading skeleton, and then fill in once data comes in. This feels nicer to me than the alternative of "leave old state around with a loading indicator". Is it true that the latter isn't possible with RSC or is it just a Hydrogen decision to not ship client-side routing / fetching?