@octanejs/tanstack-start 0.1.0

package/src/internal/start-plugin-core/types.d.ts

@@ -0,0 +1,135 @@
+import { GeneratorResult } from '@tanstack/router-utils';
+import { GeneratorPlugin } from '#tanstack-start/router-generator';
+import { TanStackStartOutputConfig } from './schema.js';
+import type * as babel from '@babel/core';
+import type * as t from '@babel/types';
+export declare const startFrameworks: readonly ['react', 'solid', 'vue', 'octane'];
+export type CompileStartFrameworkOptions = (typeof startFrameworks)[number];
+export type ServerFnLookupAccess =
+	| {
+			origin: 'client';
+	  }
+	| {
+			origin: 'server';
+	  };
+export type SerializationRuntime = 'client' | 'server';
+export interface SerializationAdapterModuleRef {
+	module: string;
+	export: string;
+	isFactory?: boolean;
+}
+export type SerializationAdapterByRuntime = Partial<
+	Record<SerializationRuntime, SerializationAdapterModuleRef>
+>;
+export type SerializationAdapterConfig =
+	| SerializationAdapterModuleRef
+	| SerializationAdapterByRuntime;
+export type StartCompilerEnvironment = 'client' | 'server';
+export interface StartCompilerImportTransformImport {
+	libName: string;
+	rootExport: string;
+}
+export interface StartCompilerTransformCandidate {
+	path: babel.NodePath<t.CallExpression>;
+}
+export interface StartCompilerTransformContext {
+	readonly ast: t.File;
+	readonly code: string;
+	readonly id: string;
+	readonly env: StartCompilerEnvironment;
+	readonly envName: string;
+	readonly mode: 'dev' | 'build';
+	readonly root: string;
+	readonly framework: CompileStartFrameworkOptions;
+	readonly providerEnvName: string;
+	readonly types: typeof t;
+	parseExpression: (code: string) => t.Expression;
+	warn?: (message: string) => void;
+}
+export interface StartCompilerImportTransform {
+	name: string;
+	environment?: StartCompilerEnvironment | Array<StartCompilerEnvironment> | undefined;
+	imports: Array<StartCompilerImportTransformImport>;
+	detect: RegExp;
+	order?: 'pre' | 'post' | undefined;
+	transform: (
+		candidates: Array<StartCompilerTransformCandidate>,
+		context: StartCompilerTransformContext,
+	) => void;
+}
+export interface StartCompilerTransformResult {
+	code: string;
+	map?: GeneratorResult['map'] | null;
+}
+export interface StartCompilerVirtualModuleContext {
+	readonly id: string;
+	readonly root: string;
+	readonly env: StartCompilerEnvironment;
+	readonly envName: string;
+	readonly code?: string;
+}
+export interface StartCompilerPlugin {
+	name: string;
+	environment?: StartCompilerEnvironment | Array<StartCompilerEnvironment> | undefined;
+	detect?: RegExp | undefined;
+	virtualModuleIdPattern?: RegExp | undefined;
+	transformAst?: (context: StartCompilerTransformContext) => boolean | null | undefined;
+	loadVirtualModule?: (
+		context: StartCompilerVirtualModuleContext,
+	) => StartCompilerTransformResult | null;
+	invalidateModule?: (context: { id: string; envName: string }) => void;
+}
+export interface NormalizedBasePaths {
+	publicBase: string;
+	assetBase: {
+		dev: string;
+		build: string;
+	};
+}
+export interface NormalizedOutputDirectories {
+	client: string;
+	server: string;
+}
+export interface NormalizedClientChunk {
+	fileName: string;
+	isEntry: boolean;
+	imports: Array<string>;
+	dynamicImports: Array<string>;
+	css: Array<string>;
+	routeFilePaths: Array<string>;
+	hydrationIds: Array<string>;
+}
+export interface NormalizedClientBuild {
+	entryChunkFileName: string;
+	chunksByFileName: ReadonlyMap<string, NormalizedClientChunk>;
+	chunkFileNamesByRouteFilePath: ReadonlyMap<string, ReadonlyArray<string>>;
+	cssFilesBySourcePath: ReadonlyMap<string, ReadonlyArray<string>>;
+	cssContentByFileName?: ReadonlyMap<string, string>;
+}
+export interface TanStackStartCoreOptions {
+	framework: CompileStartFrameworkOptions;
+	defaultEntryPaths: {
+		client: string;
+		server: string;
+		start: string;
+	};
+	providerEnvironmentName: string;
+	ssrIsProvider: boolean;
+	serializationAdapters?: Array<SerializationAdapterConfig> | undefined;
+	compilerTransforms?: Array<StartCompilerImportTransform> | undefined;
+	serverFnProviderModuleDirectives?: ReadonlyArray<string> | undefined;
+	/** Framework-owned route source adapters and generator extensions. */
+	routerGeneratorPlugins?: ReadonlyArray<GeneratorPlugin> | undefined;
+}
+export interface ResolvedStartConfig {
+	root: string;
+	startFilePath: string | undefined;
+	routerFilePath: string;
+	srcDirectory: string;
+	basePaths: NormalizedBasePaths;
+	outputDirectories: NormalizedOutputDirectories;
+}
+export type GetConfigFn = () => {
+	startConfig: TanStackStartOutputConfig;
+	resolvedStartConfig: ResolvedStartConfig;
+};

package/src/internal/start-plugin-core/types.js

@@ -0,0 +1,4 @@
+//#region src/types.ts
+var startFrameworks = ['react', 'solid', 'vue', 'octane'];
+//#endregion
+export { startFrameworks };

package/src/internal/start-plugin-core/utils.d.ts

@@ -0,0 +1,13 @@
+/** Read `build.rollupOptions` or `build.rolldownOptions` from a build config. */
+export declare function getBundlerOptions(build: any): any;
+export declare function resolveViteId(id: string): string;
+export declare function createIdFilter(ids: Array<string>): RegExp;
+export declare function escapeRegExp(value: string): string;
+export declare function createLogger(prefix: string): {
+	log: (...args: any) => void;
+	debug: (...args: any) => void;
+	info: (...args: any) => void;
+	warn: (...args: any) => void;
+	error: (...args: any) => void;
+};
+export declare function normalizePath(id: string): string;

package/src/internal/start-plugin-core/utils.js

@@ -0,0 +1,42 @@
+import path from 'node:path';
+//#region src/utils.ts
+var isWindows = typeof process !== 'undefined' && process.platform === 'win32';
+var windowsSlashRE = /\\/g;
+/** Read `build.rollupOptions` or `build.rolldownOptions` from a build config. */
+function getBundlerOptions(build) {
+	return build?.rolldownOptions ?? build?.rollupOptions;
+}
+function resolveViteId(id) {
+	return `\0${id}`;
+}
+function createIdFilter(ids) {
+	return new RegExp(`^(?:${ids.map(escapeRegExp).join('|')})$`);
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function createLogger(prefix) {
+	const label = `[${prefix}]`;
+	return {
+		log: (...args) => console.log(label, ...args),
+		debug: (...args) => console.debug(label, ...args),
+		info: (...args) => console.info(label, ...args),
+		warn: (...args) => console.warn(label, ...args),
+		error: (...args) => console.error(label, ...args),
+	};
+}
+function slash(path) {
+	return path.replace(windowsSlashRE, '/');
+}
+function normalizePath(id) {
+	return path.posix.normalize(isWindows ? slash(id) : id);
+}
+//#endregion
+export {
+	createIdFilter,
+	createLogger,
+	escapeRegExp,
+	getBundlerOptions,
+	normalizePath,
+	resolveViteId,
+};

package/src/internal/start-plugin-core/vite/createVirtualModule.d.ts

@@ -0,0 +1,15 @@
+import { Plugin } from 'vite';
+type VirtualModuleLoadHandler = (
+	this: any,
+	id: string,
+) => string | null | undefined | Promise<string | null | undefined>;
+export declare function createVirtualModule(opts: {
+	name: string;
+	moduleId: string;
+	load: VirtualModuleLoadHandler;
+	apply?: Plugin['apply'];
+	applyToEnvironment?: Plugin['applyToEnvironment'];
+	enforce?: Plugin['enforce'];
+	sharedDuringBuild?: boolean;
+}): Plugin;
+export {};

package/src/internal/start-plugin-core/vite/createVirtualModule.js

@@ -0,0 +1,27 @@
+import { createIdFilter, resolveViteId } from '../utils.js';
+//#region src/vite/createVirtualModule.ts
+function createVirtualModule(opts) {
+	const resolvedId = resolveViteId(opts.moduleId.replaceAll('#', '%23'));
+	return {
+		name: opts.name,
+		apply: opts.apply,
+		applyToEnvironment: opts.applyToEnvironment,
+		enforce: opts.enforce,
+		sharedDuringBuild: opts.sharedDuringBuild,
+		resolveId: {
+			filter: { id: createIdFilter([opts.moduleId]) },
+			handler(id) {
+				if (id === opts.moduleId) return resolvedId;
+			},
+		},
+		load: {
+			filter: { id: createIdFilter([resolvedId]) },
+			handler(id) {
+				if (id !== resolvedId) return;
+				return opts.load.call(this, id);
+			},
+		},
+	};
+}
+//#endregion
+export { createVirtualModule };

package/src/internal/start-plugin-core/vite/dev-server-plugin/dev-styles.d.ts

@@ -0,0 +1,26 @@
+import { ViteDevServer } from 'vite';
+export declare const CSS_MODULES_REGEX: RegExp;
+export declare function normalizeCssModuleCacheKey(idOrFile: string): string;
+export declare function isCssModulesFile(file: string): boolean;
+export interface CollectDevStylesOptions {
+	viteDevServer: ViteDevServer;
+	entries: Array<string>;
+	/** Cache of CSS modules content captured during transform hook */
+	cssModulesCache?: Record<string, string>;
+}
+/**
+ * Collect CSS content from the module graph starting from the given entry points.
+ */
+export declare function collectDevStyles(
+	opts: CollectDevStylesOptions,
+): Promise<string | undefined>;
+/**
+ * Extract CSS content from Vite's transformed CSS module code.
+ *
+ * Vite embeds CSS into the module as a JS string via `JSON.stringify(cssContent)`,
+ * e.g. `const __vite__css = ${JSON.stringify('...css...')}`.
+ *
+ * We locate that JSON string literal and run `JSON.parse` on it to reverse the
+ * escaping (\\n, \\t, \\", \\\\, \\uXXXX, etc.).
+ */
+export declare function extractCssFromCode(code: string): string | undefined;

package/src/internal/start-plugin-core/vite/dev-server-plugin/dev-styles.js

@@ -0,0 +1,165 @@
+import path from 'node:path';
+//#region src/vite/dev-server-plugin/dev-styles.ts
+/**
+ * CSS collection for dev mode.
+ * Crawls the Vite module graph to collect CSS from the router entry and all its dependencies.
+ */
+var CSS_FILE_REGEX = /\.(css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:$|\?)/;
+var CSS_MODULES_REGEX = /\.module\.(css|less|sass|scss|styl|stylus)(?:$|[?#])/i;
+function normalizeCssModuleCacheKey(idOrFile) {
+	return idOrFile.split('?')[0].split('#')[0].replace(/\\/g, '/');
+}
+var CSS_SIDE_EFFECT_FREE_PARAMS = ['url', 'inline', 'raw', 'inline-css'];
+var VITE_CSS_MARKER = 'const __vite__css = ';
+var ESCAPE_CSS_COMMENT_START_REGEX = /\/\*/g;
+var ESCAPE_CSS_COMMENT_END_REGEX = /\*\//g;
+function isCssFile(file) {
+	return CSS_FILE_REGEX.test(file);
+}
+function isCssModulesFile(file) {
+	return CSS_MODULES_REGEX.test(file);
+}
+function hasCssSideEffectFreeParam(url) {
+	const queryString = url.split('?')[1];
+	if (!queryString) return false;
+	const params = new URLSearchParams(queryString);
+	return CSS_SIDE_EFFECT_FREE_PARAMS.some(
+		(param) =>
+			params.get(param) === '' && !url.includes(`?${param}=`) && !url.includes(`&${param}=`),
+	);
+}
+/**
+ * Resolve a file path to a Vite dev server URL.
+ * Files within the root directory use relative paths, files outside use /@fs prefix.
+ */
+function resolveDevUrl(rootDirectory, filePath) {
+	const normalizedPath = filePath.replace(/\\/g, '/');
+	const relativePath = path.posix.relative(rootDirectory.replace(/\\/g, '/'), normalizedPath);
+	if (!relativePath.startsWith('..') && !path.isAbsolute(relativePath))
+		return path.posix.join('/', relativePath);
+	return path.posix.join('/@fs', normalizedPath);
+}
+/**
+ * Collect CSS content from the module graph starting from the given entry points.
+ */
+async function collectDevStyles(opts) {
+	const { viteDevServer, entries, cssModulesCache = {} } = opts;
+	const styles = /* @__PURE__ */ new Map();
+	const visited = /* @__PURE__ */ new Set();
+	const rootDirectory = viteDevServer.config.root;
+	await Promise.all(
+		entries.map((entry) =>
+			processEntry(viteDevServer, resolveDevUrl(rootDirectory, entry), visited),
+		),
+	);
+	const cssPromises = [];
+	for (const dep of visited) {
+		if (hasCssSideEffectFreeParam(dep.url)) continue;
+		if (dep.file && isCssModulesFile(dep.file)) {
+			const css = cssModulesCache[normalizeCssModuleCacheKey(dep.file)];
+			if (!css) continue;
+			styles.set(dep.url, css);
+			continue;
+		}
+		if (!isCssFile(dep.file ?? dep.url)) continue;
+		cssPromises.push(
+			fetchCssFromModule(viteDevServer, dep).then((css) => (css ? [dep.url, css] : null)),
+		);
+	}
+	const cssResults = await Promise.all(cssPromises);
+	for (const result of cssResults) if (result) styles.set(result[0], result[1]);
+	if (styles.size === 0) return void 0;
+	const parts = [];
+	for (const [fileName, css] of styles.entries()) {
+		const escapedFileName = fileName
+			.replace(ESCAPE_CSS_COMMENT_START_REGEX, '/\\*')
+			.replace(ESCAPE_CSS_COMMENT_END_REGEX, '*\\/');
+		parts.push(`\n/* ${escapedFileName} */\n${css}`);
+	}
+	return parts.join('\n');
+}
+/**
+ * Process an entry URL: transform it if needed, get the module node, and crawl its dependencies.
+ */
+async function processEntry(viteDevServer, entryUrl, visited) {
+	let node = await viteDevServer.moduleGraph.getModuleByUrl(entryUrl);
+	if (!node?.ssrTransformResult) {
+		try {
+			await viteDevServer.transformRequest(entryUrl);
+		} catch {}
+		node = await viteDevServer.moduleGraph.getModuleByUrl(entryUrl);
+	}
+	if (!node || visited.has(node)) return;
+	visited.add(node);
+	await findModuleDeps(viteDevServer, node, visited);
+}
+/**
+ * Find all module dependencies by crawling the module graph.
+ * Uses transformResult.deps for URL-based lookups (parallel) and
+ * importedModules for already-resolved nodes (parallel).
+ */
+async function findModuleDeps(viteDevServer, node, visited) {
+	const deps = node.ssrTransformResult?.deps ?? node.transformResult?.deps ?? null;
+	const importedModules = node.importedModules;
+	if ((!deps || deps.length === 0) && importedModules.size === 0) return;
+	const branches = [];
+	if (deps)
+		for (const depUrl of deps) {
+			const dep = await viteDevServer.moduleGraph.getModuleByUrl(depUrl);
+			if (!dep) continue;
+			if (visited.has(dep)) continue;
+			visited.add(dep);
+			branches.push(findModuleDeps(viteDevServer, dep, visited));
+		}
+	for (const depNode of importedModules) {
+		if (visited.has(depNode)) continue;
+		visited.add(depNode);
+		branches.push(findModuleDeps(viteDevServer, depNode, visited));
+	}
+	if (branches.length === 1) {
+		await branches[0];
+		return;
+	}
+	await Promise.all(branches);
+}
+async function fetchCssFromModule(viteDevServer, node) {
+	const cachedCode = node.transformResult?.code ?? node.ssrTransformResult?.code;
+	if (cachedCode) return extractCssFromCode(cachedCode);
+	try {
+		const transformResult = await viteDevServer.transformRequest(node.url);
+		if (!transformResult?.code) return void 0;
+		return extractCssFromCode(transformResult.code);
+	} catch {
+		return;
+	}
+}
+/**
+ * Extract CSS content from Vite's transformed CSS module code.
+ *
+ * Vite embeds CSS into the module as a JS string via `JSON.stringify(cssContent)`,
+ * e.g. `const __vite__css = ${JSON.stringify('...css...')}`.
+ *
+ * We locate that JSON string literal and run `JSON.parse` on it to reverse the
+ * escaping (\\n, \\t, \\", \\\\, \\uXXXX, etc.).
+ */
+function extractCssFromCode(code) {
+	const startIdx = code.indexOf(VITE_CSS_MARKER);
+	if (startIdx === -1) return void 0;
+	const valueStart = startIdx + 20;
+	if (code.charCodeAt(valueStart) !== 34) return void 0;
+	const codeLength = code.length;
+	let i = valueStart + 1;
+	while (i < codeLength) {
+		const charCode = code.charCodeAt(i);
+		if (charCode === 34)
+			try {
+				return JSON.parse(code.slice(valueStart, i + 1));
+			} catch {
+				return;
+			}
+		if (charCode === 92) i += 2;
+		else i++;
+	}
+}
+//#endregion
+export { CSS_MODULES_REGEX, collectDevStyles, normalizeCssModuleCacheKey };

package/src/internal/start-plugin-core/vite/dev-server-plugin/plugin.d.ts

@@ -0,0 +1,11 @@
+import { PluginOption } from 'vite';
+import { GetConfigFn } from '../../types.js';
+export declare function devServerPlugin({
+	getConfig: _getConfig,
+	devSsrStylesEnabled,
+	installDevServerMiddleware,
+}: {
+	getConfig: GetConfigFn;
+	devSsrStylesEnabled: boolean;
+	installDevServerMiddleware: boolean | undefined;
+}): PluginOption;

package/src/internal/start-plugin-core/vite/dev-server-plugin/plugin.js

@@ -0,0 +1,170 @@
+import { ENTRY_POINTS, VITE_ENVIRONMENT_NAMES } from '../../constants.js';
+import { CSS_MODULES_REGEX, collectDevStyles, normalizeCssModuleCacheKey } from './dev-styles.js';
+import { isRunnableDevEnvironment } from 'vite';
+import { NodeRequest, sendNodeResponse } from 'srvx/node';
+//#region src/vite/dev-server-plugin/plugin.ts
+function devServerPlugin({
+	getConfig: _getConfig,
+	devSsrStylesEnabled,
+	installDevServerMiddleware,
+}) {
+	let isTest = false;
+	const cssModulesCache = {};
+	return [
+		{
+			name: 'tanstack-start-core:dev-server',
+			config(_userConfig, { mode }) {
+				isTest = isTest ? isTest : mode === 'test';
+			},
+			transform: {
+				filter: { id: CSS_MODULES_REGEX },
+				handler(code, id) {
+					cssModulesCache[normalizeCssModuleCacheKey(id)] = code;
+				},
+			},
+			configureServer(viteDevServer) {
+				if (isTest) return;
+				if (devSsrStylesEnabled)
+					viteDevServer.middlewares.use(async (req, res, next) => {
+						const url = req.url ?? '';
+						if (!url.split('?')[0]?.endsWith('/@tanstack-start/styles.css')) return next();
+						try {
+							const routesParam = new URL(url, 'http://localhost').searchParams.get('routes');
+							const routeIds = routesParam ? routesParam.split(',') : [];
+							const entries = [];
+							const routesManifest = globalThis.TSS_ROUTES_MANIFEST;
+							if (routesManifest && routeIds.length > 0)
+								for (const routeId of routeIds) {
+									const route = routesManifest[routeId];
+									if (route?.filePath) entries.push(route.filePath);
+								}
+							const css =
+								entries.length > 0
+									? await collectDevStyles({
+											viteDevServer,
+											entries,
+											cssModulesCache,
+										})
+									: void 0;
+							res.setHeader('Content-Type', 'text/css');
+							res.setHeader('Cache-Control', 'no-store');
+							res.end(css ?? '');
+						} catch (e) {
+							console.error('[tanstack-start] Error collecting dev styles:', e);
+							res.setHeader('Content-Type', 'text/css');
+							res.setHeader('Cache-Control', 'no-store');
+							res.end(
+								`/* Error collecting styles: ${e instanceof Error ? e.message : String(e)} */`,
+							);
+						}
+					});
+				if (viteDevServer.config.experimental.bundledDev)
+					viteDevServer.watcher.add(viteDevServer.config.root);
+				return () => {
+					const serverEnv = viteDevServer.environments[VITE_ENVIRONMENT_NAMES.server];
+					if (!serverEnv)
+						throw new Error(`Server environment ${VITE_ENVIRONMENT_NAMES.server} not found`);
+					const clientEnv = viteDevServer.environments[VITE_ENVIRONMENT_NAMES.client];
+					const installMiddleware = installDevServerMiddleware;
+					if (installMiddleware === false) return;
+					if (installMiddleware == void 0) {
+						if (viteDevServer.config.server.middlewareMode) return;
+						if (!isRunnableDevEnvironment(serverEnv) || 'dispatchFetch' in serverEnv) return;
+					}
+					if (!isRunnableDevEnvironment(serverEnv))
+						throw new Error(
+							'cannot install vite dev server middleware for TanStack Start since the SSR environment is not a RunnableDevEnvironment',
+						);
+					viteDevServer.middlewares.use(async (req, res) => {
+						if (req.originalUrl) req.url = req.originalUrl;
+						const webReq = new NodeRequest({
+							req,
+							res,
+						});
+						try {
+							const serverRunner = serverEnv.runner;
+							/**
+							 * export default {
+							 *  fetch(req: Request): Promise<Response>
+							 * }
+							 */
+							if (viteDevServer.config.experimental.bundledDev) {
+								await clientEnv?.devEngine?.ensureLatestBuildOutput?.();
+								serverEnv.moduleGraph.invalidateAll();
+								serverRunner.clearCache();
+							}
+							return sendNodeResponse(
+								res,
+								await (await serverRunner.import(ENTRY_POINTS.server))['default'].fetch(webReq),
+							);
+						} catch (e) {
+							console.error(e);
+							try {
+								viteDevServer.ssrFixStacktrace(e);
+							} catch {}
+							if (webReq.headers.get('content-type')?.includes('application/json'))
+								return sendNodeResponse(
+									res,
+									new Response(
+										JSON.stringify(
+											{
+												status: 500,
+												error: 'Internal Server Error',
+												message: 'An unexpected error occurred. Please try again later.',
+												timestamp: /* @__PURE__ */ new Date().toISOString(),
+											},
+											null,
+											2,
+										),
+										{
+											status: 500,
+											headers: { 'Content-Type': 'application/json' },
+										},
+									),
+								);
+							return sendNodeResponse(
+								res,
+								new Response(
+									`
+              <!DOCTYPE html>
+              <html lang="en">
+                <head>
+                  <meta charset="UTF-8" />
+                  <title>Error</title>
+                  <script type="module">
+                    import { ErrorOverlay } from '/@vite/client'
+                    document.body.appendChild(new ErrorOverlay(${JSON.stringify(prepareError(req, e)).replace(/</g, '\\u003c')}))
+                  <\/script>
+                </head>
+                <body>
+                </body>
+              </html>
+            `,
+									{
+										status: 500,
+										headers: { 'Content-Type': 'text/html' },
+									},
+								),
+							);
+						}
+					});
+				};
+			},
+		},
+	];
+}
+/**
+ * Formats error for SSR message in error overlay
+ * @param req
+ * @param error
+ * @returns
+ */
+function prepareError(req, error) {
+	const e = error;
+	return {
+		message: `An error occurred while server rendering ${req.url}:\n\n\t${typeof e === 'string' ? e : e.message} `,
+		stack: typeof e === 'string' ? '' : e.stack,
+	};
+}
+//#endregion
+export { devServerPlugin };

package/src/internal/start-plugin-core/vite/import-protection-plugin/plugin.d.ts

@@ -0,0 +1,4 @@
+import { PluginOption } from 'vite';
+import { ImportProtectionPluginOptions } from './types.js';
+export type { ImportProtectionPluginOptions } from './types.js';
+export declare function importProtectionPlugin(opts: ImportProtectionPluginOptions): PluginOption;