npm-jar-wrapper-maker

Create NPM wrappers for Java JARs with automatic JRE management.

This tool generates NPM packages that wrap Java JAR files, allowing them to be distributed and run via npm install without requiring users to manually install Java. If Java is not found on the system, the wrapper will automatically download and cache a JRE from Adoptium.

Installation

npm install -g npm-jar-wrapper-maker

Or as a dev dependency in your Java project:

npm install --save-dev npm-jar-wrapper-maker

Usage

CLI Usage

Initialize a Configuration File

npm-jar-wrapper-maker --init

This creates a wrapper-config.json file that you can customize.

Generate from Configuration File

npm-jar-wrapper-maker --config wrapper-config.json --output ./npm-package

Generate with Inline Options

npm-jar-wrapper-maker \
  --package-name @myorg/my-cli \
  --cli-name my-cli \
  --jar-file-name my-app.jar \
  --java-version 17 \
  --output ./npm-package

Programmatic Usage

const { generateWrapper, validateConfig } = require('npm-jar-wrapper-maker');

const config = {
  packageName: '@myorg/my-cli',
  version: '1.0.0',
  description: 'My Java CLI tool',
  cliName: 'my-cli',
  jarFileName: 'my-app.jar',
  targetJavaVersion: 17,
  author: 'Your Name',
  license: 'Apache-2.0',
};

// Validate configuration
const validation = validateConfig(config);
if (!validation.valid) {
  console.error('Invalid config:', validation.errors);
  process.exit(1);
}

// Generate the wrapper
const result = generateWrapper(config, './output-dir');

console.log('Generated files:', result.files);
console.log('Copy your JAR to:', result.jarPlaceholder);

Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | packageName | string | Yes | - | NPM package name (e.g., @myorg/my-cli) | | cliName | string | Yes | - | CLI command name (e.g., my-cli) | | jarFileName | string | Yes | - | JAR file name (e.g., my-app.jar) | | version | string | No | 1.0.0 | Package version | | description | string | No | "" | Package description | | author | string | No | "" | Package author | | license | string | No | Apache-2.0 | Package license | | targetJavaVersion | number | No | 17 | Target Java version (8+) | | javaOpts | string[] | No | [] | Additional JVM options | | enableNativeAccess | boolean | No | false | Enable Java native access | | enablePostinstall | boolean | No | false | Enable postinstall script | | postinstallCommand | string | No | "" | Custom postinstall command | | configDirName | string | No | Same as cliName | Config directory name for JRE cache | | repository | object | No | {} | Repository info for package.json | | homepage | string | No | "" | Homepage URL | | bugs | object | No | {} | Bugs URL | | keywords | string[] | No | [] | Additional keywords |

Generated Files

The generator creates the following files:

• package.json - NPM package manifest
• index.js - CLI entry point (with shebang)
• cli.js - Java runtime management and execution logic
• .gitignore - Git ignore rules
• .npmignore - NPM ignore rules
• README.md - Basic documentation
• postinstall.js - (optional) Post-install hook

How the Generated Wrapper Works

1. When the CLI is executed, it first looks for Java:

   • Checks JAVA_HOME environment variable
   • Checks for java on the system PATH
   • Checks for a previously downloaded JRE in ~/.config/<cli-name>/jre

2. If no Java is found, it automatically:

   • Fetches JRE metadata from Adoptium API
   • Downloads the appropriate JRE for the user's platform and architecture
   • Verifies the download checksum
   • Extracts and caches the JRE locally

3. Executes the JAR file with the found/downloaded Java

Integration with Gradle/Maven

You can integrate this tool into your Java build process. For example, in a Gradle project:

// build.gradle
task generateNpmWrapper(type: Exec) {
    dependsOn bootJar

    commandLine 'npx', 'npm-jar-wrapper-maker',
        '--package-name', '@myorg/my-cli',
        '--cli-name', 'my-cli',
        '--jar-file-name', 'my-cli.jar',
        '--output', "${buildDir}/npm-wrapper"

    doLast {
        copy {
            from bootJar.archiveFile
            into "${buildDir}/npm-wrapper"
            rename { 'my-cli.jar' }
        }
    }
}

Or with a configuration file:

task generateNpmWrapper(type: Exec) {
    dependsOn bootJar

    commandLine 'npx', 'npm-jar-wrapper-maker',
        '--config', 'npm-wrapper-config.json',
        '--output', "${buildDir}/npm-wrapper"

    doLast {
        copy {
            from bootJar.archiveFile
            into "${buildDir}/npm-wrapper"
            rename { 'my-cli.jar' }
        }
    }
}

Security Features

The generated wrapper includes several security measures:

• Checksum verification: Downloaded JREs are verified against SHA256 checksums from Adoptium
• Path traversal protection: Archive extraction rejects paths that could escape the target directory (CVE-2020-12265 mitigation)
• HTTPS only: All downloads use HTTPS

Supported Platforms

The generated wrappers support:

• macOS (Intel and Apple Silicon)
• Linux (x64 and ARM64)
• Windows (x64)

License

Apache-2.0