jxabundler

MacOS Javascript for Automation (JXA) bundler. Creates MacOS Apps, Commandline Scripts. Allows to use libaries from NPM.

Usage no npm install needed!

<script type="module">
  import jxabundler from 'https://cdn.skypack.dev/jxabundler';
</script>

README

Contributors Forks Stargazers Issues MIT License LinkedIn


MacOS JXA Bundler

MacOS JavaScript for Automation (JXA) bundler. Creates MacOS Apps, Commandline Scripts. Uses rollup to inline libaries from NPM.

Report Bug · Request Feature

Guide → Setup ✯ Create JXA App ✯ Formats ✯ Usage & Configuration ✯ Typescript ✯ All Options FAQ & Errors

✨ Features

  • One dependency to bundle your Application
  • Include your own libaries with "import"
  • Include libaries from NPM
  • Create real Mac Apps with File-Drop Support
  • Only include used functions (Treeshaking)

🔧 Installation & Setup

1️⃣ Install by running:

npm install --dev jxabundler --save

2️⃣ Set up your package.json

{
  "name": "foo", // name your applicationa
  "source": "src/foo.js", // your source code
  "main": "dist/foo.js", // where to generate the CommonJS/Node bundle
  "scripts": {
    "build": "jxabundler -t app", // compiles "source" to "foo.app"
    "dev": "jxabundler watch" // re-build when source files change
  }
}

3️⃣ Try it out

create a sample app src/foo.js:

const app = Application.currentApplication();
app.includeStandardAdditions = true;

function chooseFiles() {
  return app.chooseFile({
    withPrompt: "Please select some files to process:",
    //ofType: ["public.image"],
    multipleSelectionsAllowed: true,
  });
}

function getFilename(path) {
  return path.toString().split("/")?.[0]??'';
}

// run on App or Cmd start
export function run(argv) {
  if (argv?.length??0 === 0) {
    const files = chooseFiles();
    main(files);
  } else {
    const files = argv.map((filepath) => Path(filepath));
    main(files);
  }
}

// drag & drop as AppleScript App saved
export function openDocuments(docs) {
  main(docs);
}
const main = (files) => {
  const filelist = files.map(f=>getFilename(f)).join(', ');
  app.displayDialog("Filenames: " + filelist);
};

compile the app by runing npm run build

3️⃣ Run the App

Open folder dist and start the app foo.app with a double click.

Create JXA App

The easier way to setup a project is to use the Create JXA App:

npx create-jxa-app my-project

This will create a project folder my-project, jxabundler and an example app.

The default template is for MacOS Apps. If you plan to develop Command Line Scripts you can use npx create-jxa-app my-project --template command

Learn more Create JXA App

💽 Output Formats

JXA Bundler can create the following formats:

  • MacOS App - a real MacOS App with Drag & Drop Support
  • Command Line Script

📦 Usage & Configuration

JXA Bundler includes two commands - build (the default) and watch. Neither require any options, but you can tailor things to suit your needs a bit if you like.

ℹ️ JXA Bundler automatically determines which dependencies to inline into bundles based on your package.json.

Read more about How Microbundle decides which dependencies to bundle, including some example configurations.

jxabundler / jxabundler build

Unless overridden via the command line, jxabundler uses the source property in your package.json to locate the input file, and the main property for the output:

{
  "source": "src/index.js",      // input
  "main": "dist/my-library.js",  // output
  "scripts": {
    "build": "jxabundler"
  }
}

jxabundler watch

Acts just like jxabundler build, but watches your source files and rebuilds on any change.

Using with TypeScript

Just point the input to a .ts file through either the cli or the source key in your package.json and you’re done.

JXA Bundler will generally respect your TypeScript config defined in a tsconfig.json file with notable exceptions being the "target" and "module" settings. To ensure your TypeScript configuration matches the configuration that JXA Bundler uses internally it's strongly recommended that you set "module": "ESNext" and "target": "ESNext" in your tsconfig.json.

Specifying builds in package.json

JXA Bundler uses the fields from your package.json to figure out where it should place each generated bundle:

{
  "main": "dist/foo.js",            // CommonJS bundle
  "source": "src/foo.js",
}

Mangling Properties

To achieve the smallest possible bundle size, libraries often wish to rename internal object properties or class members to smaller names - transforming this._internalIdValue to this._i. JXA Bundler doesn't do this by default, however it can be enabled by creating a mangle.json file (or a "mangle" property in your package.json). Within that file, you can specify a regular expression pattern to control which properties should be mangled. For example: to mangle all property names beginning an underscore:

{
    "mangle": {
        "regex": "^_"
    }
}

It's also possible to configure repeatable short names for each mangled property, so that every build of your library has the same output. See the wiki for a complete guide to property mangling in Microbundle.

Defining build-time constants

The --define option can be used to inject or replace build-time constants when bundling. In addition to injecting string or number constants, prefixing the define name with @ allows injecting JavaScript expressions.

Build command Source code Output
jxabundler --define VERSION=2 console.log(VERSION) console.log(2)
jxabundler --define API_KEY='abc123' console.log(API_KEY) console.log("abc123")
jxabundler --define @assign=Object.assign assign(a, b) Object.assign(a, b)
### All CLI Options 
  Usage
    $ jxabundler <command> [options]

  Available Commands
    build    Build once and exit
    watch    Rebuilds on any change

  For more info, run any command with the `--help` flag
    $ jxabundler build --help
    $ jxabundler watch --help

  Options
    -i, --entry      Entry module(s)
    -o, --output     Directory to place build files into (default build)
    -t, --type       Specify your type (app, cmd)  (default cmd)
    -w, --watch      Rebuilds on any change  (default false)
    --define         Replace constants with hard-coded values
    --alias          Map imports to different modules
    --compress       Compress output using Terser
    --strict         Enforce undefined global context and add "use strict"
    --cwd            Use an alternative working directory  (default .)
    --sourcemap      Generate source map
    --tsconfig       Specify the path to a custom tsconfig.json
    -v, --version    Displays current version
    -h, --help       Displays this message

  Examples
    $ jxabundler build -i src/index.js -o build/MyApp.app -t app --no-sourcemap --compress
    $ jxabundler watch -i src/index.js -o build/MyApp.app -t app

FAQ

  • Error Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './package.json' is not defined by "exports" in /Users/ah/SVN-Checkouts/AH/awsExportTransactions/node_modules/tslib/package.json This is a problem with the package tslib you currently can only fix this with changing in node_modules/tslib/package.json in the section "exports" the entry "./": "./" to "./*": "./*".

Typescript

You can use typescript without any configuration. But you will have to deal with global functions (e.g. Ref()) which can be uses without beeing imported.

Roadmap

  • add type MacOS services

Built With

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the bsd-2-clause License. See LICENSE for more information.

Contact

Your Name - @aheissenberger - andreas@heissenberger.at

Project Link: https://github.com/aheissenberger/macos-jxa-bundler