getFrameworkAdapter, tanstack & nextjs

In plain words

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

// 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

Source and docs

• Engine source: packages/theme-engine/src/vite/adapters/index.ts