CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-jiti

Runtime TypeScript and ESM support for Node.js with seamless interoperability between ESM and CommonJS.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

cli-tool.mddocs/

CLI Tool

Command-line interface for directly executing TypeScript files with full jiti transformation support.

Capabilities

jiti Command

Execute TypeScript and other supported files directly from the command line without compilation.

# CLI Usage
jiti <path> [...arguments]

Usage Examples:

# Execute a TypeScript file
jiti ./script.ts

# Execute with arguments
jiti ./cli-tool.ts --config ./config.json --verbose

# Execute from npm script
npm exec jiti ./build-script.ts

# Global installation
npm install -g jiti
jiti ./any-script.ts

CLI Features

Automatic File Type Detection: The CLI automatically handles various file extensions and applies appropriate transformations:

# All of these work seamlessly
jiti ./config.ts        # TypeScript
jiti ./script.mts       # TypeScript ESM
jiti ./legacy.cts       # TypeScript CommonJS  
jiti ./component.tsx    # TypeScript + JSX
jiti ./regular.js       # JavaScript
jiti ./module.mjs       # JavaScript ESM
jiti ./common.cjs       # JavaScript CommonJS

Node.js Integration:

  • Preserves Node.js command-line arguments and environment
  • Maintains proper process.argv handling
  • Supports Node.js debugging and profiling flags

Performance Optimization:

  • Enables Node.js compile cache when available (Node.js 22.8+)
  • Uses filesystem caching for repeated executions
  • Smart transformation detection to avoid unnecessary processing

Environment Configuration

Configure jiti CLI behavior using environment variables:

# Enable debug mode
JITI_DEBUG=1 jiti ./script.ts

# Enable JSX support
JITI_JSX=1 jiti ./component.tsx

# Disable filesystem caching
JITI_FS_CACHE=false jiti ./dev-script.ts

# Custom aliases
JITI_ALIAS='{"@/*": "./src/*"}' jiti ./script.ts

# Multiple options
JITI_DEBUG=1 JITI_JSX=1 JITI_SOURCE_MAPS=1 jiti ./complex-script.tsx

Integration with Development Workflows

Package.json Scripts:

{
  "scripts": {
    "dev": "jiti ./src/dev-server.ts",
    "build": "jiti ./scripts/build.ts",
    "test": "jiti ./scripts/test-runner.ts",
    "setup": "jiti ./scripts/setup.ts --init",
    "deploy": "NODE_ENV=production jiti ./scripts/deploy.ts"
  }
}

Development Server:

// dev-server.ts
import express from "express";
import { config } from "./config.ts";

const app = express();

app.get("/", (req, res) => {
  res.json({ message: "Development server running" });
});

app.listen(config.port, () => {
  console.log(`Server running on port ${config.port}`);
});
# Run development server directly
jiti ./dev-server.ts

Build Scripts:

// scripts/build.ts
import { execSync } from "child_process";
import { readFileSync, writeFileSync } from "fs";
import { BuildConfig } from "./types.ts";

const config: BuildConfig = {
  entry: "./src/index.ts",
  output: "./dist/bundle.js",
  minify: process.env.NODE_ENV === "production"
};

console.log("Building application...");
execSync(`esbuild ${config.entry} --bundle --outfile=${config.output}`);
console.log("Build complete!");
# Execute build script
jiti ./scripts/build.ts

Advanced CLI Usage

With Node.js Flags:

# Debug mode
node --inspect --loader jiti/loader ./script.ts

# Memory profiling
node --max-old-space-size=4096 $(which jiti) ./memory-intensive.ts

# ES modules with experimental features
node --experimental-modules $(which jiti) ./esm-script.ts

Complex Project Setup:

// scripts/setup.ts
import { existsSync, mkdirSync, writeFileSync } from "fs";
import { join } from "path";
import { Config } from "../src/types.ts";

interface SetupOptions {
  init?: boolean;
  config?: string;
  force?: boolean;
}

const args = process.argv.slice(2);
const options: SetupOptions = {
  init: args.includes("--init"),
  config: args.find(arg => arg.startsWith("--config="))?.split("=")[1],
  force: args.includes("--force")
};

async function setup() {
  console.log("Setting up project...");
  
  if (options.init) {
    const configPath = options.config || "./config.json";
    const defaultConfig: Config = {
      apiUrl: "http://localhost:3000",
      timeout: 5000
    };
    
    if (!existsSync(configPath) || options.force) {
      writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2));
      console.log(`Created config: ${configPath}`);
    }
  }
  
  // Additional setup logic...
  console.log("Setup complete!");
}

setup().catch(console.error);
# Run setup with options
jiti ./scripts/setup.ts --init --config=./custom-config.json --force

Error Handling and Debugging

Runtime Error Handling:

// error-prone-script.ts
try {
  const data = await import("./non-existent-config.ts");
} catch (error) {
  console.error("Failed to load config:", error.message);
  process.exit(1);
}
# CLI handles errors gracefully
jiti ./error-prone-script.ts
# Output: Failed to load config: Cannot resolve module './non-existent-config.ts'
# Exit code: 1

Debug Output:

# Enable debug output to see transformation details
JITI_DEBUG=1 jiti ./script.ts

Debug output includes:

  • File resolution paths
  • Transformation decisions
  • Cache usage information
  • Performance timings

Testing and Continuous Integration

Test Runner Integration:

// scripts/test-runner.ts
import { execSync } from "child_process";
import { globSync } from "glob";

const testFiles = globSync("./tests/**/*.test.ts");

for (const testFile of testFiles) {
  console.log(`Running: ${testFile}`);
  try {
    execSync(`jiti ${testFile}`, { stdio: "inherit" });
  } catch (error) {
    console.error(`Test failed: ${testFile}`);
    process.exit(1);
  }
}

console.log("All tests passed!");

CI/CD Integration:

# .github/workflows/test.yml
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install
      - run: npx jiti ./scripts/test-runner.ts
      - run: npx jiti ./scripts/lint-check.ts
      - run: npx jiti ./scripts/build-check.ts

Docker Integration:

# Dockerfile
FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm install

COPY . .

# Use jiti to run TypeScript directly
CMD ["npx", "jiti", "./src/server.ts"]

Performance Considerations

Caching for CLI:

# First run: slower (transformation + caching)
time jiti ./large-script.ts
# real    0m2.345s

# Subsequent runs: faster (cached)
time jiti ./large-script.ts  
# real    0m0.456s

Production Usage:

For production deployments, consider pre-compiling TypeScript:

{
  "scripts": {
    "build": "tsc",
    "start": "node ./dist/server.js",
    "dev": "jiti ./src/server.ts"
  }
}

Memory Usage:

# Monitor memory usage for large scripts
NODE_OPTIONS="--max-old-space-size=2048" jiti ./memory-intensive.ts

Comparison with Alternatives

vs ts-node:

# ts-node
npx ts-node ./script.ts

# jiti - simpler, faster startup
npx jiti ./script.ts

vs tsx:

# tsx
npx tsx ./script.ts

# jiti - more configuration options
JITI_DEBUG=1 npx jiti ./script.ts

Advantages of jiti CLI:

  • Zero configuration required
  • Built-in caching system
  • Comprehensive environment variable support
  • ESM/CommonJS interoperability
  • JSX support with configuration
  • Smart transformation detection
  • Cross-platform compatibility

docs

cli-tool.md

global-registration.md

index.md

instance-creation.md

module-import.md

transformation.md

tile.json