✨ Features

• ⚡ Lightning Fast - Bundles JavaScript in milliseconds using esbuild
• 🔧 Zero Config - Works out of the box, no configuration needed
• ✂️ Minification - Optional built-in minification
• 📊 Build Reports - See exactly what's contributing to your bundle size
• 👀 Watch Mode - Auto-rebuild on file changes during development
• 🗺️ Source Maps - Debug with linked or inline source maps
• 🎨 Beautiful Output - Colored CLI with helpful messages
• 🤖 Non-Interactive Mode - Perfect for CI/CD pipelines
• 🔄 Config Files - Support for JSON configuration files

📋 Prerequisites

• Node.js: v18 or higher (required for npm installation and Go binary)
• Go: v1.21 or higher (only if building from source)
• Operating System: Windows, macOS, or Linux

🚀 Installation

Option 1: Install via npm (Recommended)

# Install globally
npm install -g jspackr

# Verify installation
jspackr --version

Option 2: Install via Go

# Install latest version
go install github.com/kalokaradia/jspackr@latest

# Verify installation
jspackr --version

Option 3: Build from Source

# Clone the repository
git clone https://github.com/kalokaradia/jspackr.git
cd jspackr

# Build the binary
go build -o bin/jspackr src/main/main.go

# Make it executable (Linux/macOS)
chmod +x bin/jspackr

# Run directly
./bin/jspackr --version

Option 4: Manual Installation

Download the appropriate binary for your platform from the releases page:

# Linux/macOS
sudo mv jspackr /usr/local/bin/jspackr

# Windows
# Move jspackr.exe to your PATH

🎯 Quick Start

Basic Bundling

Bundle a JavaScript file with default settings:

jspackr src/index.js

This creates:

dist/bundle.js

With Options

jspackr -i src/index.js -o dist/app.js -m -r -w

This will:

• 📥 Bundle src/index.js
• 📤 Write to dist/app.js
• ✂️ Minify the output
• 📊 Show build report
• 👀 Watch for changes

📖 Usage

Command Syntax

jspackr [options]

CLI Options

| Short | Long Form | Description | Default | | ----- | --------------------- | ------------------------------------------- | ---------------- | | -i | --input <file> | Entry JavaScript file | Required | | -o | --out <file> | Output bundle file | dist/bundle.js | | -c | --config <file> | Path to config file | Optional | | -m | --minify | Minify the output | false | | -r | --report | Generate build report | false | | -s | --source <mode> | Source map mode: none, linked, inline | none | | -w | --watch | Enable watch mode | false | | | --log-level <level> | Log level: debug, info, warn, error | info | | -f | --force | Force overwrite without confirmation | false | | -y | --yes | Auto-confirm all prompts | false | | -n | --no-confirm | Skip all confirmation prompts | false | | -v | --version | Show version (standalone) | - | | -h | --help | Show help message | - |

Help Command

# Show help
jspackr --help

# Show version
jspackr --version

⚙️ Configuration File

Create a jspackr.config.json file for persistent configuration:

{
	"input": "./src/index.js",
	"output": "./dist/bundle.js",
	"minify": true,
	"report": true,
	"sourceMap": "linked",
	"watch": false,
	"logLevel": "info"
}

Config File Options

| Option | Type | Description | | ----------- | ------- | ----------------------------------------------- | | input | string | Entry JavaScript file path | | output | string | Output bundle file path | | minify | boolean | Minify the output bundle | | report | boolean | Generate build report | | sourceMap | string | Source map mode: none, linked, inline | | watch | boolean | Enable watch mode | | logLevel | string | Log verbosity: debug, info, warn, error |

Using Config File

# Use default config (jspackr.config.json)
jspackr

# Specify custom config file
jspackr -c custom.config.json

💡 Examples

Example 1: Basic Bundle

# Bundle a single file
jspackr -i src/index.js

# With custom output
jspackr -i src/index.js -o dist/app.js

Example 2: Production Build

# Minified with source map and report
jspackr -i src/index.js -o dist/app.min.js -m -r -s inline

Example 3: Development with Watch Mode

# Watch for changes and rebuild automatically
jspackr -i src/index.js -o dist/app.js -w

Example 4: CI/CD / Non-Interactive

# Force overwrite, skip all confirmations
jspackr -i src/index.js -o dist/app.js -f

# Or with yes flag
jspackr -i src/index.js -o dist/app.js -y

# Or completely non-interactive
jspackr -i src/index.js -o dist/app.js -n

Example 5: Using Configuration File

Create jspackr.config.json:

{
	"input": "./src/app.js",
	"output": "./build/app.js",
	"minify": true,
	"report": true
}

Run:

jspackr

Example 6: Verbose Logging

# Debug mode
jspackr -i src/index.js --log-level debug

# Quiet mode
jspackr -i src/index.js --log-level warn

Example 7: Multiple Options Combined

# Production-ready bundle with all features
jspackr \
  --input src/index.js \
  --output dist/app.js \
  --minify \
  --report \
  --source linked \
  --log-level info

📊 Build Report

When using the --report flag, jspackr generates a detailed breakdown:

Bundle Size: 45.2 KB
⏱️  Build Time: 123ms

📦 Dependencies:
  src/utils.js      12.3 KB
  src/helpers.js    8.1 KB
  src/index.js      2.4 KB
  ...

🗺️ Source Maps

| Mode | Flag Value | Description | | ------ | ---------- | ------------------------------------- | | None | none | No source map (default) | | Linked | linked | Separate .map file linked via comment | | Inline | inline | Embedded as base64 in the bundle |

# Linked source map
jspackr -i src/index.js -s linked

# Inline source map
jspackr -i src/index.js -s inline

📁 Project Structure

jspackr/
├── bin/                    # Compiled binaries
├── src/
│   ├── cli/               # CLI output and styling
│   │   ├── logger.go      # Logging functionality
│   │   ├── styles.go      # Colored output styles
│   │   └── ui.go          # UI components
│   ├── config/            # Configuration management
│   │   ├── config.go      # Config structures
│   │   ├── loader.go      # JSON config loading
│   │   ├── merger.go      # Config merging
│   │   └── validator.go   # Config validation
│   ├── core/
│   │   ├── builder/       # Bundling logic
│   │   │   ├── builder.go # Main builder
│   │   │   ├── report.go  # Build reporting
│   │   │   └── sourcemap.go # Source map handling
│   │   └── watcher/       # File watching
│   │       ├── debouncer.go
│   │       ├── hasher.go
│   │       └── watcher.go
│   ├── main/
│   │   └── main.go        # Entry point
│   └── utils/
│       ├── confirm.go     # Confirmation prompts
│       ├── file.go        # File utilities
│       └── flags.go       # CLI flags parsing
├── .gitignore
├── .npmignore
├── go.mod
├── go.sum
├── LICENSE
├── logo.svg
├── package.json
└── README.md

🐛 Troubleshooting

Command Not Found

If jspackr is not found after installation:

# Add to PATH (npm global)
npm config get prefix
# Add the output path to your shell profile

# Or for Go installation
echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission Denied

# Linux/macOS
sudo chown $(whoami) /usr/local/bin/jspackr

# Or use npm with sudo (not recommended)
sudo npm install -g jspackr

Node Version Too Old

# Check version
node --version

# Update using nvm (Linux/macOS)
nvm install 18
nvm use 18

# Or download from nodejs.org

Build Fails

# Clear cache and rebuild
go clean -cache
go build -o bin/jspackr src/main/main.go

# Check dependencies
go mod download
go mod verify

Watch Mode Not Working

# Ensure you're not using network drives
# Check file permissions
ls -la src/

# Try with absolute paths
jspackr -i /absolute/path/to/index.js

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Fork the repository
git clone https://github.com/YOUR-USERNAME/jspackr.git
cd jspackr

# Create a feature branch
git checkout -b feature/amazing-feature

# Make changes
# Test your changes
go test ./...

# Commit your changes
git commit -m "Add amazing feature"

# Push to GitHub
git push origin feature/amazing-feature

# Open a Pull Request

Coding Standards

• Follow Go formatting conventions (gofmt)
• Add comments for public functions
• Write tests for new features
• Update documentation as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• esbuild for the amazing bundling engine
• fatih/color for colored terminal output
• All contributors and users!

📧 Contact

• Author: Kaloka Radia Nanda
• GitHub: @kalokaradia
• Issues: Report a bug