binarium

Binarium

Easy-to-use, zero-configuration tool to create executables of your Node, Deno or Bun projects for all platforms and architectures.

The construction of the binary allows compilation on arm64 and x64 architecture.

If you compile on an x64 system it will not create the binaries for arm, but if you compile on arm it will create the binaries for both architectures.

Index

• 🌟 Features
• 🔑 Installation
• ⚙️ Options
• 📈 usage
  • 📦 JS
  • 🟢 Node
  • 🦕 Deno
  • 🍞 Bun
  • 💻 CLI
  • 🛠️ With config file - advanced configuration
    • Node Example
    • Deno Example
    • Bun Example
  • 🤖 Github Action
    • Inputs
    • Examples
      • Build only linux executables
      • Build for all platforms and archs and upload to releases
• 👨‍💻 Development
• ☕ Donate
• 📜 License
• 🐦 About us
  • Collaborators

🌟 Features

• ⚡ Fast: Optimized for quick execution and minimal overhead.
• 🚀 Easy to Use: Simple setup with minimal configuration required.
• 🛠️ Advanced Configuration: Customize to fit your project's exact needs.
• 🌍 Available for:
  • 🟢 Node.js
  • 🦕 Deno
  • 🍞 Bun
• 🌐 Supports Multiple Environments:
  • 📦 JavaScript Library: Integrates seamlessly into any project.
  • 💻 Command Line Interface (CLI): Works across Node.js, Deno, and Bun environments.
  • 🤖 GitHub Action: Easily incorporate it into CI/CD pipelines with GitHub Actions support.

🔑 Installation

# npm
npm install binarium
# pnpm
pnpm add binarium
# yarn
yarn add binarium
# bun
bun add binarium
# deno
deno install binarium

⚙️ Options

All of these options are available with the binarium command by adding the suffix -- and followed by an = or space and its value.

For more info execute:

binarium --help

type BuilderParams = {
 /**
  * The app server input file.
  *
  * The input can be provided without an extension.
  * If the extension is omitted, the system will automatically look for the following extensions: `.ts`, `.js`, `.mjs`, `.mts`.
  */
 input: string,
 /**
  * Binary name.
  */
 name?: string,
 /**
  * Directory for the output build.
  *
  * @default './build'
  */
 output?: string,
 /**
  * Build only binary for your current OS.
  *
  * @default false
  */
 onlyOs?: boolean
 /**
  * The build type Result [all|bundle|bin|compress].
  *
  * @default 'all'
  */
 type?: 'all'|'bundle'|'bin'|'compress'
  /**
  * Config file path.
  *
  * @default undefined
  */
 config?: string
}

📈 usage

Below is a sample of the many ways to run binarium.

📦 JS

Quickly compile your JS project into executables for all platforms and architectures

Automatically detects the JS runtime you are working in. Only accepts node, deno, bun

import { build } from 'binarium'

await build( {
 input  : 'src/cli.js', // JS or TS file. You can add it without the extension
 name   : 'app-name', // default is input filename
} )

🟢 Node

Quickly compile your Node project into executables for all platforms and architectures

import { buildNode } from 'binarium'

await buildNode( {
 input  : 'src/cli', // JS or TS file. You can add it without the extension
 name   : 'app-name', // default is input filename
} )

This function works thanks to ncc, pkg and esbuild, which facilitate this process.

Alternatively, if you are working in a node environment, you can do:

import { build } from 'binarium'

await build( {
 input  : 'src/cli', // JS or TS file. You can add it without the extension
 name   : 'app-name', // default is input filename
} )

🦕 Deno

Build Deno executables (deno compile wrapper)

import { buildDeno } from 'binarium'

await buildDeno( {
 input  : 'src/cli', // JS or TS file. You can add it without the extension
 name   : 'app-name', // default is input filename
} )

🍞 Bun

Build Bun executables (bun build --compile wrapper)

import { buildBun } from 'binarium'

await buildBun( {
 input  : 'src/cli', // JS or TS file. You can add it without the extension
 name   : 'app-name', // default is input filename
} )

💻 CLI

Use it from Cli.

binarium --input src/server.js --name app-name

binarium node --input src/node-server.js --name node-app-name

binarium deno --input src/deno-server.js --name deno-app-name

binarium bun --input src/bun-server.js --name bun-app-name

🛠️ With config file - advanced configuration

For more advanced configuration you can use a configuration file. Supported formats are: .mjs, .js, .json, .yml, .yaml, .toml, .tml.

In the configuration file you can define your build options and configure advanced options of the build itself using the nodeOptions|denoOptions|bunOptions key.

Node Example

binarium node --config binarium.config.js

// binarium.config.js
import { defineConfig } from 'binarium'

export default defineConfig( {
 name    : 'my-app-name',
 onlyOs  : true,
 nodeOptions : { esbuild: { tsconfig: './tsconfig.builder.json' } },
} )

Deno Example

binarium deno -c binarium.config.js

// binarium.config.js
import { defineConfig } from 'binarium'

export default defineConfig( {
 name    : 'my-app-name',
 onlyOs  : true,
 denoOptions : { flags: [ '--allow-all', '--no-npm' ] },
} )

Bun Example

binarium bun -c binarium.config.js

// binarium.config.js
import { defineConfig } from 'binarium'

export default defineConfig( {
 name    : 'my-app-name',
 onlyOs  : true,
 bunOptions : { flags: [ '--packages external' ] },
} )

🤖 Github Action

Inputs

The action accepts the following inputs:

• build (optional): Specifies the execution environment. Acceptable values are: node, deno, bun. The default is node.

• config (optional): Path to the configuration file. The default is ./binarium.config.json. Make sure that the specified configuration file exists and is correctly configured.

Examples

Here is an example of how to set it up:

Build only linux executables

name: Build Executable for linux

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20
      - name: Run BINARIUM Action
        uses: pigeonposse/binarium@v1
        with:
          build: 'node'
          config: '.dev/binarium.config.yml'

# .dev/binarium.config.yml
name: my-app
onlyOs: true
input: src/app.ts
assets:
  - from: src/assets/**
    to: public

Build for all platforms and archs and upload to releases

name: Build Executables and upload

on:
  workflow_dispatch:
jobs:
  build:
    runs-on: macos-14 # Because it's an arm64. SEE: https://github.com/actions/runner-images?tab=readme-ov-file#available-images
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 20
      - name: Run BINARIUM Action
        uses: pigeonposse/binarium@v1
        with:
          build: 'node'
          config: './binarium.config.yml' # Where is our config file
      - name: Release binaries
        uses: ncipollo/release-action@v1
        with:
          tag: "Releases"
          draft: false
          prerelease: false
          allowUpdates: true
          artifacts: "build/compress/*" # Default build folder
          omitBodyDuringUpdate: true

# ./binarium.config.yml
name: my-app
input: src/app.ts

👨‍💻 Development

binarium is an open-source project and its development is open to anyone who wants to participate.

☕ Donate

Help us to develop more interesting things.

📜 License

This software is licensed with GPL-3.0.

🐦 About us

PigeonPosse is a ✨ code development collective ✨ focused on creating practical and interesting tools that help developers and users enjoy a more agile and comfortable experience. Our projects cover various programming sectors and we do not have a thematic limitation in terms of projects.

Collaborators

	Name	Role	GitHub
	Angelo	Author & Development	@Angelo
	PigeonPosse	Collective	@PigeonPosse