Skip to main content

​
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

1

Authenticate with the CLI

overlayed login
This opens your browser to create an API key and stores your credentials locally.
2

Initialize your project

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

​
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
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.

​
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: 
{
	"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

​
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.