Add a page
Serve a brand-new URL, such as /faq, from your theme.
Framework: TanStack Start
This page is written for TanStack Start, the default and currently supported framework. See what depends on the framework.
Use this when the storefront needs a URL the engine does not have. This is the short version; Add a custom route covers loaders, titles and loading states.
Goal: /faq (and /ar/faq, /en/faq) shows your page.
Declare the path
import { route } from '@tanstack/virtual-file-routes';
export const routes = [route('/faq', 'faq.tsx')];Write the route file
The createFileRoute path is the same URL with the optional {-$locale} prefix in front.
import { createFileRoute } from '@tanstack/react-router';
import { useTranslation } from '@salla.sa/twilight-theme-engine/i18n';
function FaqPage() {
const { t } = useTranslation();
return (
<div className="container">
<h1>{t('pages.faq.title', 'Frequently asked questions')}</h1>
</div>
);
}
export const Route = createFileRoute('/{-$locale}/faq')({
head: () => ({ meta: [{ title: 'FAQ' }] }),
component: FaqPage,
});Restart and open it
Restart the dev server so the route tree is regenerated, then open /faq. Add the pages.faq.title key to both locale files: Add translation keys.
Check it worked
/faq and /ar/faq both render the heading. If one gives a 404, see the traps.
Traps
- A 404 right after adding the route means the route tree is stale. Restart the dev server.
- Forgetting
{-$locale}in thecreateFileRoutepath makes the page unreachable under/ar/...and/en/.... - Never put
// @auto-generatedat the top of a route file you wrote. The plugin treats that marker as disposable and overwrites the file on the next build. - Dynamic segments use TanStack syntax:
route('/promotions/$id', 'promotions.$id.tsx'). Read the value withRoute.useParams().
Next
- Add a custom route: data loading, head and skeletons.
- Routes and pages: how routes fit together.
- To change a page the engine already ships, fork a built-in route.