jxabundler

[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![LinkedIn][linkedin-shield]][linkedin-url]

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:

``sh
npm install --dev jxabundler --save
`

2️⃣ Set up your package.json

`jsonc
{
"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:

`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:

`sh
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
* Automator Services - can be integrated in Menu, called with keyboard shortcuts
* 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.

$3

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:

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

$3

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

$3

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.

$3

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",
}
`

$3

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:

`json
{
"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.

$3

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)


$3

`
Usage
$ jxabundler [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, service, 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

nur bei Automator Type (-t service):
--NSApplicationIdentifier e.g. com.apple.Safari for Safari - will restrict this service to this app (default: all Programs)
--NSReturnTypes e.g. public.utf8-plain-text - result replaces selected text (default: off)
--NSSendTypes receives this type of content (default: none):
Text public.utf8-plain-text
Webcontent com.apple.webarchive
--NSIconName e.g. NSTouchBarAdd

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

`

$3

* 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 "./": "./".

$3

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.

$3

- [X] add type MacOS services

$3

- rollup.js
- microbundle
- osacompile

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

[contributors-shield]: https://img.shields.io/github/contributors/aheissenberger/repo.svg?style=for-the-badge
[contributors-url]: https://github.com/aheissenberger/macos-jxa-bundler/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/aheissenberger/repo.svg?style=for-the-badge
[forks-url]: https://github.com/aheissenberger/macos-jxa-bundler/network/members
[stars-shield]: https://img.shields.io/github/stars/aheissenberger/repo.svg?style=for-the-badge
[stars-url]: https://github.com/aheissenberger/macos-jxa-bundler/stargazers
[issues-shield]: https://img.shields.io/github/issues/aheissenberger/repo.svg?style=for-the-badge
[issues-url]: https://github.com/aheissenberger/macos-jxa-bundler/issues
[license-shield]: https://img.shields.io/github/license/aheissenberger/repo.svg?style=for-the-badge
[license-url]: https://github.com/aheissenberger/macos-jxa-bundler/blob/master/LICENSE.txt
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/andreasheissenberger