Widget Configuration
The widget.config.json file defines the metadata and behavior of your widget. Cosmo reads this file to determine initial dimensions, resizing constraints, and positioning.
Changes to widget.config.json are not hot-reloaded. You must restart the development server (npm run dev) for configuration changes to take effect in the Cosmo app.
Required Fields
The build process validates these fields. Missing or invalid values will prevent the project from building.
| Field | Type | Example | Description |
|---|---|---|---|
configSchemaVersion | number | 1 | The widget config schema version. Current widgets must set this to 1. |
name | string | "Weather" | The display name used in publishing surfaces and the marketplace. |
version | string | "1.0.0" | The widget version published to the marketplace. |
defaultWidth | number | 320 | Initial width in points. |
defaultHeight | number | 200 | Initial height in points. |
minWidth | number | 200 | Minimum width allowed during resizing. |
minHeight | number | 120 | Minimum height allowed during resizing. |
allowResize | boolean | true | If true, the user can resize the widget window. |
keepAspectRatio | boolean | false | If true, the aspect ratio is locked during resizing. |
allowLockScreen | boolean | true | If true, the widget can be put on computer's lock screen. |
allowInternet | boolean | false | Whether the widget can make outgoing network requests. Set this to false unless internet access is necessary for your widget to function. |
Internet access is allowed in development mode regardless of the allowInternet setting.
Optional Fields
| Field | Type | Example | Description |
|---|---|---|---|
id | string | "54a61ab3-6f89-49c5-b6c8-f6d5b72f6604" | Stable marketplace identity for the widget. Keep this fixed across releases if you set it manually. |
maxWidth | number | 800 | Maximum width allowed. |
maxHeight | number | 600 | Maximum height allowed. |
defaultPos | number[] | [0.5, 0.5] | Initial normalized position [x, y] on the screen. [0,0] is bottom-left; [1,1] is top-right. |
backgroundBlurRadius | number | 20 | Applies a Gaussian blur to the window background (in points). Requires a semi-transparent background color in your CSS (e.g., rgba(255, 255, 255, 0.5)). Set to 0 to disable. |
mode | "standard" | "webpage" | "standard" | Controls whether the widget renders local packaged content or wraps an external webpage. |
webpage | object | { "targetURL": "https://example.com" } | Configuration for webpage mode. |
name is required. Cosmo no longer derives marketplace widget titles from package metadata or upload form input.