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 |
|---|---|---|---|
name | string | "Clock Widget" | The display name of the widget shown in the marketplace and app. |
minCosmoVersion | string | "0.4.0" | The minimum version of the Cosmo app required to run this widget. |
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 |
|---|---|---|---|
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. |