Configuration Reference
This guide explains the required configuration for loading your Web Extension in SwyxIt!.
Overview
The configuration must be deployed to the Swyx server using the Swyx Control Center.
Configuration Lifecycle
- Start from the sample-configuration.typical.json example.
- Adjust values for your environment and deployment target.
- Upload the file to the Swyx server using Swyx Control Center.
- Assign Swyx groups and/or users to the Web Extension.
Deployment via Swyx Control Center
Use Swyx Control Center to upload the configuration file to the Swyx server.
Recommended verification after upload:
- Restart SwyxIt! and check that the Web Extension is available.
- If you are using the SDK: Test connect and a basic hub call (for example
GetLoggedInUser) in the target environment.
Schema and Field Reference
⚠️ Important:
Only use the attributes listed below. If you add attributes that are not in this list, or if you use incorrect casing (attribute names are case sensitive), the Web Extensions configuration validation in SwyxIt! will fail and your Web Extension will not be loaded.
Quick Reference Table
| Field | Type | Required | Constraints |
|---|---|---|---|
url | string | Yes | Typically http(s)://host:port (for example localhost or remote host) |
iconUrl | string | No | Must match origin of url, otherwise iconUrl is ignored |
title | string | No | minLength: 1, maxLength: 50 |
titleShort | string | No | minLength: 1, maxLength: 50 |
useSdk | boolean | No | Must be true when using @enreachde/swyx-web-extension-sdk |
remoteConnectorPort | number | No | Range: 0–65535 |
allowStorageAccess | boolean | No | Required for localStorage/sessionStorage/cookies/IndexedDB access; auto-enabled when useSdk is true |
allowPopups | boolean | No | Required to open links in the external default browser; without it, popup attempts are blocked silently |
displayTypes | string[] | No | Default: ['widget']; current values: "widget", "navigation", "static" |
widgetHeight | number | No | Range: 150-2000 Default: 600; applies to "widget" display type |
Field Descriptions
url
The URL of the Web Extension. In most deployments this is a network URL (http:// or https://) such as localhost during development or a remote host in production.
Type: string
Examples:
- Local development:
"http://localhost:3000/web-extension" - Remote host:
"https://example.com/web-extension" - Custom address and port:
"http://my-hostname:8085/web-extension"
iconUrl
The URL of the icon used for the Web Extension in SwyxIt!. The origin of iconUrl must match the origin of url, otherwise the icon is ignored.
Type: string
Supported formats: svg, ico, png
Default: Not set
Examples:
url | iconUrl |
|---|---|
"http://localhost:3000/web-extension" | "http://localhost:3000/web-extension/icon.svg" |
"https://example.com/web-extension" | "https://example.com/web-extension/icon.png" |
"http://my-hostname:8085/web-extension" | "http://my-hostname:8085/web-extension/icon.ico" |
title
The display name of the Web Extension shown in SwyxIt!. If not set, the name configured in Swyx Control Center is used.
Type: string
Constraints: minLength 1, maxLength 50
Default: Not set
titleShort
A shortened display name of the Web Extension. Used in places where space is limited, such as the navigation bar. If not set, title is used instead.
Type: string
Constraints: minLength 1, maxLength 50
Default: Not set
useSdk
Whether the Web Extension requires the SDK to function. If true, the origin of the Web Extension URL will be added to the allowed origins for the SDK, and allowStorageAccess will be enabled automatically.
When using @enreachde/swyx-web-extension-sdk, this field must be true. Otherwise the SDK cannot connect to SwyxIt.
Type: boolean
Default: false
remoteConnectorPort
Port as configured in RemoteConnector, when required. When remoteConnectorPort is set and the RemoteConnector tunnel is active, the URL is patched to 127.0.0.1:<remoteConnectorPort>/....
This requires the same port to be configured in RemoteConnectorConfig. RemoteConnector usage is only required when the Web Extension is not publicly accessible.
Type: number
Constraints: Minimum 0, Maximum 65535
Default: Not set
allowStorageAccess
Enables browser storage access for the Web Extension iframe, allowing it to use localStorage, sessionStorage, cookies, and IndexedDB. Required for Web Extensions that persist user data or session state.
If useSdk is true, this setting has no additional effect and is not required.
Type: boolean
Default: false (or true if useSdk is enabled)
allowPopups
Allows the Web Extension iframe to open a new browsing context. In SwyxIt! the target is not rendered inside the client: the URL is handed over to the operating system's default browser and opened there, outside SwyxIt!.
Enable this for Web Extensions that link to external content.
Type: boolean
Default: false
displayTypes
The display types that the Web Extension supports. If not specified, the default is widget, so the Web Extension is only visible on the home screen as a widget. If specified, the Web Extension is only displayed for the configured display types.
Type: string[] of WebExtensionDisplayType values
Allowed values: See Display Types section below
widgetHeight
The height of the widget when the Web Extension is displayed as a widget. In combination with display type widget, this defines the widget height.
Type: number (pixels)
Default: 600
Applies when: displayTypes includes "widget"
Display Types
The WebExtensionDisplayType enum defines how the Web Extension is displayed in SwyxIt!.
Widget
Adds the Web Extension to the configurable widgets on the SwyxIt! Home Screen.
Value: "widget"
Related fields: When using this display type, configure widgetHeight to set the widget's vertical dimension.
Navigation
Adds the Web Extension to SwyxIt! navigation bar which allows to display the Web Extension in a dedicated content area.
Value: "navigation"
Static
Adds the Web Extension to a static area where it remains visible regardless of the current navigation in SwyxIt! navigation bar.
Value: "static"
Configuration Examples
Minimal Configuration
The simplest valid configuration with only the required field:
{
"url": "https://example.com/web-extension"
}
See sample-configuration.minimal.json for the complete example.
Typical Configuration
A common configuration for extensions that use @enreachde/swyx-web-extension-sdk:
{
"url": "http://localhost:3000/web-extension",
"useSdk": true,
"displayTypes": ["widget"],
"widgetHeight": 600
}
allowStorageAccess is intentionally omitted here. With useSdk: true, it has no additional runtime effect and is not required.
See sample-configuration.typical.json for the complete example.
Full Configuration
A comprehensive configuration including RemoteConnector usage context:
{
"url": "https://internal-web-extension.example.com/app",
"iconUrl": "https://internal-web-extension.example.com/icon.ico",
"title": "Internal Web Extension",
"titleShort": "Web Extension",
"useSdk": true,
"remoteConnectorPort": 8080,
"displayTypes": ["widget", "navigation", "static"],
"widgetHeight": 600
}
When the RemoteConnector tunnel is active, the effective URL is patched to 127.0.0.1:8080/....
allowStorageAccess is intentionally omitted here. With useSdk: true, it has no additional runtime effect and is not required.
See sample-configuration.full.json for the complete example.
Validation and Constraints
When preparing your configuration for deployment, ensure the following:
- SDK usage: If you use
@enreachde/swyx-web-extension-sdk, setuseSdktotrueor the SDK cannot connect to SwyxIt! - allowStorageAccess interaction:
allowStorageAccesshas no additional effect whenuseSdkistrue - allowPopups: Set
allowPopupstotrueonly if the Web Extension opens links outside the iframe; otherwise such attempts are blocked without a visible error. It is independent ofuseSdkand is never enabled automatically - URL format: Use a reachable web URL (
http:///https://) in typical setups (localhost, remote host, or host:port) - title: If
titleis omitted, the name configured for the Web Extension in the Swyx Control Center is used - titleShort: If
titleShortis omitted,titleis used instead; verify it is between 1 and 50 - RemoteConnector dependency: Use
remoteConnectorPortonly when Web Extension requires RemoteConnector tunneling, and mirror the same port in theRemoteConnectorConfig(.rcconfigfile stored in Swyx database) - Port range: If using
remoteConnectorPort, verify it is between 0 and 65535 and not used by another process on your machine running SwyxIt! - Display types: If
displayTypesis omitted, the Web Extension defaults towidget - Widget height: For
widget,widgetHeightdefaults to 600, verify it is between 150 and 2000