@octanejs/tanstack-start 0.1.0

package/src/internal/start-plugin-core/start-compiler/host.js

@@ -0,0 +1,75 @@
+import { StartCompiler, getLookupKindsForEnv } from './compiler.js';
+import { getLookupConfigurationsForEnv } from './config.js';
+//#region src/start-compiler/host.ts
+function createStartCompiler(options) {
+	return new StartCompiler({
+		env: options.env,
+		envName: options.envName,
+		root: options.root,
+		lookupKinds: getLookupKindsForEnv(options.env, {
+			compilerTransforms: options.compilerTransforms,
+		}),
+		lookupConfigurations: getLookupConfigurationsForEnv(options.env, options.framework, {
+			compilerTransforms: options.compilerTransforms,
+		}),
+		mode: options.mode,
+		framework: options.framework,
+		providerEnvName: options.providerEnvName,
+		generateFunctionId: options.generateFunctionId,
+		onServerFnsById: options.onServerFnsById,
+		compilerTransforms: options.compilerTransforms,
+		compilerPlugins: options.compilerPlugins,
+		serverFnProviderModuleDirectives: options.serverFnProviderModuleDirectives,
+		warn: options.warn,
+		getKnownServerFns: options.getKnownServerFns,
+		devServerFnModuleSpecifierEncoder: options.encodeModuleSpecifierInDev,
+		loadModule: options.loadModule,
+		resolveId: options.resolveId,
+	});
+}
+function mergeServerFnsById(current, next) {
+	for (const [id, fn] of Object.entries(next)) {
+		const existing = current[id];
+		if (existing) {
+			current[id] = {
+				...fn,
+				isClientReferenced: existing.isClientReferenced || fn.isClientReferenced,
+			};
+			continue;
+		}
+		current[id] = fn;
+	}
+}
+function matchesCodeFilters(code, filters) {
+	for (const pattern of filters) {
+		pattern.lastIndex = 0;
+		if (pattern.test(code)) return true;
+	}
+	return false;
+}
+function createCompilerVirtualModuleIdPattern(compilerPlugins) {
+	const patterns = compilerPlugins
+		.map((plugin) => plugin.virtualModuleIdPattern)
+		.filter((pattern) => !!pattern);
+	if (patterns.length === 0) return;
+	return new RegExp(patterns.map((pattern) => `(?:${pattern.source})`).join('|'));
+}
+function loadCompilerVirtualModule(compilerPlugins, context) {
+	for (const compilerPlugin of compilerPlugins) {
+		const pattern = compilerPlugin.virtualModuleIdPattern;
+		if (!pattern) continue;
+		pattern.lastIndex = 0;
+		if (!pattern.test(context.id)) continue;
+		const result = compilerPlugin.loadVirtualModule?.(context);
+		if (result) return result;
+	}
+	return null;
+}
+//#endregion
+export {
+	createCompilerVirtualModuleIdPattern,
+	createStartCompiler,
+	loadCompilerVirtualModule,
+	matchesCodeFilters,
+	mergeServerFnsById,
+};

package/src/internal/start-plugin-core/start-compiler/server-fn-resolver-module.d.ts

@@ -0,0 +1,10 @@
+import { ServerFn } from './types.js';
+interface GenerateServerFnResolverModuleOptions {
+	serverFnsById: Record<string, ServerFn>;
+	includeClientReferencedCheck: boolean;
+	useStaticImports?: boolean;
+}
+export declare function generateServerFnResolverModule(
+	opts: GenerateServerFnResolverModuleOptions,
+): string;
+export {};

package/src/internal/start-plugin-core/start-compiler/server-fn-resolver-module.js

@@ -0,0 +1,87 @@
+//#region src/start-compiler/server-fn-resolver-module.ts
+function getResolverManifestEntries(serverFnsById) {
+	return Object.entries(serverFnsById)
+		.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+		.map(([id, fn]) => ({
+			id,
+			functionName: fn.functionName,
+			extractedFilename: fn.extractedFilename,
+			isClientReferenced: fn.isClientReferenced ?? true,
+		}));
+}
+function getClientReferencedCheck(includeClientReferencedCheck) {
+	if (!includeClientReferencedCheck) return '';
+	return `
+  if (access.origin === 'client' && !serverFnInfo.isClientReferenced) {
+    throw new Error('Server function not accessible from client: ' + id)
+  }
+`;
+}
+function getResolverBody() {
+	return `
+export async function getServerFnById(id, access) {
+  const serverFnInfo = manifest[id]
+  if (!serverFnInfo) {
+    throw new Error('Server function info not found for ' + id)
+  }
+__CLIENT_REFERENCED_CHECK__
+  const fnModule = serverFnInfo.module ?? (await serverFnInfo.importer())
+  if (!fnModule) {
+    throw new Error('Server function module not resolved for ' + id)
+  }
+  const action = fnModule[serverFnInfo.functionName]
+  if (!action) {
+    throw new Error('Server function module export not resolved for serverFn ID: ' + id)
+  }
+  return action
+}
+`;
+}
+function getResolverManifestModuleAccess(opts) {
+	if (opts.useStaticImports) return `module: ${opts.moduleRef}`;
+	return `importer: () => import(${JSON.stringify(opts.extractedFilename)})`;
+}
+function getResolverManifestEntry(opts) {
+	const clientReferenced = opts.includeClientReferencedCheck
+		? `,\n    isClientReferenced: ${opts.entry.isClientReferenced}`
+		: '';
+	return `'${opts.entry.id}': {
+    functionName: '${opts.entry.functionName}',
+    ${opts.moduleAccess}${clientReferenced}
+  }`;
+}
+function generateServerFnResolverModule(opts) {
+	const manifestEntries = getResolverManifestEntries(opts.serverFnsById);
+	const staticImports = [];
+	const manifest = manifestEntries
+		.map((entry, index) => {
+			const moduleRef = `serverFnModule${index}`;
+			if (opts.useStaticImports)
+				staticImports.push(
+					`import * as ${moduleRef} from ${JSON.stringify(entry.extractedFilename)}`,
+				);
+			return getResolverManifestEntry({
+				entry,
+				moduleAccess: getResolverManifestModuleAccess({
+					useStaticImports: opts.useStaticImports,
+					extractedFilename: entry.extractedFilename,
+					moduleRef,
+				}),
+				includeClientReferencedCheck: opts.includeClientReferencedCheck,
+			});
+		})
+		.join(',\n  ');
+	const body = getResolverBody().replace(
+		'__CLIENT_REFERENCED_CHECK__',
+		getClientReferencedCheck(opts.includeClientReferencedCheck),
+	);
+	return `
+${staticImports.join('\n')}
+const manifest = {
+  ${manifest}
+}
+${body}
+`;
+}
+//#endregion
+export { generateServerFnResolverModule };

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

@@ -0,0 +1,119 @@
+import { StartCompilerTransformContext } from '../types.js';
+import type * as babel from '@babel/core';
+import type * as t from '@babel/types';
+/**
+ * Context passed to all plugin handlers during compilation.
+ * Contains both read-only input data and mutable state that handlers update.
+ */
+export interface CompilationContext extends StartCompilerTransformContext {
+	/** Generate a unique function ID */
+	generateFunctionId: GenerateFunctionIdFn;
+	/** Get known server functions from previous builds (e.g., client build) */
+	getKnownServerFns: () => Record<string, ServerFn>;
+	/** Module-level directives to add to extracted server function provider files. */
+	serverFnProviderModuleDirectives: ReadonlyArray<string> | undefined;
+	/**
+	 * Callback when server functions are discovered.
+	 * Called after each file is compiled with its new functions.
+	 */
+	onServerFnsById: ((d: Record<string, ServerFn>) => void) | undefined;
+}
+/**
+ * Batched plugin handler signature.
+ * Receives ALL candidates of a specific kind in one call.
+ * Mutates the CompilationContext directly.
+ */
+export type BatchedPluginHandler<TOpts = unknown> = (
+	candidates: Array<RewriteCandidate>,
+	context: CompilationContext,
+	opts: TOpts,
+) => void;
+/**
+ * Info about a method call in the chain, including the call expression path
+ * and the path to its first argument (if any).
+ */
+export interface MethodCallInfo {
+	callPath: babel.NodePath<t.CallExpression>;
+	/** Path to the first argument, or null if no arguments */
+	firstArgPath: babel.NodePath | null;
+}
+/**
+ * Pre-collected method chain paths for a root call expression.
+ * This avoids needing to traverse the AST again in handlers.
+ */
+export interface MethodChainPaths {
+	middleware: MethodCallInfo | null;
+	validator: MethodCallInfo | null;
+	inputValidator: MethodCallInfo | null;
+	handler: MethodCallInfo | null;
+	server: MethodCallInfo | null;
+	client: MethodCallInfo | null;
+}
+export type MethodChainKey = keyof MethodChainPaths;
+/**
+ * Information about a candidate that needs to be rewritten.
+ */
+export interface RewriteCandidate {
+	path: babel.NodePath<t.CallExpression>;
+	methodChain: MethodChainPaths;
+}
+/**
+ * Represents an extracted server function that has been registered.
+ * Used for manifest generation and tracking function metadata.
+ */
+export interface ServerFn {
+	/** The unique name used to export this function */
+	functionName: string;
+	/** The unique ID for this function (used in RPC calls) */
+	functionId: string;
+	/** The filename with query param where the extracted implementation lives */
+	extractedFilename: string;
+	/** The original source filename */
+	filename: string;
+	/**
+	 * True when this function was discovered by the client build.
+	 * Used to restrict HTTP access to only client-referenced functions.
+	 */
+	isClientReferenced?: boolean;
+}
+/**
+ * Function type for generating unique function IDs.
+ */
+export type GenerateFunctionIdFn = (opts: {
+	filename: string;
+	functionName: string;
+	extractedFilename: string;
+}) => string;
+/**
+ * Optional version that allows returning undefined to use default ID generation.
+ */
+export type GenerateFunctionIdFnOptional = (
+	opts: Omit<Parameters<GenerateFunctionIdFn>[0], 'extractedFilename'>,
+) => string | undefined;
+/**
+ * Function type for generating replacement code for server functions.
+ * Used internally by handleCreateServerFn.
+ */
+export type DevServerFnModuleSpecifierEncoder = (opts: {
+	extractedFilename: string;
+	root: string;
+}) => string;
+export type ReplacerFn = (opts: {
+	/** Placeholder for the original function expression */
+	fn: string;
+	/** The filename where the extracted implementation lives */
+	extractedFilename: string;
+	/** The original source filename */
+	filename: string;
+	/** The unique function ID */
+	functionId: string;
+	/** The export name for this function */
+	functionName: string;
+	/** True if this is the source/provider file (has the implementation) */
+	isSourceFn: boolean;
+	/**
+	 * True when this function was already discovered by a previous build (e.g., client).
+	 * For SSR callers, this means the function is in the manifest.
+	 */
+	isClientReferenced: boolean;
+}) => string;

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

@@ -0,0 +1,27 @@
+import { default as babel } from '@babel/core';
+import * as t from '@babel/types';
+export declare function codeFrameError(
+	code: string,
+	loc: {
+		start: {
+			line: number;
+			column: number;
+		};
+		end: {
+			line: number;
+			column: number;
+		};
+	},
+	message: string,
+): Error;
+export declare function cleanId(id: string): string;
+/**
+ * Strips a method call by replacing it with its callee object.
+ * E.g., `foo().bar()` -> `foo()`
+ *
+ * This is a common pattern used when removing method calls from chains
+ * (e.g., removing .server() from middleware on client, or .validator() on client).
+ *
+ * @param callPath - The path to the CallExpression to strip
+ */
+export declare function stripMethodCall(callPath: babel.NodePath<t.CallExpression>): void;

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

@@ -0,0 +1,36 @@
+import * as t from '@babel/types';
+import { codeFrameColumns } from '@babel/code-frame';
+//#region src/start-compiler/utils.ts
+function codeFrameError(code, loc, message) {
+	const frame = codeFrameColumns(
+		code,
+		{
+			start: loc.start,
+			end: loc.end,
+		},
+		{
+			highlightCode: true,
+			message,
+		},
+	);
+	return new Error(frame);
+}
+function cleanId(id) {
+	if (id.startsWith('\0')) id = id.slice(1);
+	const queryIndex = id.indexOf('?');
+	return queryIndex === -1 ? id : id.substring(0, queryIndex);
+}
+/**
+ * Strips a method call by replacing it with its callee object.
+ * E.g., `foo().bar()` -> `foo()`
+ *
+ * This is a common pattern used when removing method calls from chains
+ * (e.g., removing .server() from middleware on client, or .validator() on client).
+ *
+ * @param callPath - The path to the CallExpression to strip
+ */
+function stripMethodCall(callPath) {
+	if (t.isMemberExpression(callPath.node.callee)) callPath.replaceWith(callPath.node.callee.object);
+}
+//#endregion
+export { cleanId, codeFrameError, stripMethodCall };

package/src/internal/start-plugin-core/start-manifest-plugin/inlineCss.d.ts

@@ -0,0 +1,16 @@
+export interface InlineCssTemplate {
+	strings: Array<string>;
+	urls: Array<string>;
+}
+export interface InlineCssResult {
+	css: string;
+	template?: InlineCssTemplate;
+}
+export declare function shouldRebaseInlineCssUrls(css: string): boolean;
+export declare function rebaseInlineCssUrls(options: { css: string; cssHref: string }): string;
+export declare function processInlineCssUrls(options: {
+	css: string;
+	cssHref: string;
+	templates?: boolean;
+}): InlineCssResult;
+export declare function getCssAssetSource(source: unknown): string | undefined;

package/src/internal/start-plugin-core/start-manifest-plugin/inlineCss.js

@@ -0,0 +1,131 @@
+import { transform } from 'lightningcss';
+//#region src/start-manifest-plugin/inlineCss.ts
+var cssUrlPattern =
+	/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)"']*?))\s*\)|@import\s+(?:url\(\s*(?:"([^"]*)"|'([^']*)'|([^)"']*?))\s*\)|"([^"]*)"|'([^']*)')/gi;
+function createInlineCssUrlPlaceholder(index) {
+	return `__TSS INLINE CSS URL ${index}__`;
+}
+function isRelativeCssUrl(url) {
+	if (!url) return false;
+	if (url.startsWith('#')) return false;
+	if (url.startsWith('/')) return false;
+	if (/^[a-z][a-z\d+.-]*:/i.test(url)) return false;
+	return true;
+}
+function shouldTransformInlineCssUrl(url) {
+	if (!url) return false;
+	if (url.startsWith('#')) return false;
+	if (url.startsWith('//')) return false;
+	if (/^[a-z][a-z\d+.-]*:/i.test(url)) return false;
+	return true;
+}
+function shouldProcessInlineCssUrls(css, templates) {
+	cssUrlPattern.lastIndex = 0;
+	for (const match of css.matchAll(cssUrlPattern)) {
+		const url = (
+			match[1] ??
+			match[2] ??
+			match[3] ??
+			match[4] ??
+			match[5] ??
+			match[6] ??
+			match[7] ??
+			match[8] ??
+			''
+		).trim();
+		if (templates ? shouldTransformInlineCssUrl(url) : isRelativeCssUrl(url)) return true;
+	}
+	return false;
+}
+function rebaseCssUrl(url, cssHref) {
+	if (!isRelativeCssUrl(url)) return url;
+	const fakeOrigin = 'http://tanstack.local';
+	const resolved = new URL(url, new URL(cssHref, fakeOrigin));
+	if (resolved.origin === fakeOrigin)
+		return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+	return resolved.href;
+}
+function processInlineCssUrls(options) {
+	const css = options.css.trim();
+	const templates = options.templates === true;
+	if (!shouldProcessInlineCssUrls(css, templates)) return { css };
+	const urls = [];
+	const result = transform({
+		filename: options.cssHref,
+		code: Buffer.from(css),
+		minify: true,
+		visitor: {
+			Url(url) {
+				if (!shouldTransformInlineCssUrl(url.url)) return url;
+				const rebasedUrl = rebaseCssUrl(url.url, options.cssHref);
+				if (templates) {
+					urls.push(rebasedUrl);
+					return {
+						...url,
+						url: createInlineCssUrlPlaceholder(urls.length - 1),
+					};
+				}
+				return {
+					...url,
+					url: rebasedUrl,
+				};
+			},
+			Rule: {
+				import(rule) {
+					if (!shouldTransformInlineCssUrl(rule.value.url)) return rule;
+					const rebasedUrl = rebaseCssUrl(rule.value.url, options.cssHref);
+					if (templates) urls.push(rebasedUrl);
+					const value = {
+						url: templates ? createInlineCssUrlPlaceholder(urls.length - 1) : rebasedUrl,
+						loc: rule.value.loc,
+						...(rule.value.media ? { media: rule.value.media } : {}),
+						...(rule.value.layer ? { layer: rule.value.layer } : {}),
+						...(rule.value.supports ? { supports: rule.value.supports } : {}),
+					};
+					return {
+						...rule,
+						value,
+					};
+				},
+			},
+		},
+	});
+	const transformedCss = Buffer.from(result.code).toString('utf8');
+	if (!templates || urls.length === 0) return { css: transformedCss };
+	return createInlineCssTemplate(transformedCss, urls);
+}
+function createInlineCssTemplate(cssWithPlaceholders, urls) {
+	const strings = [];
+	let css = '';
+	let cursor = 0;
+	for (let index = 0; index < urls.length; index++) {
+		const placeholder = createInlineCssUrlPlaceholder(index);
+		const placeholderIndex = cssWithPlaceholders.indexOf(placeholder, cursor);
+		if (placeholderIndex === -1)
+			throw new Error(
+				`TanStack Start inlineCss could not find CSS URL placeholder: ${placeholder}`,
+			);
+		const staticPart = cssWithPlaceholders.slice(cursor, placeholderIndex);
+		strings.push(staticPart);
+		css += staticPart + urls[index];
+		cursor = placeholderIndex + placeholder.length;
+	}
+	const finalStaticPart = cssWithPlaceholders.slice(cursor);
+	strings.push(finalStaticPart);
+	css += finalStaticPart;
+	return {
+		css,
+		template: {
+			strings,
+			urls,
+		},
+	};
+}
+function getCssAssetSource(source) {
+	if (typeof source === 'string') return source;
+	if (source instanceof Uint8Array) return Buffer.from(source).toString('utf8');
+	if (source == null) return void 0;
+	return String(source);
+}
+//#endregion
+export { getCssAssetSource, processInlineCssUrls };

package/src/internal/start-plugin-core/start-manifest-plugin/manifestBuilder.d.ts

@@ -0,0 +1,64 @@
+import { ManifestCssLink, ManifestScript, ScriptFormat } from '@tanstack/router-core';
+import { InlineCssTemplate } from './inlineCss.js';
+import { NormalizedClientBuild, NormalizedClientChunk } from '../types.js';
+type RouteTreeRoute = {
+	filePath?: string;
+	preloads?: Array<string>;
+	scripts?: Array<ManifestScript>;
+	css?: Array<ManifestCssLink>;
+	children?: Array<string>;
+};
+type RouteTreeRoutes = Record<string, RouteTreeRoute>;
+type AdditionalRouteManifestEntry = ManifestCssLink | ManifestScript;
+interface ScannedClientChunks {
+	entryChunk: NormalizedClientChunk;
+	chunksByFileName: ReadonlyMap<string, NormalizedClientChunk>;
+	routeChunksByFilePath: ReadonlyMap<string, Array<NormalizedClientChunk>>;
+}
+interface ManifestAssetResolvers {
+	getAssetPath: (fileName: string) => string;
+	getChunkPreloads: (chunk: NormalizedClientChunk) => Array<string>;
+	getStylesheetLink: (cssFile: string) => ManifestCssLink;
+}
+export interface StartManifest {
+	scriptFormat?: ScriptFormat;
+	routes: Record<string, RouteTreeRoute>;
+	inlineCss?: {
+		styles: Record<string, string>;
+		templates?: Record<string, InlineCssTemplate>;
+	};
+}
+export interface InlineCssOptions {
+	enabled: boolean;
+	transformAssets: boolean;
+}
+export declare function appendUniqueStrings(
+	target: Array<string> | undefined,
+	source: Array<string>,
+): string[] | undefined;
+export declare function buildStartManifest(options: {
+	clientBuild: NormalizedClientBuild;
+	routeTreeRoutes: RouteTreeRoutes;
+	basePath: string;
+	inlineCss?: InlineCssOptions;
+	scriptFormat?: ScriptFormat;
+	additionalRouteAssets?: Partial<Record<string, ReadonlyArray<AdditionalRouteManifestEntry>>>;
+}): StartManifest;
+export declare function serializeStartManifest(startManifest: StartManifest): string;
+export declare function scanClientChunks(clientBuild: NormalizedClientBuild): ScannedClientChunks;
+export declare function createManifestAssetResolvers(basePath: string): ManifestAssetResolvers;
+export declare function createChunkCssAssetCollector(options: {
+	chunksByFileName: ReadonlyMap<string, NormalizedClientChunk>;
+	getStylesheetLink: (cssFile: string) => ManifestCssLink;
+}): {
+	getChunkCssAssets: (chunk: NormalizedClientChunk) => Array<ManifestCssLink>;
+};
+export declare function buildRouteManifestRoutes(options: {
+	routeTreeRoutes: RouteTreeRoutes;
+	routeChunksByFilePath: ReadonlyMap<string, ReadonlyArray<NormalizedClientChunk>>;
+	chunksByFileName: ReadonlyMap<string, NormalizedClientChunk>;
+	entryChunk: NormalizedClientChunk;
+	assetResolvers: ManifestAssetResolvers;
+	additionalRouteAssets?: Partial<Record<string, ReadonlyArray<AdditionalRouteManifestEntry>>>;
+}): Record<string, RouteTreeRoute>;
+export {};