DOCSEARCHbyAlgolia
Submit Docs

Astra CLI Documentation

repository·main·Indexed 19 days ago

https://github.com/astracompiler/cli

A high-performance JavaScript-to-executable compiler for creating standalone binaries for Node.js applications, such as servers and CLIs. It uses esbuild for fast compilation and provides native support for TypeScript and ESM. Currently, Astra supports compiling Windows applications and allows for metadata customization of the resulting binaries.

Tokens
997
Snippets
4
Records
5
Agent score
17%

What's inside astra-cli

  1. Overview of Astra features and capabilities

    main

    Astra is a fast, reliable js-to-exe compiler designed primarily for compiling servers (like Express or Fastify) and CLIs (like Commander).

    Key Features:

    • Standalone Executables: Generates a single .exe or binary file including all dependencies.
    • Modern Node.js Support: Supports the latest Node.js versions (up to Node 24).
    • ESM Support: Improved support for ECMAScript Modules (ESM) with workarounds for Node.js SEA limitations.
    • TypeScript Support: Native support for TypeScript.
    • Metadata Customization: Ability to modify executable metadata such as icon, name, and version.
    • Fast Builds: Powered by esbuild for high-speed compilation.
    • Small Footprint: Average executable size is ~70-80MB, which can be reduced to ~30MB using upx.

    Note: Currently, Astra only compiles Windows applications. macOS and Linux support are planned for future releases.

  2. Compile a JavaScript or TypeScript project with Astra

    main

    Once installed, you can compile your project into a standalone executable using the astra build command. Astra bundles your code using esbuild and generates a single binary file that includes all dependencies.

    To compile a project, provide the entry point file (e.g., src/index.js or a TypeScript file) to the build command.

    To see all available options and flags, run:

    astra --help
    astra build src/index.js

  3. Install Astra CLI

    main

    You can install Astra globally to use it as a system-wide command, or install it as a development dependency for a specific project.

    Global Installation

    Use one of the following commands depending on your package manager:

    # npm
npm i -g astra-cli

# yarn (classic)
yarn global add astra-cli

# pnpm
pnpm add -g astra-cli

    Project-specific Installation

    To install Astra only for a single project, use these commands:

    # npm
npm i --save-dev astra-cli

# yarn
yarn add --dev astra-cli

# pnpm
pnpm add -D astra-cli
    npm i -g astra-cli

  4. Use the inject function from postject

    main

    The inject function is used to inject a resource (as a Buffer) into a binary file. It returns a Promise<void> that resolves when the injection is complete.

    Parameters:

    • filename: The path to the target binary file.
    • resourceName: The name of the resource being injected.
    • resourceData: The data to be injected, provided as a Buffer.
    • options (optional): An object of type InjectOptions to configure the injection process.
    import { inject } from 'postject';

await inject('path/to/binary', 'my-resource', Buffer.from('data'), {
  overwrite: true,
  quiet: false
});

  5. Configure postject injection options

    main

    When calling inject, you can provide an InjectOptions object to customize the injection behavior.

    OptionTypeDefaultDescription
    machoSegmentNamestring'__POSTJECT'The name of the Mach-O segment used for injection.
    overwritebooleanfalseWhether to overwrite existing data.
    sentinelFusestring'POSTJECT_SENTINEL_fce680ab2cc467b6e072b8b5df1996b2'The sentinel string used to identify the injected data.
    quietbooleanfalseIf true, suppresses output during the injection process.
    export interface InjectOptions {
	/**
	 * @default '__POSTJECT'
	 */
	machoSegmentName?: string;
	/**
	 * @default false
	 */
	overwrite?: boolean;
	/**
	 * @default "POSTJECT_SENTINEL_fce680ab2cc467b6e072b8b5df1996b2"
	 */
	sentinelFuse?: string;
	/**
	 * @default false
	 */
	quiet?: boolean;
}