Single-file transformation capabilities for syntax conversion, minification, and format conversion without full bundling. The transform API is ideal for processing individual files, code snippets, or when you need quick transformations without dependency resolution.
Transforms a single file or code string with the specified options.
/**
* Transform a single file or code string
* @param input - Source code as string or Uint8Array
* @param options - Transformation options
* @returns Promise resolving to transformation results
*/
function transform(
input: string | Uint8Array,
options?: TransformOptions
): Promise<TransformResult>;Usage Examples:
import * as esbuild from "esbuild";
// Transform TypeScript to JavaScript
const result = await esbuild.transform(`
interface User {
name: string;
age: number;
}
const user: User = { name: "Alice", age: 30 };
console.log(\`Hello, \${user.name}!\`);
`, {
loader: "ts",
format: "esm",
target: "es2020",
});
console.log(result.code);
// Transform and minify
const minified = await esbuild.transform(`
function calculateTax(price, rate) {
return price * (1 + rate);
}
`, {
loader: "js",
minify: true,
});
// Transform JSX
const jsxResult = await esbuild.transform(`
const App = () => {
return <div>Hello World</div>;
};
`, {
loader: "jsx",
jsx: "transform",
jsxFactory: "React.createElement",
});Synchronous version of the transform function. Node.js only - throws error in browser environments.
/**
* Synchronously transform a single file or code string
* @param input - Source code as string or Uint8Array
* @param options - Transformation options
* @returns Transformation results
* @throws Error in browser environments
*/
function transformSync(
input: string | Uint8Array,
options?: TransformOptions
): TransformResult;Usage Example:
import * as esbuild from "esbuild";
// Synchronous transformation (Node.js only)
try {
const result = esbuild.transformSync(`
const greeting = (name: string) => \`Hello \${name}!\`;
export { greeting };
`, {
loader: "ts",
format: "cjs",
});
console.log("Transformed code:", result.code);
} catch (error) {
console.error("Transform failed:", error);
}Configuration options for transform operations. Extends CommonOptions with transform-specific options.
interface TransformOptions extends CommonOptions {
// Transform-specific options
sourcefile?: string;
loader?: Loader;
banner?: string;
footer?: string;
}Result object returned by transform operations.
interface TransformResult {
code: string;
map: string;
warnings: Message[];
mangleCache?: Record<string, string | false>;
legalComments?: string;
}Error object thrown when transforms fail.
interface TransformFailure extends Error {
errors: Message[];
warnings: Message[];
}ESBuild supports numerous file loaders for different input types:
type Loader =
| "js" // JavaScript
| "jsx" // JavaScript with JSX
| "ts" // TypeScript
| "tsx" // TypeScript with JSX
| "css" // CSS stylesheets
| "json" // JSON data
| "text" // Plain text
| "base64" // Base64 encoded data
| "dataurl" // Data URL format
| "file" // File path reference
| "binary" // Binary data
| "copy" // Copy file as-is
| "default" // Use file extension
| "empty" // Empty module
| "local-css"; // CSS modulesUsage Examples:
// Different loaders
const cssResult = await esbuild.transform(`
.header { color: blue; font-size: 18px; }
`, { loader: "css", minify: true });
const jsonResult = await esbuild.transform(`{
"name": "example",
"version": "1.0.0"
}`, { loader: "json" });
const textResult = await esbuild.transform(`
Hello World!
This is plain text.
`, { loader: "text" });