or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

build-context.md core-build-api.md file-transformation.md index.md plugin-system.md utility-functions.md

tile.json

Core Build API

Primary build functionality for bundling, transforming, and optimizing JavaScript/CSS projects. The build API analyzes entry points, resolves dependencies, applies transformations, and generates optimized output files.

Capabilities

Build Function (Async)

Performs a complete build operation with full bundling, optimization, and file generation.

/**
 * Build a project with the specified options
 * @param options - Build configuration options
 * @returns Promise resolving to build results
 */
function build(options: BuildOptions): Promise<BuildResult>;

Usage Examples:

import * as esbuild from "esbuild";

// Simple bundle
const result = await esbuild.build({
  entryPoints: ["src/app.js"],
  bundle: true,
  outfile: "dist/app.js",
});

// Multiple entry points with code splitting
await esbuild.build({
  entryPoints: ["src/home.js", "src/about.js"],
  bundle: true,
  splitting: true,
  format: "esm",
  outdir: "dist",
});

// TypeScript with custom configuration
await esbuild.build({
  entryPoints: ["src/main.ts"],
  bundle: true,
  platform: "node",
  target: "node18",
  format: "cjs",
  outfile: "dist/main.js",
  minify: true,
  sourcemap: true,
});

Build Function (Sync)

Synchronous version of the build function. Node.js only - throws error in browser environments.

/**
 * Synchronously build a project with the specified options
 * @param options - Build configuration options  
 * @returns Build results
 * @throws Error in browser environments
 */
function buildSync(options: BuildOptions): BuildResult;

Usage Example:

import * as esbuild from "esbuild";

// Synchronous build (Node.js only)
try {
  const result = esbuild.buildSync({
    entryPoints: ["src/app.js"],
    bundle: true,
    outfile: "dist/app.js",
    minify: true,
  });
  
  console.log("Build completed:", result.outputFiles?.length, "files");
} catch (error) {
  console.error("Build failed:", error);
}

Types

CommonOptions Interface

Shared configuration options for both build and transform operations.

interface CommonOptions {
  // Source Maps
  sourcemap?: boolean | "linked" | "inline" | "external" | "both";
  sourcesContent?: boolean;
  sourceRoot?: string;
  
  // Output Format
  format?: Format;
  globalName?: string;
  
  // Target and Compatibility
  target?: string | string[];
  supported?: Record<string, boolean>;
  platform?: Platform;
  
  // Code Processing
  minify?: boolean;
  minifyWhitespace?: boolean;
  minifyIdentifiers?: boolean;
  minifySyntax?: boolean;
  lineLimit?: number;
  treeShaking?: boolean;
  ignoreAnnotations?: boolean;
  
  // Property Mangling
  mangleProps?: RegExp;
  reserveProps?: RegExp;
  mangleQuoted?: boolean;
  mangleCache?: Record<string, string | false>;
  
  // Code Removal
  drop?: Drop[];
  dropLabels?: string[];
  
  // JavaScript/TypeScript/JSX
  jsx?: "transform" | "preserve" | "automatic";
  jsxFactory?: string;
  jsxFragment?: string;
  jsxImportSource?: string;
  jsxDev?: boolean;
  jsxSideEffects?: boolean;
  
  // Code Modification
  define?: Record<string, string>;
  pure?: string[];
  keepNames?: boolean;
  
  // Logging
  logLevel?: LogLevel;
  logLimit?: number;
  logOverride?: Record<string, LogLevel>;
  color?: boolean;
  absPaths?: AbsPaths[];
  
  // Legal
  legalComments?: "none" | "inline" | "eof" | "linked" | "external";
  
  // CSS
  charset?: Charset;
  
  // TypeScript Configuration
  tsconfigRaw?: string | TsconfigRaw;
}

BuildOptions Interface

Complete configuration interface for build operations. Extends CommonOptions with build-specific options.

interface BuildOptions extends CommonOptions {
  // Entry Points
  entryPoints?: string[] | Record<string, string> | { in: string; out: string }[];
  stdin?: StdinOptions;
  
  // Output Configuration
  bundle?: boolean;
  outfile?: string;
  outdir?: string;
  outbase?: string;
  platform?: Platform;
  format?: Format;
  splitting?: boolean;
  preserveSymlinks?: boolean;
  
  // Code Processing
  minify?: boolean;
  minifyWhitespace?: boolean;
  minifyIdentifiers?: boolean;
  minifySyntax?: boolean;
  treeShaking?: boolean;
  ignoreAnnotations?: boolean;
  
  // Source Maps
  sourcemap?: boolean | "linked" | "inline" | "external" | "both";
  sourcesContent?: boolean;
  sourceRoot?: string;
  
  // Target and Compatibility
  target?: string | string[];
  supported?: Record<string, boolean>;
  
  // Module Resolution
  external?: string[];
  packages?: "external" | "bundle";
  alias?: Record<string, string>;
  loader?: Record<string, Loader>;
  resolveExtensions?: string[];
  mainFields?: string[];
  conditions?: string[];
  
  // File Processing
  write?: boolean;
  metafile?: boolean;
  outExtension?: Record<string, string>;
  publicPath?: string;
  entryNames?: string;
  chunkNames?: string;
  assetNames?: string;
  
  // JavaScript/TypeScript
  jsx?: "transform" | "preserve" | "automatic";
  jsxFactory?: string;
  jsxFragment?: string;
  jsxImportSource?: string;
  jsxDev?: boolean;
  jsxSideEffects?: boolean;
  
  // Advanced
  plugins?: Plugin[];
  absWorkingDir?: string;  
  nodePaths?: string[];
  banner?: Record<string, string>;
  footer?: Record<string, string>;
  inject?: string[];
  define?: Record<string, string>;
  pure?: string[];
  keepNames?: boolean;
  globalName?: string;
  mangleProps?: RegExp;
  reserveProps?: RegExp;
  mangleQuoted?: boolean;
  mangleCache?: Record<string, string | false>;
  drop?: Drop[];
  dropLabels?: string[];
  
  // Logging
  logLevel?: LogLevel;
  logLimit?: number;
  logOverride?: Record<string, LogLevel>;
  
  // Legal
  legalComments?: "none" | "inline" | "eof" | "linked" | "external";
  
  // CSS
  charset?: Charset;
}

interface StdinOptions {
  contents: string | Uint8Array;
  resolveDir?: string;
  sourcefile?: string; 
  loader?: Loader;
}

interface TsconfigRaw {
  compilerOptions?: {
    alwaysStrict?: boolean;
    baseUrl?: string;
    experimentalDecorators?: boolean;
    importsNotUsedAsValues?: "remove" | "preserve" | "error";
    jsx?: "preserve" | "react-native" | "react" | "react-jsx" | "react-jsxdev";
    jsxFactory?: string;
    jsxFragmentFactory?: string;
    jsxImportSource?: string;
    paths?: Record<string, string[]>;
    preserveValueImports?: boolean;
    strict?: boolean;
    target?: string;
    useDefineForClassFields?: boolean;
    verbatimModuleSyntax?: boolean;
  };
}

BuildResult Interface

Result object returned by build operations.

interface BuildResult {
  errors: Message[];
  warnings: Message[];
  outputFiles?: OutputFile[];
  metafile?: Metafile;
  mangleCache?: Record<string, string | false>;
}

interface OutputFile {
  path: string;
  contents: Uint8Array;
  hash: string;
  readonly text: string;
}

interface Message {
  id: string;
  pluginName: string;
  text: string;
  location?: Location;
  notes: Note[];
  detail: any;
}

interface Location {
  file: string;
  namespace: string;
  line: number;
  column: number;
  length: number;
  lineText: string;
  suggestion: string;
}

BuildFailure Interface

Error object thrown when builds fail.

interface BuildFailure extends Error {
  errors: Message[];
  warnings: Message[];
}

Platform and Format Types

type Platform = "browser" | "node" | "neutral";
type Format = "iife" | "cjs" | "esm";
type LogLevel = "verbose" | "debug" | "info" | "warning" | "error" | "silent";
type Charset = "ascii" | "utf8";
type Drop = "console" | "debugger";
type AbsPaths = "code" | "log" | "metafile";
type Loader = "base64" | "binary" | "copy" | "css" | "dataurl" | "default" | "empty" | "file" | "js" | "json" | "jsx" | "local-css" | "text" | "ts" | "tsx";