Source Transforms

A build plugin rewrites module source with its transform hook. The hook runs after the module is loaded in server, browser, and HMR builds, so it also sees what a loader produced, and it can return a source map.

Register the plugin in loaders when it belongs to your app, or return it from plugins(app) of a processor or integration you write.

There is no separate sourceTransforms configuration option. Component identity attribution and the server import.meta rewrite are core-owned build plugins that run after contributed plugins.

Writing a transform

import type { EcoBuildPlugin } from '@ecopages/core/processor';
 
export const bannerTransform: EcoBuildPlugin = {
	name: 'file-banner',
	setup(build) {
		build.transform({ filter: /entry\.tsx$/ }, (code, id) => {
			return { code: `/* transformed: ${id} */\n${code}` };
		});
	},
};
  • name identifies the plugin and must be unique among the plugins of an environment.
  • filter is a RegExp tested against the module id without its query or hash. The callback receives the id as the bundler gives it, so strip a query before reading the file.
  • The callback returns the rewritten source, { code, map? }, or undefined to skip the module. A rewrite that changes code without a map clears the earlier mappings; return map to keep locations.
  • environments: ['server'] or ['browser'] limits the plugin to one kind of build.

Checking a whole build

build.onEnd(callback) runs once every module of a build is transformed, so a plugin can check what its transforms saw across modules. It does not run when the build already failed, and an error it throws fails the build under the plugin's name.

export const noTodoCheck: EcoBuildPlugin = {
	name: 'no-todo',
	setup(build) {
		const files: string[] = [];
		build.transform({ filter: /\.tsx$/ }, (code, id) => {
			if (code.includes('TODO:')) files.push(id);
			return undefined;
		});
		build.onEnd(() => {
			if (files.length > 0) throw new Error(`TODO left in ${files.join(', ')}`);
		});
	},
};

Every build calls setup again, so keep build state inside setup. In development, the browser transform server builds one module at a time, so onEnd fires after each module there, seeing only that module; server builds in development and every production build run it once for the whole graph.

Registration

import { defineConfig } from '@ecopages/core/config';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';
import { bannerTransform } from './banner-transform';
 
export default defineConfig({
	baseUrl: 'https://example.com',
	loaders: [bannerTransform],
	integrations: [ecopagesJsxPlugin()],
});

Order

Transforms run in plugin order: loaders first, then processors, then integrations, and the plugins of each in the order they declare them. Core's own transforms run last: component identity attribution, then, in server builds, the rewrite that keeps import.meta pointing at the source files. A transform you register therefore sees the module before Ecopages attributes component identity and cannot run after it.

Choosing the Right Extension Point

MechanismUse when
EcoBuildPlugin (transform)A source rewrite, with an optional source map
EcoBuildPlugin (onLoad / onResolve)Virtual modules, custom loaders, or resolve-time behavior
Processor plugins(app)Plugins owned by a processor, such as asset loaders
Integration plugins(app)Framework-specific transforms or import aliasing

See also