### Complete Build Workflow Example

Source: https://context7.com/astracompiler/cli/llms.txt

Demonstrates a full end-to-end build process using Astra CLI, including configuration, compilation, metadata modification, asset bundling, and optional compression. The example shows how to create a standalone Windows executable that runs without a separate Node.js installation.

```javascript
// Step 1: Create astra.config.js
export default {
  outFile: "dist/myserver.exe",
  esbuild: {
    minify: true,
    target: "node20",
    external: ["better-sqlite3"]
  },
  modifyMetadata: true,
  exe: {
    companyName: "My Startup",
    productName: "API Server",
    fileDescription: "RESTful API Server",
    productVersion: "1.0.0",
    fileVersion: "1.0.0.0",
    icon: "assets/server.ico",
    copyright: "© 2024 My Startup"
  }
};

// Step 2: Run build command
// $ astra build src/server.js
// Astra will:
// [1/4] Bundle code with esbuild (ESM → CJS)
// [2/4] Edit metadata (icon, version, copyright)
// [3/4] Generate SEA blob with assets
// [4/4] Inject blob into node.exe copy
// ✓ Output: dist/myserver.exe (~75MB)

// Step 3: Compress with UPX (optional)
// $ upx --best dist/myserver.exe
// Compressed to ~30MB

// Step 4: Distribute
// Single .exe file - no dependencies required
// Runs on Windows without Node.js installation
```

--------------------------------

### Install Command: Pre-download Node.js Versions

Source: https://context7.com/astracompiler/cli/llms.txt

Downloads and caches Node.js binaries locally for offline compilation or faster subsequent builds. Supports interactive version selection, specific version installation, and LTS version installation. The version format is node_v{version}-{platform}-{architecture}.

```bash
# Install with interactive version selector
astra install

# Install specific version
astra install node_v22.15.1-win-x64

# Install LTS version
astra install node_v20.18.3-win-x64

# Version format: node_v{version}-{platform}-{architecture}
# Platforms: win, linux, macos
# Architectures: x64, x86, arm64
# Stored in: ~/.astra/versions/
```

--------------------------------

### Init Command: Initialize Project Configuration

Source: https://context7.com/astracompiler/cli/llms.txt

Creates a default `astra.config.js` configuration file in the current directory. This file contains all available options and examples for customizing the build process.

```bash
# Create config file
astra init

# Creates: astra.config.js
# Contains: output settings, esbuild config, metadata options, assets
```

--------------------------------

### Install Astra CLI (npm, yarn, pnpm)

Source: https://github.com/astracompiler/cli/blob/main/README.md

Instructions for installing the Astra CLI globally or as a development dependency using npm, yarn, or pnpm.

```bash
# npm 
npm i -g astra-cli
# yarn (classic)
yarn global add astra-cli
# pnpm
pnpm add -g astra-cli

# for one project only
# npm
npm i --save-dev astra-cli
# yarn
yarn add --dev astra-cli
# pnpm
pnpm add -D astra-cli
```

--------------------------------

### Compile Express.js Server to Executable (JavaScript)

Source: https://context7.com/astracompiler/cli/llms.txt

This example demonstrates compiling an Express.js web server into a standalone executable using the Astra CLI. It shows basic compilation and advanced configuration with astra.config.js, including bundling, metadata, and icons. The resulting executable runs without a separate Node.js installation.

```javascript
// server.js - Express server
import express from 'express';
import path from 'path';

const app = express();
const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.json({ message: 'Hello from compiled server!' });
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

// Compile command:
// $ astra build server.js -o dist -n node_v22.15.1-win-x64

// Result: dist/build.exe
// Run: ./dist/build.exe
// Server starts without Node.js installed

// With configuration file:
// astra.config.js
export default {
  outFile: "dist/api-server.exe",
  esbuild: {
    minify: true,
    external: [] // Bundle everything
  },
  exe: {
    companyName: "My Company",
    productName: "API Server",
    fileDescription: "RESTful API Server v1.0",
    icon: "server.ico"
  }
};

// Compile: $ astra build server.js
// Run: $ dist/api-server.exe
```

--------------------------------

### Programmatic Install Function - astra-cli

Source: https://context7.com/astracompiler/cli/llms.txt

Downloads Node.js binaries programmatically with progress tracking and SHA256 verification. It validates version formats and downloads to a specific cache directory. Internet connection is required.

```typescript
import install from 'astra-cli/src/install.ts';

// Example: Install specific Node version
await install({
  ver: 'node_v22.15.1-win-x64'
});

// Example: Install with error handling
try {
  await install({ ver: 'node_v20.18.3-win-arm64' });
  console.log('Installation successful');
} catch (error) {
  if (error.code === 'ENOTFOUND') {
    console.error('No internet connection');
  }
}

// Version format validation:
const regex = /^node_v(\d+\.\d+\.\d+)-([a-z]+)-(x86|x64|arm64)$/;
const version = 'node_v22.15.1-win-x64';
if (!regex.test(version)) {
  throw new Error('Invalid version format');
}
```

--------------------------------

### Cache Management Helper - astra-cli

Source: https://context7.com/astracompiler/cli/llms.txt

Provides persistent file-based caching for GitHub API responses and Node.js version management. It includes functions to list installed versions, check installation status, get version paths, and a Keyv cache for custom data. Caches are stored in '~/.astra/'.

```typescript
import {
  cache,
  listOfAvailableVersions,
  isVersionInstalled,
  getVersionPath
} from 'astra-cli/src/helpers/cache.ts';

// List all locally installed Node versions
const versions = listOfAvailableVersions();
console.log(versions);
// Output: ['node_v22.15.1-win-x64.exe', 'node_v20.18.3-win-x64-lts.exe']

// Check if version is installed
const installed = isVersionInstalled('node_v22.15.1-win-x64.exe');
console.log(installed); // true or false

// Get absolute path to version
const versionPath = getVersionPath('node_v22.15.1-win-x64.exe');
console.log(versionPath);
// Output: /home/user/.astra/versions/node_v22.15.1-win-x64.exe

// Use Keyv cache for custom data
await cache.set('my-key', { data: 'value' });
const value = await cache.get('my-key');
console.log(value); // { data: 'value' }

// Cache configuration:
// - Location: ~/.astra/cache.json
// - Write delay: 100ms
// - Expired check: 1 hour
// - Automatic serialization/deserialization
```

--------------------------------

### Compile Commander.js CLI Tool to Executable (TypeScript)

Source: https://context7.com/astracompiler/cli/llms.txt

This example shows how to compile a Commander.js command-line interface tool written in TypeScript into a distributable executable. The Astra CLI handles the compilation, resulting in a single `.exe` file that can be distributed without external Node.js dependencies. This simplifies the deployment of CLI tools.

```typescript
// cli.ts - Commander CLI tool
import { Command } from 'commander';
import chalk from 'chalk';

const program = new Command();

program
  .name('mytool')
  .description('My awesome CLI tool')
  .version('1.0.0');

program
  .command('greet <name>')
  .description('Greet a user')
  .action((name) => {
    console.log(chalk.green(`Hello, ${name}!`));
  });

program.parse();

// Compile:
// $ astra build cli.ts --noMetadata

// Result: dist/build.exe
// Distribute: Single .exe file
// Usage: mytool.exe greet John
```

--------------------------------

### Compile TypeScript ESM to Executable with Assets (TypeScript)

Source: https://context7.com/astracompiler/cli/llms.txt

This example demonstrates compiling a TypeScript application using ECMAScript Modules (ESM) into an executable. Astra CLI automatically converts ESM to CommonJS for compatibility with the Standalone Executable Application (SEA) format. It also shows how to include external assets, like a `config.json` file, directly within the executable bundle.

```typescript
// app.ts - ESM TypeScript
import { readFile } from 'fs/promises';
import { join } from 'path';

async function main() {
  const data = await readFile(join(process.cwd(), 'config.json'), 'utf-8');
  const config = JSON.parse(data);
  console.log('Config loaded:', config);
}

main().catch(console.error);

// astra.config.js
export default {
  outFile: "dist/app.exe",
  esbuild: {
    format: "cjs",         // Astra converts ESM → CJS automatically
    minify: true,
    target: "node20"
  },
  assets: {
    "config.json": "./config.json"  // Include config in blob
  }
};

// Compile: $ astra build app.ts
// ESM is automatically converted to CommonJS for SEA compatibility
```

--------------------------------

### Detect Wine Installation

Source: https://context7.com/astracompiler/cli/llms.txt

Detects the presence of Wine on non-Windows systems, which is necessary for editing Windows executable metadata. It executes the 'wine --version' command and returns true if successful. This function is crucial for conditionally applying metadata edits.

```typescript
import isWineInstalled from 'astra-cli/src/helpers/iswineinstalled.ts';
import { canRunWindowsExeNatively } from 'cross-spawn-windows-exe';

// Check Wine availability
const wineAvailable = isWineInstalled();

if (wineAvailable) {
  console.log('Wine is installed - can edit .exe metadata');
} else {
  console.log('Wine not found - skipping metadata');
}

// Use case: Conditional metadata editing
const canEditMetadata = isWineInstalled() || canRunWindowsExeNatively();

if (!canEditMetadata) {
  console.log('Install Wine from: https://www.winehq.org/');
  console.log('Or use --noMetadata flag');
}
```

--------------------------------

### Versions Command: List Available Node.js Releases

Source: https://context7.com/astracompiler/cli/llms.txt

Displays all available Node.js versions from the Astra binaries repository. The output includes version number, platform, architecture, and LTS status, with color-coding for platforms and LTS status.

```bash
# Show all available versions
astra versions

# Example output:
# Available Node.js versions:
# 22.15.1 win x64 LTS
# 22.15.1 linux x64 LTS
# 22.14.0 win x64
# 21.7.3 macos arm64
# (Colors: Windows=blue, Linux=green, macOS=magenta, LTS=green)
```

--------------------------------

### Configuration File: Complete Build Customization

Source: https://context7.com/astracompiler/cli/llms.txt

Provides a comprehensive schema for customizing the Astra CLI build process. Allows configuration of output file path, esbuild options (minification, target, platform, external dependencies, defines, loaders), metadata modification, assets to include, and Windows executable metadata (company name, product name, file description, versions, icon, copyright).

```javascript
// astra.config.js
export default {
  // Output configuration
  outFile: "dist/myapp.exe",           // Specific output file path
  outDir: "dist",                       // Output directory (default)

  // esbuild bundler options
  esbuild: {
    minify: true,                       // Minify output (default: true)
    target: "node20",                   // Compilation target
    platform: "node",                   // Platform (always node)
    external: ["fsevents"],             // External dependencies
    define: {                           // Define constants
      "process.env.NODE_ENV": '"production"'
    },
    loader: {                           // File loaders
      ".png": "file",
      ".jpg": "dataurl"
    }
    // All esbuild options supported: https://esbuild.github.io/api/
  },

  // Metadata editing control
  modifyMetadata: true,                 // Enable/disable metadata (requires Wine on non-Windows)

  // Assets to include in SEA blob
  assets: {
    "config.json": "./config.json",
    "templates/": "./templates/"
  },

  // Windows executable metadata
  exe: {
    companyName: "Acme Corporation",
    productName: "My Application",
    fileDescription: "Enterprise Node.js Application",
    productVersion: "2.1.0",
    fileVersion: "2.1.0.0",              // Must be X.X.X.X format
    icon: "assets/app.ico",              // Must be .ico format
    copyright: "Copyright © 2024 Acme Corporation"
  }
};
```

--------------------------------

### Display Astra CLI Help

Source: https://github.com/astracompiler/cli/blob/main/README.md

Command to display the help information and available options for the Astra CLI.

```bash
astra --help
```

--------------------------------

### Configuration Loader Helper - astra-cli

Source: https://context7.com/astracompiler/cli/llms.txt

Loads project configuration files using cosmiconfig, supporting multiple formats like '.js', '.cjs', and '.mjs'. It searches for 'astra.config.*' files in the project directory. Provides access to project-specific settings like output files and build configurations.

```typescript
import getConfig from 'astra-cli/src/helpers/configloader.ts';

// Load configuration (searches for astra.config.*)
const config = await getConfig();

if (config) {
  console.log('Output file:', config.outFile);
  console.log('Company:', config.exe?.companyName);
  console.log('Esbuild config:', config.esbuild);
} else {
  console.log('No config file found');
}

// Searches for (in order):
// 1. astra.config.js
// 2. astra.config.cjs
// 3. astra.config.mjs

// Example: Use config in build script
const config = await getConfig();
const outputPath = config?.outFile || 'dist/build.exe';
const iconPath = config?.exe?.icon || undefined;
```

--------------------------------

### Programmatic Build Function - astra-cli

Source: https://context7.com/astracompiler/cli/llms.txt

Builds server applications programmatically from TypeScript/JavaScript code. It validates entry points, Node versions, and optionally checks icon files and wine availability. Dependencies include astra-cli.

```typescript
import build from 'astra-cli/src/build.ts';

// Example: Build server application programmatically
await build({
  entry: 'src/server.ts',              // Entry point file
  outDir: 'dist',                      // Output directory
  node: 'node_v22.15.1-win-x64',       // Node version (Astra format)
  disShasumCheck: false,               // Enable SHA256 verification
  noMetadata: false                    // Enable metadata editing
});

// Example: Error handling with validation
try {
  await build({
    entry: 'src/app.js',
    outDir: 'build',
    node: 'node_v20.18.3-win-x64',
    disShasumCheck: true,              // Skip checksum for speed
    noMetadata: false
  });
  console.log('Build completed successfully!');
} catch (error) {
  console.error('Build failed:', error.message);
  process.exit(1);
}
```

--------------------------------

### Compile Project with Astra CLI

Source: https://github.com/astracompiler/cli/blob/main/README.md

Command to compile a JavaScript/TypeScript project using the Astra CLI. Assumes the entry point is src/index.js.

```bash
astra build src/index.js
```

--------------------------------

### Build Command: Compile JS/TS to EXE

Source: https://context7.com/astracompiler/cli/llms.txt

Compiles JavaScript or TypeScript entry files into standalone Windows executables. Supports automatic bundling, metadata injection, and SEA integration. Options include specifying output directory, Node.js version, disabling metadata, skipping integrity checks, and using a configuration file.

```bash
# Basic compilation with interactive prompts
astra build src/index.js

# Full compilation with all options specified
astra build src/server.ts -o dist -n node_v22.15.1-win-x64 --noMetadata

# Compile with configuration file (astra.config.js)
astra build src/app.ts

# Skip integrity checks (faster builds)
astra build src/cli.js --disShasumCheck

# Example output:
# [1/4] Building project...
# [2/4] Setting file metadata...
# [3/4] Generating blob...
# [4/4] Injecting blob...
# ✓ Project built successfully! 🚀
# Output: dist/build.exe
```

--------------------------------

### Version Name Parser Helper - astra-cli

Source: https://context7.com/astracompiler/cli/llms.txt

Parses and generates Astra version strings, including architecture, OS, and LTS status. It provides functions to parse existing strings, generate new ones, and check if a version is LTS. It depends on 'astra-cli/src/helpers/nameparse.ts'.

```typescript
import nameparse, { generate, isLTS } from 'astra-cli/src/helpers/nameparse.ts';

// Parse version string
const parsed = nameparse('node_v22.15.1-win-x64-lts.exe');
console.log(parsed);
// Output:
// {
//   arch: 'x64',
//   os: 'win',
//   isLTS: true,
//   version: 'v22.15.1'
// }

// Generate version string
const versionName = generate({
  arch: 'x64',
  os: 'win',
  isLTS: true,
  version: 'v22.15.1'
});
console.log(versionName);
// Output: node_v22.15.1-win-x64-lts

// Check LTS status (async)
const isLTSVersion = await isLTS('node_v20.18.3-win-x64');
console.log(isLTSVersion); // true or false

// Use case: Dynamic version selection
const currentArch = process.arch; // 'x64', 'arm64', etc.
const targetVersion = generate({
  arch: currentArch,
  os: 'win',
  isLTS: true,
  version: 'v22.15.1'
});
```

--------------------------------

### Verify SHA256 Hashes of Binaries

Source: https://context7.com/astracompiler/cli/llms.txt

Verifies the integrity of downloaded Node.js binaries by comparing their SHA256 hashes against official checksums. It fetches checksums from a remote source, calculates the local file's hash, and returns a boolean indicating a match. This helps ensure the downloaded binaries have not been tampered with.

```typescript
import shasumMatch from 'astra-cli/src/helpers/shasum.ts';

// Verify downloaded node.exe integrity
const pathToNode = '/home/user/.astra/versions/node_v22.15.1-win-x64.exe';
const isValid = await shasumMatch(pathToNode);

if (isValid) {
  console.log('Binary integrity verified');
} else {
  console.log('SHA256 mismatch - redownloading...');
  // Trigger reinstall
}
```

--------------------------------

### Edit Windows Executable Metadata

Source: https://context7.com/astracompiler/cli/llms.txt

Edits Windows executable properties such as icons, version information, and company details using the rcedit tool. This function allows for customization of metadata for compiled executables. It requires Windows native execution or Wine on non-Windows systems.

```typescript
import rcedit from 'astra-cli/src/helpers/rcedit.ts';

// Set icon and version information
await rcedit('dist/myapp.exe', {
  icon: 'assets/icon.ico',
  'version-string': {
    CompanyName: 'My Company',
    FileDescription: 'Enterprise Application',
    ProductName: 'My Product',
    LegalCopyright: '© 2024 My Company',
    OriginalFilename: 'myapp.exe',
    InternalFilename: 'myapp'
  },
  'file-version': '1.2.3.4',
  'product-version': '1.2.3'
});

// Complete options example
await rcedit('dist/app.exe', {
  icon: 'icon.ico',
  'version-string': {
    Comments: 'Built with Astra',
    CompanyName: 'Acme Corp',
    FileDescription: 'My App',
    InternalFilename: 'app',
    LegalCopyright: '© 2024',
    LegalTrademarks1: 'Trademark',
    LegalTrademarks2: 'Trademark 2',
    OriginalFilename: 'app.exe',
    ProductName: 'My Product'
  },
  'file-version': '2.0.0.1',
  'product-version': '2.0.0',
  'requested-execution-level': 'asInvoker'
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.