# App

The `app` object manages the application lifecycle, window focus states, application configurations, and data persistence paths. It inherits or wraps an underlying event-emitting mechanism to communicate core lifecycle changes.

{% code lineNumbers="true" %}

```javascript
const { app } = require("positron.js")

app.setName("Name")
```

{% endcode %}

### Properties

#### `name`

* **Type:** `string`
* **Description:** The current display name of the application.

#### `events`

* **Type:** `EventEmitter`
* **Description:** Provides direct access to the underlying `appEvents` instance for advanced event-handling patterns.

### Methods

#### `quit(exitCode)`

Initiates the application shutdown sequence. It notifies listeners, requests a native process termination via WebSocket, and forces a process exit after a brief delay.

* **Parameters:**
  * `exitCode` (`number`, optional): The exit code to close the process with. Defaults to `0`.
* **Returns:** `void`

<details>

<summary><strong>Sequence</strong></summary>

1. Emits the `before-quit` event via `app.events`.
2. Sends a `terminate` command JSON payload to `activeSocket` if the WebSocket connection is open.
3. Fires the `quit` event on the global `appEvents` bus.
4. Forces `process.exit(exitCode)` after a 20-millisecond delay.

</details>

#### `on(event, listener)`

Registers a persistent callback function to listen for application-level events.

* **Parameters:**
  * `event` (`string`): The name of the event (e.g., `"before-quit"`, `"quit"`, `"name-updated"`).
  * `listener` (`Function`): The callback function executed when the event is fired.
* **Returns:** `void`

#### `off(event, listener)`

Removes a previously registered event listener.

* **Parameters:**
  * `event` (`string`): The name of the target event.
  * `listener` (`Function`): The specific callback function to remove.
* **Returns:** `void`

#### `once(event, listener)`

Registers a one-time callback function. The listener will trigger at most once, and is automatically removed immediately after invocation.

* **Parameters:**
  * `event` (`string`): The name of the event.
  * `listener` (`Function`): The callback function to execute.
* **Returns:** `void`

#### `getFocusedWindow()`

Asynchronously checks all active application windows to find which one is currently focused by the user.

* **Parameters:** None
* Returns: Promise - Resolves with the focused window object, or null if no windows currently hold focus.

#### `setName(name)`

{% hint style="info" %}
This is called with the name from your `package.json` on start
{% endhint %}

Updates the application identity across the environment and prepares the required file system directories for user data storage.

* **Parameters:**
  * `name` (`string`): The new name for the application.
* **Returns:** `void`
* **Side Effects:**
  * Synchronizes `process.env.POSITRON_APP_NAME`.
  * Emits the `name-updated` event.
  * Ensures the physical `userData` directory path exists on the disk (creates it recursively if missing).

### Sub-Modules (`userData`)

The `userData` sub-module handles file system operations related to local application storage configurations and user profile states.

#### `userData.getPath(append)`

Retrieves the absolute operating system directory path designated for storing local application data.

* **Parameters:**&#x20;
  * `append` `(string)`: Append this string to the file path.
* **Returns:** `string` - The absolute platform-specific file path.

| **Windows (win32)** | process.env.APPDATA OR C:\Users\\\AppData\Roaming\\ |
| ------------------- | --------------------------------------------------- |
| **macOS (darwin)**  | /Users//Library/Application Support/                |

#### `userData.delete()`

Recursively deletes the application's local user data directory from the host machine disk if it exists.

* **Parameters:** None
* **Returns:** `void`
* **Console Logs:** Logs a `success` message upon deletion, or a `warn` statement if the directory did not exist.

### Events

The `app` object handles the following events through its event emitter methods (`on`, `once`, `off`):


---

# 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/modules/app.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.