nalaka/auto_reset

Ballerimon 🚀

The nodemon for Ballerina - Auto-restart your Ballerina applications during development.

Ballerimon is a command-line tool that monitors your Ballerina files and automatically restarts your application when changes are detected. Just like nodemon for Node.js, but for Ballerina!

Features

• 🔍 Auto-monitoring: Watches .bal and .toml files automatically
• 🚀 Auto-restart: Instantly restarts your app when files change
• 🎯 Smart filtering: Ignores build directories and common artifacts
• ⚙️ CLI-friendly: Simple command-line interface
• 🖥️ Cross-platform: Works on Windows, macOS, and Linux
• � Beautiful output: Clean, emoji-rich console messages

Installation

Option 1: From Ballerina Central (Recommended)

bal tool install nalaka/auto_reset

Option 2: From Source

git clone <repository>
cd ballerimon
bal build

Usage

Ballerimon works exactly like nodemon - just prefix your Ballerina command with ballerimon:

# Instead of: bal run
ballerimon bal run

# Instead of: bal run service.bal  
ballerimon bal run service.bal

# Instead of: bal run --debug=5005
ballerimon bal run --debug=5005

# Works with any Ballerina command
ballerimon bal test

Examples

Basic HTTP Service

# Start your service with auto-restart
ballerimon bal run service.bal

Debug Mode

# Run with debugging enabled
ballerimon bal run --debug=5005 service.bal

Custom Package

# Run a specific package
ballerimon bal run mypackage

Testing

# Auto-run tests when files change
ballerimon bal test

How It Works

1. Start Monitoring: Ballerimon starts watching your current directory
2. Run Command: Executes your Ballerina command (e.g., bal run)
3. Watch for Changes: Monitors .bal and .toml files
4. Auto-restart: When changes are detected:
   • Stops the current process
   • Waits for additional changes (debounce)
   • Restarts your application

Output Example

🚀 Ballerimon - Auto-restart tool for Ballerina applications
Similar to nodemon for Node.js

📁 Watching: ./
🔧 Command: bal run service.bal
👀 Monitoring .bal files for changes...

Press Ctrl+C to stop watching

🔍 Starting file watcher...
▶️  Starting application...
✅ Application started successfully

📝 File changed: service.bal

🔄 Changes detected - restarting...
⏹️  Stopping application...
▶️  Starting application...  
✅ Application started successfully

Comparison with nodemon

If you're familiar with nodemon for Node.js, here's how Ballerimon compares:

Migration from Manual Workflow

Before (Manual):

# Edit your files...
# Ctrl+C to stop
bal run service.bal
# Make more changes...
# Ctrl+C to stop again
bal run service.bal
# Repeat...

After (Ballerimon):

ballerimon bal run service.bal
# Edit files and see automatic restarts! 🎉

Configuration

Ballerimon uses sensible defaults but can be customized:

• Watch Extensions: .bal, .toml
• Ignore Paths: target/, .ballerina/, tests/, .git/, node_modules/
• Debounce Time: 1000ms (1 second)
• Working Directory: Current directory

Real-World Examples

Web API Development

# Start your REST API with auto-restart
ballerimon bal run api.bal

# Your service.bal file:
service /api on new http:Listener(8080) {
    resource function get hello() returns string {
        return "Hello, World!";
    }
}

Microservice Development

# Start multiple services (use different terminals)
ballerimon bal run user-service.bal    # Terminal 1
ballerimon bal run order-service.bal   # Terminal 2
ballerimon bal run payment-service.bal # Terminal 3

Integration Testing

# Auto-run tests when code changes
ballerimon bal test

# Specific test file
ballerimon bal test tests/integration_test.bal

Best Practices

1. Use with Version Control

Add Ballerimon to your development workflow:

# Start development server
ballerimon bal run service.bal

# In another terminal, continue with git workflow
git add .
git commit -m "Add new feature"

2. Environment Variables

# Set environment variables before starting
export DATABASE_URL=localhost:5432
ballerimon bal run service.bal

3. Debug Mode

# Enable debugging and auto-restart
ballerimon bal run --debug=5005 service.bal

4. Production vs Development

# Development (with Ballerimon)
ballerimon bal run service.bal

# Production (without Ballerimon)  
bal run service.bal

Configuration Options

Use Cases

1. Web Service Development

Monitor your Ballerina HTTP service and restart automatically:

auto_reset:WatchConfig config = {
    projectPath: "./",
    ballerinaCmd: "bal run service.bal",
    verbose: true,
    debounceMs: 800
};

2. Multi-Module Projects

Watch specific modules or the entire project:

auto_reset:WatchConfig config = {
    projectPath: "./modules/core",
    watchExtensions: [".bal", ".toml"],
    ballerinaCmd: "bal build && bal run target/bin/myapp.jar"
};

3. Integration Testing

Monitor test files and run tests automatically:

auto_reset:WatchConfig config = {
    projectPath: "./tests",
    ballerinaCmd: "bal test",
    ignorePaths: ["target/", ".ballerina/"]
};

API Reference

Types

WatchConfig

Configuration record for the file watcher:

public type WatchConfig record {|
    string projectPath = "./";
    string[] watchExtensions = [".bal"];
    string[] ignorePaths = ["target/", ".ballerina/", "tests/"];
    int debounceMs = 500;
    string ballerinaCmd = "bal run";
    boolean verbose = false;
|};

Functions

startWithConfig(WatchConfig) returns error?

Start watching with a custom configuration.

createWatcher(WatchConfig) returns BallerinaWatcher

Create a watcher instance with custom configuration.

Classes

BallerinaWatcher

Main watcher class with the following methods:

• startWatching() returns error? - Start monitoring files
• stop() returns error? - Stop the watcher and cleanup

Examples

Example 1: Basic HTTP Service Watcher

// watcher.bal
import nalaka/auto_reset;

public function main() returns error? {
    auto_reset:WatchConfig config = {
        ballerinaCmd: "bal run http_service.bal",
        verbose: true
    };
    
    return auto_reset:startWithConfig(config);
}

Example 2: Custom Development Workflow

// dev-watcher.bal
import nalaka/auto_reset;
import ballerina/log;

public function main() returns error? {
    log:printInfo("Starting development watcher...");
    
    auto_reset:WatchConfig config = {
        projectPath: "./src",
        watchExtensions: [".bal", ".json", ".yaml"],
        ignorePaths: ["target/", ".ballerina/", "tests/", "docs/", "*.log"],
        debounceMs: 1000,
        ballerinaCmd: "bal build && bal run target/bin/myapp.jar --config=dev.yaml",
        verbose: true
    };
    
    auto_reset:BallerinaWatcher watcher = auto_reset:createWatcher(config);
    return watcher.startWatching();
}

Best Practices

1. Use Appropriate Debounce Time: Set debounceMs to a reasonable value (500-1000ms) to avoid excessive restarts during rapid file changes.

2. Ignore Build Artifacts: Always include build directories in ignorePaths to prevent infinite restart loops.

3. Specific Watch Extensions: Only watch file types that actually affect your application to reduce unnecessary restarts.

4. Environment-Specific Commands: Use different ballerinaCmd for development vs. production-like testing.

Troubleshooting

Common Issues

Q: The watcher keeps restarting infinitely A: Check your ignorePaths configuration. Make sure to ignore build directories like target/ and .ballerina/.

Q: Changes aren't being detected A: Verify that your file extensions are included in watchExtensions and the files aren't in ignored paths.

Q: The application doesn't start A: Check that your ballerinaCmd is correct and can be executed from the projectPath directory.

Q: Too many restarts happening A: Increase the debounceMs value to allow more time for multiple file changes to settle.

Debug Mode

Enable verbose logging to troubleshoot issues:

auto_reset:WatchConfig config = {
    verbose: true  // Enable detailed logging
};

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

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

Changelog

v0.1.0

• Initial release
• Basic file watching functionality
• Configurable watch patterns and ignore paths
• Auto-restart capability
• Verbose logging support

Support

If you encounter any issues or have questions:

1. Check the troubleshooting section above
2. Search existing issues in the repository
3. Create a new issue with detailed information about your problem

Happy coding with auto-restart! 🚀