Quick JBang Scripting with IntelliJ IDEA: Development & Debugging Guide

One of the biggest advantages of JBang is that you don't give up rich IDE features like code auto-completion, refactoring, syntax highlighting, and interactive debugging when writing single-file Java scripts. IntelliJ IDEA offers outstanding support for JBang, making script development feel just as powerful as building a full enterprise application.

1. Method 1: Zero-Install Script Editing (`jbang edit`)

If you don't want to install extra IDE plugins, JBang provides a built-in CLI command that automatically converts your standalone script into a temporary, fully configured IntelliJ project on the fly.

Step 1: Create Your JBang Script

Generate a new sample script using Java 21 and the Jackson JSON parser:

$ jbang init ApiScript.java

Edit ApiScript.java to include your dependencies:

///usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 21
//DEPS com.fasterxml.jackson.core:jackson-databind:2.18.2

import com.fasterxml.jackson.databind.ObjectMapper;

public class ApiScript {

    public static void main(String... args) throws Exception {
        var mapper = new ObjectMapper();
        var user = mapper.createObjectNode()
                .put("name", "Frank")
                .put("role", "Middleware Engineer");

        System.out.println("JSON Output: " + mapper.writerWithDefaultPrettyPrinter().writeValueAsString(user));
    }
}

Step 2: Open in IntelliJ IDEA with `jbang edit`

Run the following command in your terminal:

$ jbang edit --open=idea ApiScript.java

What Happens Behind the Scenes:

1. JBang inspects ApiScript.java and resolves all dependencies specified in //DEPS from Maven Central.
2. It creates a temporary IDEA project structure in ~/.jbang/edited/.
3. IntelliJ IDEA opens automatically with full JDK indexing, code completion, and library resolution ready to go!

2. Method 2: Using the Official JBang IntelliJ Plugin

For developers who frequently write JBang scripts, installing the official plugin provides a seamless native experience directly inside your primary workspace.

Installing the Plugin:

1. Open IntelliJ IDEA and navigate to Settings / Preferences | Plugins.
2. Select the Marketplace tab and search for JBang.
3. Click Install and restart the IDE.

Key Features Offered by the Plugin:

• New JBang File Wizard: Right-click any directory and select New -> JBang Script to generate pre-formatted templates.
• Inline Gutter Run Buttons: Execute or debug JBang scripts with a single click next to the main method line.
• Live Templates: Type //DEPS or //JAVA to get smart code completion for Maven artifact IDs and JDK versions.

3. How to Debug JBang Scripts in IntelliJ IDEA

Debugging a single-file JBang script in IntelliJ IDEA is just as straightforward as debugging a standard Java application.

Option A: Debugging via CLI Remote Attachment

If you prefer running your scripts from the terminal but want to attach IntelliJ's debugger to inspect variables and set breakpoints:

1. Launch your script in debug mode:

$ jbang --debug ApiScript.java

JBang will pause execution and output: Listening for transport dt_socket at address: 4004.

2. Attach IntelliJ IDEA Debugger:

1. In IntelliJ IDEA, go to Run | Edit Configurations...
2. Click + and select Remote JVM Debug.
3. Set the port to 4004 and click Debug. IntelliJ will instantly connect to your running JBang script!

Option B: Native IDE Debugging (via JBang Plugin or `jbang edit`)

When running inside a project created by jbang edit or managed by the JBang plugin:

1. Set a breakpoint on any line of code by clicking the gutter margin.
2. Right-click inside the editor window and select Debug 'ApiScript.main()'.

4. Comparison of IntelliJ IDEA Workflow Methods

Frequently Asked Questions (FAQs)

Q1: Does editing a script via `jbang edit` modify my original file?

Yes. Although JBang generates a temporary project wrapper to satisfy IntelliJ's indexing requirements, the Java file inside the editor is a direct symlink/reference to your original source script.

Q2: Why does IntelliJ show red unresolved class warnings for my `//DEPS`?

If you open a JBang script directly as a raw file without using jbang edit or the JBang plugin, IntelliJ treats it as an unmanaged Java file. Always use jbang edit --open=idea Script.java or the plugin so JBang can download and expose the external JAR dependencies to IntelliJ's module classpath.

Q3: Can I use Java 21 virtual threads in JBang scripts inside IntelliJ?

Yes! Simply declare //JAVA 21 at the top of your script. JBang will instruct IntelliJ to set the project SDK and language level to Java 21 automatically.

Conclusion

Combining JBang with IntelliJ IDEA gives you the best of both worlds: the lightning-fast, zero-overhead execution of single-file scripting paired with the world-class refactoring, code completion, and debugging features of JetBrains' leading IDE.