Global Registration and ESM Loader

// Import for automatic global registration
import "jiti/register";

// Method 1: Import in your entry file
import "jiti/register";
import { config } from "./config.ts"; // Automatically works

console.log(config);

# Method 2: Use Node.js --import flag
node --import jiti/register index.js

# Method 3: Use via environment variable
NODE_OPTIONS="--import jiti/register" node index.js

import { createJiti } from "jiti/native";

/**
 * Creates a native jiti instance with limited API surface
 * @param parentURL - Parent URL for resolution context
 * @param jitiOptions - Limited options for native mode
 * @returns Jiti instance with native-only capabilities
 */
function createJiti(parentURL?: string | URL, jitiOptions?: JitiOptions): NativeJiti;

interface NativeJiti {
  // ✅ Supported methods
  import<T>(id: string, opts?: JitiResolveOptions & { default?: true }): Promise<T>;
  esmResolve(id: string, opts?: string | JitiResolveOptions): string;
  
  // ❌ Unsupported methods (throw errors)
  (id: string): never; // Throws: "jiti() is not supported in native mode, use jiti.import() instead"
  transform(opts: TransformOptions): never; // Throws: "transform() is not supported in native mode"
  evalModule(source: string, options?: EvalModuleOptions): never; // Throws: "evalModule() is not supported in native mode"
  resolve: never; // Throws: "resolve() is not supported in native mode"
}

import { createJiti } from "jiti/native";

// Create native jiti instance
const jiti = createJiti(import.meta.url);

// Only import() and esmResolve() work in native mode
const module = await jiti.import("./config.js");
const resolved = jiti.esmResolve("./utils.js");

// These methods throw errors in native mode:
try {
  jiti.transform({ source: "code" }); // Throws: not supported in native mode
} catch (error) {
  console.error(error.message); // "`transform()` is not supported in native mode"
}

try {
  jiti.evalModule("code"); // Throws: not supported in native mode
} catch (error) {
  console.error(error.message); // "`evalModule()` is not supported in native mode"
}

try {
  jiti("./module"); // Throws: not supported in native mode
} catch (error) {
  console.error(error.message); // "`jiti()` is not supported in native mode, use `jiti.import()` instead"
}

// ESM Loader Hooks (internal implementation)
export async function resolve(specifier: string, context: ResolveContext, nextResolve: Function): Promise<ResolveResult>;
export async function load(url: string, context: LoadContext, nextLoad: Function): Promise<LoadResult>;

# Enable JSX and debug mode globally
JITI_JSX=1 JITI_DEBUG=1 node --import jiti/register app.js

# Disable caching for development
JITI_FS_CACHE=false node --import jiti/register dev-server.js

// Only register in development
if (process.env.NODE_ENV === "development") {
  await import("jiti/register");
}

// Import your TypeScript modules after registration
const { devUtils } = await import("./dev-utils.ts");

// main.ts - Entry point with global registration
import "jiti/register";

// Now all imports in your app automatically support TypeScript
import { config } from "./config/app.ts";
import { routes } from "./routes/index.ts";
import { middleware } from "./middleware/auth.ts";

async function startApp() {
  const server = (await import("./server.ts")).default;
  server.start();
}

startApp();

// Enable TypeScript for your library's development
// lib/index.ts
export { LibraryClass } from "./core.ts";
export type { LibraryOptions } from "./types.ts";

// During development, use jiti for testing
// test/setup.ts
import "jiti/register";
import { test } from "./lib/index.ts"; // Uses TypeScript directly

// ✅ Good for native mode - JavaScript only
const jiti = createJiti("jiti/native");
await jiti.import("./config.js");
await jiti.import("./utils.mjs");

// ❌ Not suitable for native mode - needs transformation
await jiti.import("./config.ts"); // TypeScript
await jiti.import("./component.tsx"); // JSX

// Development: Use global registration for TypeScript
if (process.env.NODE_ENV === "development") {
  await import("jiti/register");
  const { devConfig } = await import("./config.dev.ts");
} else {
  // Production: Use compiled JavaScript
  const { prodConfig } = await import("./config.prod.js");
}

// vitest.config.js or jest.config.js
export default {
  setupFilesAfterEnv: ["jiti/register"],
  // Now test files can import TypeScript directly
};

{
  "scripts": {
    "dev": "node --import jiti/register src/dev-server.ts",
    "test": "NODE_OPTIONS='--import jiti/register' vitest",
    "debug": "JITI_DEBUG=1 node --import jiti/register --inspect src/index.ts"
  }
}

// If a TypeScript file has syntax errors, the loader will provide:
// - File location with line/column numbers
// - Syntax error details
// - Code frame showing the problematic code

try {
  await import("./broken-syntax.ts");
} catch (error) {
  console.error("TypeScript compilation failed:");
  console.error(error.message);
  console.error(error.location); // File:line:column
}

# Enable debug logging to see loader operations
JITI_DEBUG=1 node --import jiti/register app.ts

// jiti automatically detects runtime capabilities
const jiti = createJiti(import.meta.url, {
  tryNative: true // Try native import first, fallback to transformation
});

// In Bun, this automatically uses native capabilities
// In Node.js, this uses transformation when needed
const module = await jiti.import("./file.ts");

// Works across different JavaScript runtimes
import { createJiti } from "jiti/native";

// Deno support
const jiti = createJiti(import.meta.url);
const module = await jiti.import("./config.ts");

// Bun support with enhanced native capabilities
const jiti = createJiti(import.meta.url, {
  tryNative: true // Bun has excellent native TypeScript support
});