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