Add a custom route

The engine already serves every built-in page. Add a custom route when you need a URL it does not have, such as /new-arrivals, /faq or /promotions/summer. To change a page the engine already has, use Fork a built-in route instead.

Adding a route takes two edits: one line in app/routes.ts and one file in app/routes/.

import { route } from '@tanstack/virtual-file-routes';

export const routes = [
  route('/new-arrivals', 'new-arrivals.tsx'),
];

import { createFileRoute } from '@tanstack/react-router';
import { useTranslation } from '@salla.sa/twilight-theme-engine/i18n';
import { product } from '@salla.sa/twilight-theme-engine/api/product';
import { getTwilightContext } from '@salla.sa/twilight-theme-engine/tanstack';
import { ProductCard } from '@salla.sa/twilight-theme-engine/product';

export const Route = createFileRoute('/{-$locale}/new-arrivals')({
  loader: () => {
    const { queryClient } = getTwilightContext();
    return queryClient.fetchQuery(product.queries.list({ source: 'latest', perPage: 12 }));
  },
  head: () => ({ meta: [{ title: 'New arrivals' }] }),
  component: NewArrivals,
});

function NewArrivals() {
  const { t } = useTranslation();
  const { items } = Route.useLoaderData();

  return (
    <div className="container">
      <h1>{t('pages.new_arrivals.title', 'New arrivals')}</h1>
      <div className="grid grid-cols-2 gap-4 md:grid-cols-4">
        {items.map((item) => (
          <ProductCard key={item.id} product={item} />
        ))}
      </div>
    </div>
  );
}

The parts of a route fileCopy Anchor Link

URLs with a value in themCopy Anchor Link

Put a $ before the part that changes, in both the manifest and the route path:

route('/promotions/$id', 'promotions.$id.tsx'),

import { createFileRoute } from '@tanstack/react-router';
import { product } from '@salla.sa/twilight-theme-engine/api/product';

export const Route = createFileRoute('/{-$locale}/promotions/$id')({
  loader: ({ params }) => product.findOrThrow(params.id),
  head: ({ loaderData }) => ({ meta: [{ title: loaderData?.name }] }),
  component: Promotion,
});

function Promotion() {
  const item = Route.useLoaderData();
  const { id } = Route.useParams();
  return <h1>{item.name} (#{id})</h1>;
}

params also holds locale, which is undefined when the URL has no language prefix. A value can be mixed with fixed text, like the engine's own /$slug/p{$id} for products.

Query stringsCopy Anchor Link

To read ?page=2, describe the search params you accept with validateSearch:

export const Route = createFileRoute('/{-$locale}/new-arrivals')({
  validateSearch: (search: Record<string, unknown>) => ({
    page: Number(search.page) || 1,
  }),
  loaderDeps: ({ search }) => ({ page: search.page }),
  loader: ({ deps }) => {
    const { queryClient } = getTwilightContext();
    return queryClient.fetchQuery(
      product.queries.list({ source: 'latest', perPage: 12, page: deps.page })
    );
  },
  // head and component as above (with the same imports)
});

loaderDeps is what makes the loader run again when ?page= changes.

Loading and missing dataCopy Anchor Link

• While loading: add pendingComponent: () => <Skeleton />. The engine ships skeletons for its own pages, see the skeleton components.
• Not found: the ...OrThrow functions on the API modules (product.findOrThrow) turn a 404 or 410 answer into the engine's not-found page. Any other error reaches the router's error page. See Errors, timeouts and retries.
• Signed-out customers: a page that only works for signed-in customers should check useUser().isLoggedIn in its component and show a sign-in prompt instead of the content.

Link to your pageCopy Anchor Link

Use the engine's Link so the language prefix is kept:

import { Link } from '@salla.sa/twilight-theme-engine/common';

<Link to="/new-arrivals">New arrivals</Link>

Add it to the menuCopy Anchor Link

A route is only a URL. A merchant adds it to a menu in the dashboard, or you link to it from a component in the header or footer (Layout and components).

Common mistakesCopy Anchor Link

NextCopy Anchor Link

• Overview: every built-in route, to copy patterns from
• SEO redirects: send an old URL to a new one
• Routes and pages: the concepts behind app/routes.ts
• Add a page: the short recipe