Instance Creation and Configuration

/**
 * Creates a new Jiti instance with custom options.
 * @param id - Instance id, usually the current filename or import.meta.url
 * @param userOptions - Custom options to override the default options
 * @returns A Jiti instance with configured behavior
 */
function createJiti(id: string, userOptions?: JitiOptions): Jiti;

import { createJiti } from "jiti";

// Basic usage with current file URL
const jiti = createJiti(import.meta.url);

// With custom options
const jiti = createJiti(import.meta.url, {
  debug: true,
  fsCache: false,
  jsx: true
});

// CommonJS usage (deprecated)
const { createJiti } = require("jiti");
const jiti = createJiti(__filename);

interface JitiOptions {
  /**
   * Filesystem source cache - enables caching transformed files to disk
   * @default true
   */
  fsCache?: boolean | string;
  
  /**
   * Rebuild the filesystem source cache
   * @default false
   */
  rebuildFsCache?: boolean;
  
  /**
   * Runtime module cache - integrates with Node.js require.cache
   * @default true
   */
  moduleCache?: boolean;
  
  /**
   * Enable verbose debugging output
   * @default false
   */
  debug?: boolean;
  
  /**
   * Enable sourcemaps for transformed code
   * @default false
   */
  sourceMaps?: boolean;
  
  /**
   * Enable default export interoperability using Proxy
   * @default true
   */
  interopDefault?: boolean;
  
  /**
   * Supported file extensions for transformation
   * @default [".js", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts", ".mtsx", ".ctsx", ".json"]
   */
  extensions?: string[];
  
  /**
   * Custom transform function for source code
   */
  transform?: (opts: TransformOptions) => TransformResult;
  
  /**
   * Transform options passed to the transform function
   */
  transformOptions?: Omit<TransformOptions, "source">;
  
  /**
   * Resolve aliases for module paths
   * @default {}
   */
  alias?: Record<string, string>;
  
  /**
   * Modules to always use native require/import for
   * @default ["typescript", "jiti"]
   */
  nativeModules?: string[];
  
  /**
   * Modules to transform regardless of syntax
   * @default []
   */
  transformModules?: string[];
  
  /**
   * Parent module's import.meta context for ESM resolution
   */
  importMeta?: ImportMeta;
  
  /**
   * Try native require/import before jiti transformations
   * @default false (true if Bun is detected)
   */
  tryNative?: boolean;
  
  /**
   * Enable JSX support using @babel/plugin-transform-react-jsx
   * @default false
   */
  jsx?: boolean | JSXOptions;
  
  /**
   * @deprecated Use the fsCache option instead
   * @default true
   */
  cache?: boolean | string;
  
  /**
   * @deprecated Use the moduleCache option instead
   * @default true
   */
  requireCache?: boolean;
  
  /**
   * Internal cache version for filesystem cache
   * @internal
   */
  cacheVersion?: string;
}

# Enable debug mode and JSX support
JITI_DEBUG=1 JITI_JSX=1 node script.js

# Set custom aliases
JITI_ALIAS='{"@/*": "./src/*", "~/*": "./lib/*"}' node script.js

# Disable caching for development
JITI_FS_CACHE=false JITI_MODULE_CACHE=false node script.js

interface JSXOptions {
  /**
   * Throw error if JSX namespace is used
   * @default false
   */
  throwIfNamespace?: boolean;
  
  /**
   * JSX runtime mode - 'classic' uses React.createElement, 'automatic' uses new JSX transform
   * @default 'classic'
   */
  runtime?: "classic" | "automatic";
  
  /**
   * Import source for automatic runtime
   * @default 'react'
   */
  importSource?: string;
  
  /**
   * JSX pragma function for classic runtime
   * @default 'React.createElement'
   */
  pragma?: string;
  
  /**
   * JSX fragment pragma for classic runtime
   * @default 'React.Fragment'
   */
  pragmaFrag?: string;
  
  /**
   * Use built-in helpers for JSX
   * @default false
   */
  useBuiltIns?: boolean;
  
  /**
   * Use spread syntax for props
   * @default false
   */
  useSpread?: boolean;
}

// Enable JSX with default React settings
const jiti = createJiti(import.meta.url, { jsx: true });

// Custom JSX configuration for Preact
const jiti = createJiti(import.meta.url, {
  jsx: {
    runtime: "automatic",
    importSource: "preact"
  }
});

// Classic JSX with custom pragma
const jiti = createJiti(import.meta.url, {
  jsx: {
    runtime: "classic",
    pragma: "h",
    pragmaFrag: "Fragment"
  }
});

// Custom filesystem cache directory
const jiti = createJiti(import.meta.url, {
  fsCache: "./custom-cache"
});

// Disable all caching for development
const jiti = createJiti(import.meta.url, {
  fsCache: false,
  moduleCache: false
});

// Force cache rebuild
const jiti = createJiti(import.meta.url, {
  rebuildFsCache: true
});