Getting Started

LLM Optimized

These docs are optimized for AI. Add https://buildcosmo.com/llms-full.txt to your AI IDE (like Cursor or Windsurf) for context-aware coding assistance.

Cosmo allows you to build desktop widgets using standard web technologies. This guide covers the end-to-end workflow for developing a widget using the Vite-based scaffolding tool.

Prerequisites

Node.js 20+: Required for the build tooling.
Cosmo for macOS: Must be installed and running on the same machine.
Developer Mode: Enable this in Cosmo via Settings → General. The app will ignore local development widgets if this is disabled.

Scaffold a Project

Run the create command to generate a new widget project. This initializes a Vite project configured for Cosmo.

npm create cosmo-widget@latest my-widget
cd my-widget
npm install

pnpm create cosmo-widget@latest my-widget
cd my-widget
pnpm install

yarn create cosmo-widget@latest my-widget
cd my-widget
yarn install

Setting up an existing web project? See Manual Setup to convert your project into a Cosmo widget.

Project Structure

The scaffolded project includes the following key files:

File	Purpose
`src/widget.js`	The entry point. Must export a `widget()` function.
`widget.config.json`	Mandatory configuration (dimensions, constraints, etc.). Validated at build time.
`widget.preferences-template.json`	Optional schema for user-configurable preferences shown in the widget's context menu.
`thumbnail.png`	Optional preview image for the Cosmo marketplace. Recommended resolution: 512x512px+.

Development Workflow

Start the development server to preview your widget in Cosmo.

npm run dev

This command:

Starts the local Vite development server.
Opens your widget in the Cosmo desktop app.

Server-Only Mode

To run the Vite server without opening the widget in Cosmo (useful for UI testing in a browser):

npm run dev -- -s

Build for Distribution

Package your widget for release.

npm run build

The build process:

Bundles your assets using Vite.
Validates widget.config.json against the schema.
Copies configuration files and the thumbnail to the dist/ directory.

Ensure widget.config.json is valid; build errors will occur if required fields are missing or out of bounds.

Note: Cosmo now supports widget publishing through the web /publish flow. You can either connect a GitHub repository for CI-based publishing or upload a packaged widget ZIP manually. See Distribution for the current publishing options.

Next Steps

Configure your widget's behavior in widget.config.json.
Define user preferences in widget.preferences-template.json.
Explore the Core SDK for available APIs.

Join our Community

Connect with other developers and get support on our Discord server.

On this page