> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlayed.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Setting up your local development environment for Overlayed

## Overview

When developing with Overlayed locally, your application needs access to metadata about your app from the Overlayed
platform. This guide explains how the `.overlayed` directory works and why it's needed.

## Setup

### First-Time Setup

Make sure you have the [Overlayed CLI](/packages/cli) installed.

<Steps>
  <Step title="Authenticate with the CLI">
    ```bash theme={null}
    overlayed login
    ```

    This opens your browser to create an API key and stores your credentials locally.
  </Step>

  <Step title="Initialize your project">
    ```bash theme={null}
    overlayed init
    ```

    This command:

    * Reads your `overlayed.config.ts` to get your application ID
    * Fetches application metadata from the Overlayed API
    * Creates `.overlayed/meta.json` with the cached data
  </Step>
</Steps>

### Automatic Initialization

If you forget to run `overlayed init`, the first time you run your application in development mode, Overlayed will:

1. Detect that `.overlayed/meta.json` doesn't exist
2. Automatically fetch and cache the metadata
3. Exit the application to load the cached data
4. On the next run, your app will start normally

<Warning>
  This automatic initialization requires you to have run `overlayed login` first. If you haven't authenticated, the
  app will fail to fetch metadata and exit with an error.
</Warning>

## The `.overlayed` Directory

The `.overlayed` directory is created in your project root and contains cached metadata about your application. This
directory:

* **Should be added to `.gitignore`** - It contains cached data that's fetched from the API
* **Is automatically created** - When you run `overlayed init` or when your app first runs in development mode
* **Contains `meta.json`** - Your application's metadata including ID, name, slug, and release information

## What's in `meta.json`?

The cached metadata file contains:

```json theme={null}
{
	"application": {
		"id": "your-app-id",
		"name": "Your App Name",
		"slug": "your-app-slug"
	},
	"release": {
		"id": null,
		"channel": "local",
		"version": "0.0.0"
	}
}
```

This data is used by Overlayed internally to:

* Identify your application
* Configure the runtime environment
* Provide application context to your renderer processes

## Loading Your Site During Development

During local development, your app should load your local dev server — **not** the production URL.

<Warning>
  Never load your production site URL (`https://yoursite.overlayedapps.com`) during local development. The production
  URL requires release headers that are only present in deployed builds.
</Warning>

For example, if your frontend dev server runs at `http://localhost:5173`:

```typescript theme={null}
if (import.meta.env.DEV) {
	// Point this to your local dev server
	this.renderWindow.loadURL("http://localhost:5173");
} else {
	const siteUrl = overlay.windows.getProductionSiteUrl();
	this.renderWindow.loadURL(siteUrl.toString());
}
```

How you determine the local URL depends on your setup. Some frameworks set `ELECTRON_RENDERER_URL`, others use a fixed
port. The important thing is that you load a local URL in dev and `getProductionSiteUrl()` in production.

## Troubleshooting

### "Failed to fetch application metadata"

This error means:

1. You haven't run `overlayed login`, or
2. Your API key is invalid/expired, or
3. Your `overlayed.config.ts` has an incorrect `applicationId`

**Solution:** Run `overlayed login` followed by `overlayed init`.

### "Could not find overlayed instance"

This error in the renderer process means the preload script didn't properly expose the Overlayed globals.

**Solution:** Ensure you're importing `@overlayed/app/preload` in your preload script.