@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

package/src/services/module-loading/app-server-module-transpiler.service.test.ts

@@ -0,0 +1,130 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+import {
+	createAppServerModuleTranspiler,
+	getAppHostModuleLoader,
+	getAppModuleLoader,
+	setAppHostModuleLoader,
+	shouldAppUseHostModuleLoader,
+} from './app-server-module-transpiler.service.ts';
+
+describe('app server module transpiler runtime state', () => {
+	it('stores and exposes an abstract host module loader on app runtime state', () => {
+		const appConfig = {
+			runtime: {},
+		} as any;
+		const hostModuleLoader = async (id: string) => ({ id });
+
+		setAppHostModuleLoader(appConfig, hostModuleLoader);
+
+		assert.equal(getAppHostModuleLoader(appConfig), hostModuleLoader);
+	});
+
+	it('exposes host ownership when a host module loader is configured', () => {
+		const hostModuleLoader = async (id: string) => ({ id });
+		const appConfig = {
+			rootDir: '/app',
+			runtime: {
+				hostModuleLoader,
+			},
+		} as any;
+
+		const moduleLoader = getAppModuleLoader(appConfig);
+
+		assert.equal(moduleLoader.owner, 'host');
+	});
+
+	it('creates a server transpiler that uses the app module loader', () => {
+		const hostModuleLoader = async (id: string) => ({ id });
+		const appConfig = {
+			rootDir: '/app',
+			runtime: {
+				hostModuleLoader,
+			},
+		} as any;
+
+		const transpiler = createAppServerModuleTranspiler(appConfig);
+
+		assert.ok(transpiler);
+		assert.equal(getAppHostModuleLoader(appConfig), hostModuleLoader);
+	});
+
+	it('keeps Ecopages integration modules on the framework transpiler path', () => {
+		const appConfig = {
+			absolutePaths: {
+				componentsDir: '/app/src/components',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				pagesDir: '/app/src/pages',
+			},
+			templatesExt: ['.kita.tsx', '.lit.tsx'],
+		} as any;
+
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/runtime/helpers.ts'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/index.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/includes/html.kita.tsx'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/layouts/base-layout.kita.tsx'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/counter.lit.tsx'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/components/counter.lit.tsx'), false);
+	});
+
+	it('prefers the host module loader for framework-owned modules when a host runtime provides one', () => {
+		const appConfig = {
+			absolutePaths: {
+				componentsDir: '/app/src/components',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				pagesDir: '/app/src/pages',
+			},
+			runtime: {
+				hostModuleLoader: async (id: string) => ({ id }),
+			},
+			templatesExt: ['.kita.tsx', '.lit.tsx'],
+		} as any;
+
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/runtime/helpers.ts'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/index.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/includes/html.kita.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/layouts/base-layout.kita.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/counter.lit.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/components/counter.lit.tsx'), true);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/docs.md'), false);
+		assert.equal(shouldAppUseHostModuleLoader(appConfig, '/app/src/pages/react-content.mdx'), false);
+	});
+
+	it('adds the Node bootstrap plugin to app-owned module imports in node runtimes', async () => {
+		const calls: Array<unknown> = [];
+		const appConfig = {
+			rootDir: '/app',
+			absolutePaths: {
+				componentsDir: '/app/src/components',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				pagesDir: '/app/src/pages',
+			},
+			templatesExt: ['.tsx'],
+			runtime: {},
+		} as any;
+
+		const moduleLoader = getAppModuleLoader(appConfig) as any;
+		const originalImportModule = moduleLoader.pageModuleImportService.importModule.bind(
+			moduleLoader.pageModuleImportService,
+		);
+		moduleLoader.pageModuleImportService.importModule = async (options: unknown) => {
+			calls.push(options);
+			return { default: { ok: true } };
+		};
+
+		await moduleLoader.importModule({
+			filePath: '/app/src/pages/index.tsx',
+			rootDir: '/app',
+			outdir: '/app/.eco/.server-modules',
+		});
+
+		moduleLoader.pageModuleImportService.importModule = originalImportModule;
+
+		const plugins = (calls[0] as { plugins?: Array<{ name: string }> }).plugins;
+		assert.equal(Array.isArray(plugins), true);
+		assert.equal(plugins?.[0]?.name, 'node-bootstrap-plugin');
+	});
+});

package/src/services/module-loading/app-server-module-transpiler.service.ts

@@ -0,0 +1,143 @@
+import { getAppBuildExecutor } from '../../build/build-adapter.ts';
+import path from 'node:path';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { DevelopmentInvalidationService } from '../invalidation/development-invalidation.service.ts';
+import { type AppModuleLoader, type AppModuleLoaderOwner } from './app-module-loader.service.ts';
+import { createAppNodeBootstrapPlugin } from './node-bootstrap-plugin.ts';
+import { PageModuleImportService, type PageModuleImportOptions } from './page-module-import.service.ts';
+import type { SourceModuleLoader } from './module-loading-types.ts';
+import { supportsSourceModuleLoading } from './source-module-support.ts';
+import { ServerModuleTranspiler } from './server-module-transpiler.service.ts';
+
+export function shouldAppUseHostModuleLoader(appConfig: EcoPagesAppConfig, filePath: string): boolean {
+	if (appConfig.runtime?.hostModuleLoader) {
+		return supportsSourceModuleLoading(filePath);
+	}
+
+	const normalizedFilePath = path.normalize(filePath);
+	const frameworkOwnedDirectories = [
+		appConfig.absolutePaths.pagesDir,
+		appConfig.absolutePaths.includesDir,
+		appConfig.absolutePaths.layoutsDir,
+		appConfig.absolutePaths.componentsDir,
+	].map((directoryPath) => path.normalize(directoryPath));
+	const isFrameworkOwnedModule = frameworkOwnedDirectories.some((directoryPath) => {
+		return normalizedFilePath === directoryPath || normalizedFilePath.startsWith(`${directoryPath}${path.sep}`);
+	});
+	const isConfiguredTemplateModule = appConfig.templatesExt.some((extension) =>
+		normalizedFilePath.endsWith(extension),
+	);
+
+	return !(isFrameworkOwnedModule && isConfiguredTemplateModule);
+}
+
+export function getAppHostModuleLoader(appConfig: EcoPagesAppConfig): SourceModuleLoader | undefined {
+	return appConfig.runtime?.hostModuleLoader;
+}
+
+function getAppModuleLoaderOwner(appConfig: EcoPagesAppConfig): AppModuleLoaderOwner {
+	return getAppHostModuleLoader(appConfig) ? 'host' : 'bun';
+}
+
+export function setAppHostModuleLoader(appConfig: EcoPagesAppConfig, hostModuleLoader?: SourceModuleLoader): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		hostModuleLoader,
+	};
+}
+
+export function createAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader {
+	const invalidationService = new DevelopmentInvalidationService(appConfig);
+	const pageModuleImportService = new PageModuleImportService({
+		canLoadSourceModuleFromHost: (filePath) => shouldAppUseHostModuleLoader(appConfig, filePath),
+		getHostModuleLoader: () => getAppHostModuleLoader(appConfig),
+	});
+	const getDefaultPlugins =
+		typeof Bun === 'undefined' && appConfig.rootDir
+			? () => [createAppNodeBootstrapPlugin(appConfig)]
+			: () => [];
+	const appModuleLoader: AppModuleLoader & {
+		pageModuleImportService: PageModuleImportService;
+	} = {
+		get owner(): AppModuleLoaderOwner {
+			return getAppModuleLoaderOwner(appConfig);
+		},
+		pageModuleImportService,
+		async importModule<T = unknown>(options: PageModuleImportOptions) {
+			const mergedPlugins = [...getDefaultPlugins(), ...(options.plugins ?? [])];
+
+			return await pageModuleImportService.importModule<T>({
+				...options,
+				...(mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {}),
+				buildExecutor: options.buildExecutor ?? getAppBuildExecutor(appConfig),
+				invalidationVersion:
+					options.invalidationVersion ?? invalidationService.getServerModuleInvalidationVersion(),
+			});
+		},
+		invalidateDevelopmentGraph() {
+			pageModuleImportService.invalidateDevelopmentGraph();
+		},
+	};
+
+	return appModuleLoader;
+}
+
+export function getAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader {
+	const existingModuleLoader = appConfig.runtime?.appModuleLoader;
+	if (existingModuleLoader) {
+		return existingModuleLoader;
+	}
+
+	const appModuleLoader = createAppModuleLoader(appConfig);
+	setAppModuleLoader(appConfig, appModuleLoader);
+	return appModuleLoader;
+}
+
+export function setAppModuleLoader(appConfig: EcoPagesAppConfig, appModuleLoader: AppModuleLoader): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		appModuleLoader,
+	};
+}
+
+/**
+ * Creates the shared app-scoped server-module transpiler for one runtime
+ * instance.
+ */
+export function createAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler {
+	const invalidationService = new DevelopmentInvalidationService(appConfig);
+
+	return new ServerModuleTranspiler({
+		rootDir: appConfig.rootDir,
+		invalidateModules: (changedFiles) => invalidationService.invalidateServerModules(changedFiles),
+		pageModuleImportService: getAppModuleLoader(appConfig),
+	});
+}
+
+/**
+ * Returns the app-owned server-module transpiler, creating it lazily when the
+ * runtime first needs one.
+ */
+export function getAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler {
+	const existingTranspiler = appConfig.runtime?.serverModuleTranspiler;
+	if (existingTranspiler) {
+		return existingTranspiler;
+	}
+
+	const serverModuleTranspiler = createAppServerModuleTranspiler(appConfig);
+	setAppServerModuleTranspiler(appConfig, serverModuleTranspiler);
+	return serverModuleTranspiler;
+}
+
+/**
+ * Installs the server-module transpiler that should serve one app instance.
+ */
+export function setAppServerModuleTranspiler(
+	appConfig: EcoPagesAppConfig,
+	serverModuleTranspiler: ServerModuleTranspiler,
+): void {
+	appConfig.runtime = {
+		...(appConfig.runtime ?? {}),
+		serverModuleTranspiler,
+	};
+}

package/src/services/module-loading/host-module-loader-registry.ts

@@ -0,0 +1,15 @@
+import type { SourceModuleLoader } from './module-loading-types.ts';
+
+let hostModuleLoader: SourceModuleLoader | undefined;
+
+export function setHostModuleLoader(loader: SourceModuleLoader): void {
+	hostModuleLoader = loader;
+}
+
+export function getHostModuleLoader(): SourceModuleLoader | undefined {
+	return hostModuleLoader;
+}
+
+export function clearHostModuleLoader(): void {
+	hostModuleLoader = undefined;
+}

package/src/services/module-loading/{module-loading-types.d.ts → module-loading-types.ts}

@@ -1,2 +1,3 @@
 export type SourceModuleLoader = (id: string) => Promise<unknown>;
+
 export type SourceModuleLoaderFactory = () => SourceModuleLoader | undefined;

package/src/services/module-loading/node-bootstrap-plugin.test.ts

@@ -0,0 +1,335 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { test } from 'vitest';
+import {
+	createNodeBootstrapPlugin,
+	getNodeUnsupportedBuiltinError,
+	resolveNodeBootstrapDependency,
+} from './node-bootstrap-plugin.ts';
+
+function writePackage(packageDir: string, options: { name: string; main?: string }) {
+	fs.mkdirSync(packageDir, { recursive: true });
+	fs.writeFileSync(
+		path.join(packageDir, 'package.json'),
+		JSON.stringify({
+			name: options.name,
+			main: options.main ?? 'index.js',
+		}),
+		'utf8',
+	);
+	const entryFilePath = path.join(packageDir, options.main ?? 'index.js');
+	fs.mkdirSync(path.dirname(entryFilePath), { recursive: true });
+	fs.writeFileSync(entryFilePath, 'export default null;\n', 'utf8');
+}
+
+test('resolveNodeBootstrapDependency keeps relative, node, and workspace specifiers in the bundle graph', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+
+	try {
+		const options = {
+			projectDir: rootDir,
+			runtimeNodeModulesDir: path.join(rootDir, '.eco', 'node_modules'),
+		};
+
+		assert.equal(resolveNodeBootstrapDependency({ path: './local.ts' }, options), undefined);
+		assert.equal(resolveNodeBootstrapDependency({ path: 'node:path' }, options), undefined);
+		assert.equal(resolveNodeBootstrapDependency({ path: '@/data/demo-data' }, options), undefined);
+		assert.deepEqual(resolveNodeBootstrapDependency({ path: '@ecopages/core' }, options), {
+			path: fileURLToPath(import.meta.resolve('@ecopages/core')),
+		});
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('resolveNodeBootstrapDependency externalizes third-party packages and links them into runtime node_modules', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	const importerPath = path.join(rootDir, 'packages', 'example', 'src', 'index.ts');
+	fs.mkdirSync(path.dirname(importerPath), { recursive: true });
+	fs.writeFileSync(importerPath, 'export default null;\n', 'utf8');
+	writePackage(path.join(rootDir, 'node_modules', 'fast-glob'), { name: 'fast-glob', main: 'out/index.js' });
+
+	try {
+		const runtimeNodeModulesDir = path.join(rootDir, '.eco', 'node_modules');
+		const result = resolveNodeBootstrapDependency(
+			{ path: 'fast-glob', importer: importerPath },
+			{ projectDir: rootDir, runtimeNodeModulesDir },
+		);
+
+		assert.deepEqual(result, { path: 'fast-glob', external: true });
+		assert.equal(
+			fs.realpathSync(path.join(runtimeNodeModulesDir, 'fast-glob')),
+			fs.realpathSync(path.join(rootDir, 'node_modules', 'fast-glob')),
+		);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('resolveNodeBootstrapDependency resolves workspace-source third-party imports from the app project boundary', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	const importerPath = path.join(rootDir, 'packages', 'react-plugin', 'src', 'plugin.ts');
+	fs.mkdirSync(path.dirname(importerPath), { recursive: true });
+	fs.writeFileSync(importerPath, 'export default null;\n', 'utf8');
+	writePackage(path.join(rootDir, 'node_modules', 'react'), { name: 'react', main: 'index.js' });
+
+	try {
+		const runtimeNodeModulesDir = path.join(rootDir, '.eco', 'node_modules');
+		const result = resolveNodeBootstrapDependency(
+			{ path: 'react', importer: importerPath },
+			{ projectDir: rootDir, runtimeNodeModulesDir },
+		);
+
+		assert.deepEqual(result, { path: 'react', external: true });
+		assert.equal(
+			fs.realpathSync(path.join(runtimeNodeModulesDir, 'react')),
+			fs.realpathSync(path.join(rootDir, 'node_modules', 'react')),
+		);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('resolveNodeBootstrapDependency resolves workspace package dependencies from the importer package boundary', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	const appProjectDir = path.join(rootDir, 'playground', 'kitchen-sink');
+	fs.mkdirSync(appProjectDir, { recursive: true });
+	fs.writeFileSync(path.join(appProjectDir, 'package.json'), '{}', 'utf8');
+	const frameworkPackageDir = path.join(rootDir, 'packages', 'core');
+	const importerPath = path.join(frameworkPackageDir, 'src', 'plugin.ts');
+	fs.mkdirSync(path.dirname(importerPath), { recursive: true });
+	fs.writeFileSync(importerPath, 'export default null;\n', 'utf8');
+	fs.writeFileSync(
+		path.join(frameworkPackageDir, 'package.json'),
+		JSON.stringify({ name: '@ecopages/core' }),
+		'utf8',
+	);
+	writePackage(path.join(frameworkPackageDir, 'node_modules', 'oxc-parser'), {
+		name: 'oxc-parser',
+		main: 'index.js',
+	});
+
+	try {
+		const runtimeNodeModulesDir = path.join(rootDir, '.eco', 'node_modules');
+		const result = resolveNodeBootstrapDependency(
+			{ path: 'oxc-parser', importer: importerPath },
+			{ projectDir: appProjectDir, runtimeNodeModulesDir },
+		);
+
+		assert.deepEqual(result, { path: 'oxc-parser', external: true });
+		assert.equal(
+			fs.realpathSync(path.join(runtimeNodeModulesDir, 'oxc-parser')),
+			fs.realpathSync(path.join(frameworkPackageDir, 'node_modules', 'oxc-parser')),
+		);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('resolveNodeBootstrapDependency resolves nested third-party dependencies from the importer package context', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	const importerPackageDir = path.join(rootDir, 'node_modules', 'dep-a');
+	writePackage(importerPackageDir, { name: 'dep-a' });
+	const nestedDependencyDir = path.join(importerPackageDir, 'node_modules', 'dep-b');
+	writePackage(nestedDependencyDir, { name: 'dep-b' });
+	const importerPath = path.join(importerPackageDir, 'index.js');
+
+	try {
+		const runtimeNodeModulesDir = path.join(rootDir, '.eco', 'node_modules');
+		const result = resolveNodeBootstrapDependency(
+			{ path: 'dep-b', importer: importerPath },
+			{ projectDir: rootDir, runtimeNodeModulesDir },
+		);
+
+		assert.deepEqual(result, { path: 'dep-b', external: true });
+		assert.equal(fs.realpathSync(path.join(runtimeNodeModulesDir, 'dep-b')), fs.realpathSync(nestedDependencyDir));
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('resolveNodeBootstrapDependency refreshes runtime links when the resolved package target changes', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	const importerPath = path.join(rootDir, 'src', 'page.tsx');
+	fs.mkdirSync(path.dirname(importerPath), { recursive: true });
+	fs.writeFileSync(importerPath, 'export default null;\n', 'utf8');
+	const firstPackageDir = path.join(rootDir, 'store', 'react-v1');
+	const secondPackageDir = path.join(rootDir, 'store', 'react-v2');
+	writePackage(firstPackageDir, { name: 'react' });
+	writePackage(secondPackageDir, { name: 'react' });
+	const nodeModulesDir = path.join(rootDir, 'node_modules');
+	const appReactLinkPath = path.join(nodeModulesDir, 'react');
+	const runtimeNodeModulesDir = path.join(rootDir, '.eco', 'node_modules');
+	const runtimeReactLinkPath = path.join(runtimeNodeModulesDir, 'react');
+	fs.mkdirSync(nodeModulesDir, { recursive: true });
+	fs.mkdirSync(runtimeNodeModulesDir, { recursive: true });
+	fs.symlinkSync(secondPackageDir, appReactLinkPath, 'dir');
+	fs.symlinkSync(firstPackageDir, runtimeReactLinkPath, 'dir');
+
+	try {
+		assert.deepEqual(
+			resolveNodeBootstrapDependency(
+				{ path: 'react', importer: importerPath },
+				{ projectDir: rootDir, runtimeNodeModulesDir },
+			),
+			{ path: 'react', external: true },
+		);
+		assert.equal(fs.realpathSync(path.join(runtimeNodeModulesDir, 'react')), fs.realpathSync(secondPackageDir));
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('resolveNodeBootstrapDependency replaces dangling runtime symlinks before linking the resolved package', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	const importerPath = path.join(rootDir, 'src', 'page.tsx');
+	fs.mkdirSync(path.dirname(importerPath), { recursive: true });
+	fs.writeFileSync(importerPath, 'export default null;\n', 'utf8');
+	const packageDir = path.join(rootDir, 'node_modules', 'react');
+	const staleTargetDir = path.join(rootDir, 'store', 'react-stale');
+	const runtimeNodeModulesDir = path.join(rootDir, '.eco', 'node_modules');
+	const runtimeReactLinkPath = path.join(runtimeNodeModulesDir, 'react');
+	writePackage(packageDir, { name: 'react' });
+	fs.mkdirSync(path.dirname(runtimeReactLinkPath), { recursive: true });
+	fs.symlinkSync(staleTargetDir, runtimeReactLinkPath, 'dir');
+
+	try {
+		assert.deepEqual(
+			resolveNodeBootstrapDependency(
+				{ path: 'react', importer: importerPath },
+				{ projectDir: rootDir, runtimeNodeModulesDir },
+			),
+			{ path: 'react', external: true },
+		);
+		assert.equal(fs.realpathSync(runtimeReactLinkPath), fs.realpathSync(packageDir));
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('createNodeBootstrapPlugin wires the shared resolution policy into an Eco build plugin', async () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	writePackage(path.join(rootDir, 'node_modules', 'fast-glob'), { name: 'fast-glob', main: 'out/index.js' });
+
+	try {
+		const plugin = createNodeBootstrapPlugin({
+			projectDir: rootDir,
+			runtimeNodeModulesDir: path.join(rootDir, '.eco', 'node_modules'),
+		});
+
+		let onResolveCallback: ((args: { path: string; importer?: string; namespace?: string }) => unknown) | undefined;
+
+		await plugin.setup({
+			onResolve(_options, callback) {
+				onResolveCallback = callback;
+			},
+			onLoad() {},
+			module() {},
+		});
+
+		assert.ok(onResolveCallback);
+		assert.deepEqual(onResolveCallback?.({ path: 'fast-glob' }), {
+			path: 'fast-glob',
+			external: true,
+		});
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('createNodeBootstrapPlugin rewrites import.meta for all project source files', async () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	const bootstrapFile = path.join(rootDir, 'eco.config.ts');
+	const regularFile = path.join(rootDir, 'src', 'page.kita.tsx');
+	fs.mkdirSync(path.dirname(regularFile), { recursive: true });
+	fs.writeFileSync(bootstrapFile, 'export default import.meta.dirname;\n', 'utf8');
+	fs.writeFileSync(regularFile, 'export default import.meta.dirname;\n', 'utf8');
+
+	try {
+		const plugin = createNodeBootstrapPlugin({
+			projectDir: rootDir,
+			runtimeNodeModulesDir: path.join(rootDir, '.eco', 'node_modules'),
+		});
+
+		let onLoadCallback: ((args: { path: string; namespace?: string }) => Promise<unknown> | unknown) | undefined;
+
+		await plugin.setup({
+			onResolve() {},
+			onLoad(_options, callback) {
+				onLoadCallback = callback;
+			},
+			module() {},
+		});
+
+		assert.ok(onLoadCallback);
+		const bootstrapResult = await onLoadCallback?.({ path: bootstrapFile });
+		const regularResult = await onLoadCallback?.({ path: regularFile });
+
+		assert.equal(typeof (bootstrapResult as { contents?: string } | undefined)?.contents, 'string');
+		assert.equal(
+			bootstrapResult && typeof bootstrapResult === 'object' && 'contents' in bootstrapResult
+				? String((bootstrapResult as { contents: string }).contents).includes(
+						JSON.stringify(path.dirname(bootstrapFile)),
+					)
+				: false,
+			true,
+		);
+		assert.equal(typeof (regularResult as { contents?: string } | undefined)?.contents, 'string');
+		assert.equal(
+			regularResult && typeof regularResult === 'object' && 'contents' in regularResult
+				? String((regularResult as { contents: string }).contents).includes(
+						JSON.stringify(path.dirname(regularFile)),
+					)
+				: false,
+			true,
+		);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('createNodeBootstrapPlugin fails fast on Bun-only builtins', async () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-node-bootstrap-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	const importerPath = path.join(rootDir, 'src', 'db.server.ts');
+
+	try {
+		const plugin = createNodeBootstrapPlugin({
+			projectDir: rootDir,
+			runtimeNodeModulesDir: path.join(rootDir, '.eco', 'node_modules'),
+		});
+
+		let onResolveCallback: ((args: { path: string; importer?: string; namespace?: string }) => unknown) | undefined;
+
+		await plugin.setup({
+			onResolve(options, callback) {
+				if (String(options.filter) === String(/^bun:/)) {
+					onResolveCallback = callback;
+				}
+			},
+			onLoad() {},
+			module() {},
+		});
+
+		assert.ok(onResolveCallback);
+		assert.throws(
+			() => onResolveCallback?.({ path: 'bun:sqlite', importer: importerPath }),
+			new RegExp(
+				getNodeUnsupportedBuiltinError('bun:sqlite', importerPath).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+			),
+		);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});