# Package

{% code lineNumbers="true" %}

```bash
npx positron package [--mac | --win ]
```

{% endcode %}

The `package` command is a core utility of the Positron build pipeline. It compiles, obfuscates, bundles, and packages your source JavaScript code along with a native runtime into a cross-platform distributed application directory (`.app` bundle for macOS or an `.exe` directory for Windows).

### Core Features

* **Smart Bundling:** Uses `esbuild` to bundle your source code into a high-performance single-file pipeline. If missing, it gracefully falls back to a multi-file copying pipeline.
* **Binary Embedding:** Transforms raw application logic and the Node.js runtime into a single, self-contained binary payload.

### CLI Flag Reference

| Flag        | Alternate | Description                                                                       |
| ----------- | --------- | --------------------------------------------------------------------------------- |
| `--mac`     | `--m`     | Explicitly forces the packaging pipeline to output a macOS `.app` bundle.         |
| `--windows` | `--w`     | Explicitly forces the packaging pipeline to output a Windows execution directory. |

> **Note:** If neither `--mac` nor `--windows` are passed, the script will fall back to auto-detecting your host environment via `process.platform`.

### The Packaging Pipeline

{% stepper %}
{% step %}

#### Read package.json & Clean /dist 

{% endstep %}

{% step %}

#### Process JS Pipeline (esbuild bundling & obfuscation)

{% endstep %}

{% step %}

#### Isolate Target OS (macOS .app bundle vs Windows directory structure)

{% endstep %}

{% step %}

#### Build executable Node with @yao-pkg/pkg

{% endstep %}

{% step %}

#### Final Clean-up (Purge temp configuration scripts, icons, and loose code)

{% endstep %}
{% endstepper %}

### Platform-Specific Implementations

#### 1. macOS

Creates a standard Apple App Bundle ecosystem layout.

* **Layout Structure:**

  ```
  dist/
  └── [AppName].app/
      └── Contents/
          ├── Info.plist
          ├── MacOS/
          │   └── [AppName] (Native Positron Compiled Runtime Binary)
          └── Resources/
              ├── positron-backend (The Node.js binary)
              └── [Static Assets...]
  ```

#### 2. Windows

Generates an executable directory distribution workspace.

* **Layout Structure:**

  ```
  dist/
  └── [AppName]/
      ├── [AppName].exe (Renamed Positron executable)
      └── resources/
          ├── positron-backend (The Node.js binary)
          └── [Static Assets...]
  ```
* **Executable Customization:** Utilizes `resedit` to alter the binary's properties natively. It loads `icon.ico` from your project's root and injects it directly into the primary Win32 icon group resource table (`ID: 1`, Lang ID: `1033`).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://positronjs.gitbook.io/v1/cli/package.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.