TwilightRoute & option types

typeAdvanced

Supporting types of /vite: one row of the generated route table, the framework names, and option shapes twilightReact() accepts but ignores.

import { TwilightRoute, Framework, ReactPluginOptions, TanStackRouterOptions, NextJsRouterOptions, RouterOptions } from '@salla.sa/twilight-theme-engine/vite';

In plain words

These are TypeScript shapes, not code that runs. TwilightRoute is one row of the engine's route table: the URL path, the file in app/routes/, and the name of the engine function that builds that page.

The other types describe option objects twilightReact() accepts for react and router but, today, does not use.

Signature

interface TwilightRoute {
  path: string;        // '/cart', '/$slug/p{$id}'
  file: string;        // 'cart.tsx', inside app/routes/
  factory: string;     // 'createCartRouteConfig'; 'createCustomRoute_<file>' for app/routes.ts entries
  id?: string;         // a RouteId on built-in pages; absent on your own routes
  isIndex?: boolean;   // the '/' page
  isLayout?: boolean;  // '/account': no file; '/account/…' rows nest inside it
}

type Framework = 'tanstack' | 'nextjs';

interface ReactPluginOptions {
  jsxRuntime?: 'automatic' | 'classic';
  jsxImportSource?: string;
  babel?: Record<string, any>;
  [key: string]: any;
}

interface TanStackRouterOptions {
  routesDirectory?: string;
  generatedRouteTree?: string;
  virtualRouteConfig?: unknown;
  rootRoute?: string;
  routesFile?: string;
  [key: string]: any;
}

interface NextJsRouterOptions { [key: string]: any }
type RouterOptions = TanStackRouterOptions | NextJsRouterOptions;

Example

scripts/routes.ts

import type { TwilightRoute } from '@salla.sa/twilight-theme-engine/vite';

// The row that route('/lookbook', 'lookbook.tsx') in app/routes.ts becomes.
// Its router id is '/{-$locale}/lookbook'.
export const lookbook: TwilightRoute = {
  path: '/lookbook',
  file: 'lookbook.tsx',
  factory: 'createCustomRoute_lookbook_tsx',
};

How it behaves

A custom row's factory is createCustomRoute_ plus the file name with every character other than a letter or digit turned into _. It matters only when the file is missing and the generator writes a placeholder importing that name.
Built-in rows look like { path: '/cart', file: 'cart.tsx', factory: 'createCartRouteConfig', id: RouteId.CART }; the list itself is not exported.
A row's router id is /{-$locale} plus its path (/{-$locale}/ for the index), and rows under /account/ nest inside the account layout.
ReactPluginOptions and TanStackRouterOptions document an older design. Today twilightReact calls @vitejs/plugin-react() with no options and passes TanStack Start only srcDirectory and the generated route config.

Gotchas

Every option shape ends in [key: string]: any, so a misspelled key type-checks, and because the adapter ignores react and router, nothing tells you the value was never used.

getFrameworkAdapter, tanstack & nextjs

The adapter objects behind twilightReact(): tanstack generates route files and returns the Vite plugins; nextjs is a placeholder whose methods throw.

twilightReact

The one Vite plugin call in a theme's vite.config.ts: server rendering, a route for every storefront page, translations and build checks.

Source and docs

Engine source: packages/theme-engine/src/vite/types.ts

In plain words

Signature

Example

How it behaves

Gotchas

Related

Source and docs