Getting Started

Welcome to ScriptIt! This guide will help you get up and running with ScriptIt in just a few minutes.

What is ScriptIt?

ScriptIt is a powerful cross-runtime script runner that allows you to execute JavaScript and TypeScript scripts across Bun, Node.js, and Deno with enhanced features like:

• 🎨 Colored console output for better debugging
• 🖥️ Terminal UI (TUI) for interactive script management
• 🔧 Environment management with .env support
• ⚡ Cross-runtime compatibility with automatic detection
• 🚀 Enhanced script context with rich environment and utilities

Installation

Global Installation (Recommended)

Install ScriptIt globally to use the CLI from anywhere:

Bun

bun add -g @glyphtek/scriptit

npm

npm install -g @glyphtek/scriptit

pnpm

pnpm add -g @glyphtek/scriptit

yarn

yarn global add @glyphtek/scriptit

Local Installation

For use as a library in your project:

Bun

bun add @glyphtek/scriptit

npm

npm install @glyphtek/scriptit

pnpm

pnpm add @glyphtek/scriptit

yarn

yarn add @glyphtek/scriptit

Your First Script

Let's create a simple script to see ScriptIt in action.

1. Create a Script File

Create a file called hello.js:

// hello.js - Traditional execute function pattern
export const description = "Hello world script with colored console";

export async function execute(context) {
  // Use the enhanced console with fallback for colored output
  const console = context.console || global.console;
  
  console.log('👋 Hello from ScriptIt!');
  console.error('This is an error message');
  console.warn('This is a warning');
  console.info('This is info');
  console.debug('This is debug information');

  // Access the enhanced context
  console.log('Current working directory:', process.cwd());
  console.log('Script arguments:', process.argv.slice(2));
  
  return { message: 'Hello script completed successfully!' };
}

Or using the default export pattern:

// hello-default.js - Default export pattern
export const description = "Hello world default export script";

export default async function(context) {
  // Use the enhanced console with fallback for colored output
  const console = context.console || global.console;
  
  console.log('👋 Hello from ScriptIt Default!');
  console.info('This script uses the default export pattern');
  console.warn('Perfect for existing functions');
  
  return { message: 'Default export script completed!' };
}

2. Run with Colored Console

scriptit exec hello.js

You'll see beautiful colored output (enabled by default):

• 🤍 White for console.log
• 🔴 Red for console.error
• 🟡 Yellow for console.warn
• 🔵 Blue for console.info
• ⚫ Gray for console.debug

3. Try the Interactive TUI

scriptit run

This opens an interactive terminal interface where you can:

• Browse and select scripts
• View real-time output
• Manage multiple script executions

Key Features

Colored Console Output

ScriptIt provides colored console output when you use the enhanced context:

// In your script, use the fallback pattern for colors
export async function execute(context) {
  const console = context.console || global.console;
  
  console.log('Regular log message');     // White
  console.error('Error message');         // Red
  console.warn('Warning message');        // Yellow
  console.info('Info message');          // Blue
  console.debug('Debug message');        // Gray
}

Environment Variables

Create a .env file in your project:

API_KEY=your-secret-key
DATABASE_URL=postgresql://localhost:5432/mydb
NODE_ENV=development

Access them in your script:

export async function execute(context) {
  console.log('API Key:', context.env.API_KEY);
  console.log('Environment:', context.env.NODE_ENV);
}

Runtime Selection

ScriptIt automatically detects the best runtime, but you can specify one:

# Force Bun runtime
scriptit exec script.ts --runtime bun

# Force Node.js runtime
scriptit exec script.js --runtime node

# Force Deno runtime
scriptit exec script.ts --runtime deno

Library Usage

Use ScriptIt programmatically in your applications:

import { createScriptRunner } from '@glyphtek/scriptit'

const runner = await createScriptRunner({
  scriptsDir: './scripts',
  tmpDir: './tmp',
  consoleInterception: {
    enabled: true,
    useColors: true
  }
});

// Execute a script file
await runner.executeScript('hello.js')

// Execute with parameters
await runner.executeScript('process-data.js', {
  params: {
    inputFile: 'data.csv',
    outputDir: './output'
  },
  env: {
    NODE_ENV: 'production'
  }
})

// Listen to events
runner.on('script:beforeExecute', (scriptPath, params) => {
  console.log(`Starting script: ${scriptPath}`)
})

runner.on('script:afterExecute', (scriptPath, result) => {
  console.log(`Script ${scriptPath} completed successfully`)
})

runner.on('script:error', (scriptPath, error) => {
  console.error(`Script ${scriptPath} failed:`, error.message)
})

Script Structure Requirements

Important: ScriptIt requires your scripts to export either:

1. An execute function (traditional pattern):

export async function execute(context) {
  // Your script logic here
  return result; // optional
}

2. A default function (default export pattern):

export default async function(context) {
  // Your script logic here
  return result; // optional
}

Scripts without these functions will fail with an error.

Configuration

CLI Configuration

Create a scriptit.config.js file in your project root:

export default {
  scriptsDir: './scripts',
  tmpDir: './tmp',
  envFiles: ['.env'],
  consoleInterception: {
    enabled: true,
    useColors: true
  },
  timeout: 30000,
  workingDirectory: process.cwd()
}

Environment-Specific Settings

export default {
  development: {
    runtime: 'bun',
    consoleColors: true,
    verbose: true
  },
  production: {
    runtime: 'node',
    consoleColors: false,
    timeout: 60000
  }
}

Next Steps

Now that you have ScriptIt set up, explore these topics:

• CLI Commands - Learn all available CLI options
• Library API - Integrate ScriptIt into your applications
• Colored Console - Deep dive into console features
• Examples - See real-world usage examples

Need Help?

• 📖 Check the documentation
• 🐛 Report issues on GitHub
• 💬 Join discussions on GitHub Discussions

Happy scripting! 🚀