Bun.Transpiler API
Bun provides Bun.Transpiler for transpiling code, offering Bun-native transpilation capabilities.
bun apis/transpiler
23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
jsxImportSource compiler option
The jsxImportSource option specifies the module from which the component factory function (such as createElement, jsx, or jsxDEV) is imported. This option only applies when jsx is 'react-jsx' or 'react-jsxdev'. Default value is 'react'. When using jsxImportSource with react-jsx or react-jsxdev, the option automatically appends either /jsx-runtime or /jsx-dev-runtime to the import path.
JSX pragma comments per-file configuration
You can set JSX compiler options per file using pragma comments. The following pragmas are supported: (1) // @jsx h sets jsxFactory to 'h'; (2) // @jsxFrag MyFragment sets jsxFragmentFactory to 'MyFragment'; (3) // @jsxImportSource preact sets jsxImportSource to 'preact'.
JSX logging in Bun
Bun implements special logging for JSX that pretty-prints component trees when JSX is logged to console, making debugging easier by displaying a formatted visual representation of the component structure.
JSX prop punning shorthand
The Bun runtime supports prop punning for JSX, which is a shorthand for assigning a variable to a prop with the same name. Instead of writing <div className={className} />, you can write <div {className} />.
JSX configuration sources
Bun reads tsconfig.json or jsconfig.json to determine how to perform JSX transformation. If neither is used, the same options can be set in bunfig.toml.
jsx compiler option values and transpilation
The jsx compiler option controls how JSX constructs are transformed. Possible values are: (1) 'react' - transpiles <Box width={5}>Hello</Box> to React.createElement(Box, { width: 5 }, "Hello"); (2) 'react-jsx' - transpiles to import { jsx } from "react/jsx-runtime"; jsx("Box", { width: 5 }, "Hello"); (3) 'react-jsxdev' - transpiles to import { jsxDEV } from "react/jsx-dev-runtime"; jsxDEV("Box", { width: 5, children: "Hello" }, undefined, false, undefined, this); (4) 'preserve' - JSX is not transpiled and is not currently supported by Bun.
jsxFactory compiler option
The jsxFactory option specifies the function name used to represent JSX constructs when jsx is set to 'react'. Default value is 'React.createElement'. This is useful for libraries like Preact that use a different function name such as 'h'.
jsxFragmentFactory compiler option
The jsxFragmentFactory option specifies the function name used to represent JSX fragments such as <>Hello</> when jsx is set to 'react'. Default value is 'React.Fragment'.
Bun supports JSX and TSX files
Bun supports .jsx and .tsx files. Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution.
Bun.Transpiler MacroMap interface structure
The MacroMap type is a record where keys are package paths and values are objects mapping import item names to macro file paths. Example: { 'react-relay': { 'graphql': 'bun-macro-relay/bun-macro-relay.tsx' } }
Bun.Transpiler TSX example with imports and exports
Example showing transpilation of TypeScript JSX with imports and exports. Input code: `import * as whatever from './whatever.ts'; export function Home(props: {title: string}){ return <p>{props.title}</p>; }` is transpiled to vanilla JavaScript with JSX compiled to jsxDEV calls: `import * as whatever from './whatever.ts'; export function Home(props) { return jsxDEV_7x81h0kn('p', { children: props.title }, undefined, false, undefined, this); }`
Bun.Transpiler.scan() output example with mixed imports
Example output of scan() showing exports array with string names and imports array with import objects. Shown: exports: ['name'], imports: [{kind: 'import-statement', path: 'react'}, {kind: 'dynamic-import', path: './loader'}]. The require() call and type-only import are not included in the output.
Bun.Transpiler.scanImports() output example
Example output of scanImports() showing an array of import objects: [{kind: 'import-statement', path: 'react'}, {kind: 'require-call', path: './cjs.js'}, {kind: 'dynamic-import', path: './loader'}]. Type-only imports are excluded.
Bun.Transpiler class instantiation
Create a transpiler instance with `new Bun.Transpiler(options)`. The loader option specifies the file type to transpile: 'js', 'jsx', 'ts', or 'tsx'. Example: `const transpiler = new Bun.Transpiler({ loader: 'tsx' });`
Bun.Transpiler.transformSync() synchronous transpilation
The transformSync(code, loader?) method transpiles code synchronously and returns a string of vanilla JavaScript. It does not resolve modules or execute code. The optional loader parameter overrides the default loader specified in the constructor. Example: `const result = transpiler.transformSync(code);` or `transpiler.transformSync('<div>hi!</div>', 'tsx');`
Bun.Transpiler.transform() async transpilation
The transform(code, loader?) method is an async version of transformSync() that returns Promise<string>. It runs the transpiler in Bun's worker threadpool, spreading work across Math.floor($cpu_count * 0.8) threads without blocking the main JavaScript thread. The optional loader parameter overrides the default loader. Use transformSync unless transpiling many large files, as threadpool overhead often costs more than the transpilation itself.
Bun.Transpiler.scan() import/export scanning
The scan(code) method scans source code and returns an object with two properties: exports (array of export names) and imports (array of import objects). Type-only imports and exports are ignored. Each import object has a path and kind property.
Bun.Transpiler.scanImports() fast import scanning
The scanImports(code) method returns an array of import objects. It is faster than scan() especially for large files but marginally less accurate due to performance optimizations. Each import has a path and kind property.
Bun.Transpiler import kinds enumeration
Imports are categorized into the following kinds: 'import-statement' for `import Foo from 'bar'`, 'require-call' for `require('foo')`, 'require-resolve' for `require.resolve('foo')`, 'dynamic-import' for `import('foo')`, 'import-rule' for CSS `@import 'foo.css'`, 'url-token' for CSS `url('./foo.png')`, 'internal' for imports injected by Bun, 'entry-point-build' and 'entry-point-run' for entry points.
TranspilerOptions interface reference
The TranspilerOptions object passed to new Bun.Transpiler() accepts: define (Record<string, string> for key-value replacements, values must be JSON strings), loader (Loader type: 'jsx'|'js'|'ts'|'tsx'), target ('browser'|'bun'|'node' affecting import/require usage), tsconfig (string or object for tsconfig.json configuration, sets custom JSX factory/fragment/import source), macro (MacroMap for replacing imports with macros), exports ({eliminate?: string[], replace?: Record<string, string>}), trimUnusedImports (boolean, default false, removes unused imports), minifyWhitespace (boolean for experimental whitespace minification), inline (boolean, default false, inlines constant values).
Bun.Transpiler macro execution behavior
Macros run in the same thread as the transpiler but in a separate event loop from the rest of the application. Macros and regular code share globals, making it possible (but not recommended) to share state between them. Using AST nodes outside of a macro is undefined behavior.
TranspilerOptions.define key-value replacement example
The define option replaces keys with values where values must be JSON strings. Example: { 'process.env.NODE_ENV': '"production"' }