# package.json

When you run the packager, it reads several fields from your root `package.json` file to dynamically configure the build, generate native metadata, and establish the application's identity.

| Key           | Type     | Description                                                                                                                                     | Default / Fallback                                                               |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `productName` | `string` | The human-readable name of your application. This is used for the `.app` bundle name on macOS and the `.exe` folder/executable name on Windows. | Falls back to `name`, then `POSITRON_APP_NAME` env variable, or `"PositronApp"`. |
| `version`     | `string` | The version of your application. On macOS, this directly populates the `CFBundleShortVersionString` in the bundle's `Info.plist`.               | `"1.0.0"`                                                                        |
| `author`      | `string` | The author/organization name. Used on macOS to construct the unique bundle identifier (`com.[author].[appname]`) and the copyright notice.      | `"positron"` / `"Positron"`                                                      |
| `macCategory` | `string` | **(macOS Specific)** The Apple application category type used to populate the `LSApplicationCategoryType` in the `Info.plist`.                  | `"public.app-category.developer-tools"`                                          |

### Application Naming Priority

The script determines your final application's name using the following priority order:

1. `process.env.POSITRON_APP_NAME` (Environment Variable)
2. `productName` (In `package.json`)
3. `name` (In `package.json`)
4. `"PositronApp"` (Hardcoded fallback)

> **Tip:** Use `productName` for spaces and capital letters (e.g., `"My Awesome App"`), and keep `name` kebab-cased for npm compatibility (e.g., `"my-awesome-app"`).

### macOS Bundle Metadata (`Info.plist`)

For macOS builds (`--mac` or `--m`), an `Info.plist` file is auto-generated inside the app bundle using your `package.json` properties:

* **Bundle Identifier:** Generated as `com.${package.author}.${appName.toLowerCase()}`. Ensure your `author` field contains no spaces or special characters if you want a clean reverse-DNS identifier.
* **Copyright:** Populated directly from the `author` field.
* **App Category:** Controlled entirely by `macCategory`. If your app is not a developer tool, you should override this field (e.g., `"public.app-category.utilities"` or `"public.app-category.productivity"`).

### Example `package.json`

Here is an example configuration optimized for the packaging pipeline:

```json
{
  "name": "my-desktop-tool",
  "productName": "DesktopTool Pro",
  "version": "2.4.0",
  "author": "ExampleCorp",
  "macCategory": "public.app-category.utilities",
  "dependencies": {
    // Your dependencies...
  }
}
```

#### Resulting Output with this Config:

* **Windows:** Generates a folder and executable named `dist/DesktopTool Pro/DesktopTool Pro.exe`.
* **macOS:** Generates an app bundle named `dist/DesktopTool Pro.app` with an internal bundle ID of `com.examplecorp.desktoptool pro`.


---

# 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/package-json.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.