Skip to content
Twilight React Playground
ثيم رائدaren

getFrameworkAdapter, tanstack & nextjs

functionAdvanced

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

import { getFrameworkAdapter, tanstack, nextjs, FrameworkAdapter } from '@salla.sa/twilight-theme-engine/vite';

In plain words

twilightReact() does its work through an adapter: an object that knows how to connect the engine to one framework. The engine ships two. tanstack is the one every theme uses; nextjs only reserves the name and throws when used.

A theme never needs these. They exist for scripts that want one step of twilightReact() on its own, such as regenerating the route files.

Signature

function getFrameworkAdapter(framework: 'tanstack' | 'nextjs'): FrameworkAdapter

const tanstack: FrameworkAdapter;   // name 'tanstack'
const nextjs: FrameworkAdapter;     // name 'nextjs'; both methods throw

interface FrameworkAdapter {
  name: string;
  generateRouteFiles: (options: {
    projectRoot: string;
    baseRoutes?: TwilightRoute[];   // replaces the engine's built-in routes
    baseRoutesImport: string;
  }) => TwilightRoute[];
  createPlugins: (options: TwilightReactOptions) => Promise<PluginOption[]>;
}

Example

scripts/print-routes.mjs
// Node, from the theme folder. Writes app/routes/* like a dev start would.
import { tanstack } from '@salla.sa/twilight-theme-engine/vite';

const routes = tanstack.generateRouteFiles({
  projectRoot: process.cwd(),
  baseRoutesImport: '@salla.sa/twilight-theme-engine/routes',
});

console.table(routes.map(({ path, file, factory }) => ({ path, file, factory })));

How it behaves

  • twilightReact(options) is getFrameworkAdapter(options.framework ?? 'tanstack').createPlugins(options), after pointing the engine's head helpers at that framework inside the Vite process.

  • tanstack.generateRouteFiles reads app/routes.ts under projectRoot, merges its routes over baseRoutes (or the built-in list) by path, writes app/routes/*.tsx for files that are missing or still start with // @auto-generated, writes the locale, account and redirect wrappers into the engine package's .twilight/ folder, and returns the merged route table.

  • tanstack.createPlugins calls generateRouteFiles once right away and again in the config hook with Vite's root, then returns the plugin list described on twilightReact.

  • getFrameworkAdapter throws [twilight-react] Unsupported framework: <name> for any other name. There is no way to register a third adapter: a custom one is used by calling its createPlugins yourself in vite.config.ts.

  • The /nextjs subpath is a different thing: runtime helpers for a Next.js app, in the framework group. It does not make this adapter work.

Gotchas

  • generateRouteFiles writes files, and baseRoutes replaces the built-in list instead of adding to it: pass baseRoutes: [myRoute] and every built-in page disappears from the generated table. Fix: leave baseRoutes out and add pages through app/routes.ts.

  • An app/routes.ts that fails to compile or run only logs a warning and counts as no custom routes; generateRouteFiles does not throw.

  • nextjs, and twilightReact({ framework: 'nextjs' }), throw [twilight-react:nextjs] Next.js framework support is not yet implemented.

  • packages/theme-engine/src/vite/README.md shows an adapter with createRouterPlugin and createReactPlugin, and imports GenerateRoutesOptions from /vite. Neither exists: the interface has createPlugins, and the options type is Parameters<FrameworkAdapter['generateRouteFiles']>[0].

Related

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.

TwilightRoute & option types

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

Source and docs