Skip to main content

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​

  1. Start from the sample-configuration.typical.json example.
  2. Adjust values for your environment and deployment target.
  3. Upload the file to the Swyx server using Swyx Control Center.
  4. 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​

FieldTypeRequiredConstraints
urlstringYesTypically http(s)://host:port (for example localhost or remote host)
iconUrlstringNoMust match origin of url, otherwise iconUrl is ignored
titlestringNominLength: 1, maxLength: 50
titleShortstringNominLength: 1, maxLength: 50
useSdkbooleanNoMust be true when using @enreachde/swyx-web-extension-sdk
remoteConnectorPortnumberNoRange: 0–65535
allowStorageAccessbooleanNoRequired for localStorage/sessionStorage/cookies/IndexedDB access; auto-enabled when useSdk is true
allowPopupsbooleanNoRequired to open links in the external default browser; without it, popup attempts are blocked silently
displayTypesstring[]NoDefault: ['widget']; current values: "widget", "navigation", "static"
widgetHeightnumberNoRange: 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:

urliconUrl
"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.


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, set useSdk to true or the SDK cannot connect to SwyxIt!
  • allowStorageAccess interaction: allowStorageAccess has no additional effect when useSdk is true
  • allowPopups: Set allowPopups to true only if the Web Extension opens links outside the iframe; otherwise such attempts are blocked without a visible error. It is independent of useSdk and is never enabled automatically
  • URL format: Use a reachable web URL (http:///https://) in typical setups (localhost, remote host, or host:port)
  • title: If title is omitted, the name configured for the Web Extension in the Swyx Control Center is used
  • titleShort: If titleShort is omitted, title is used instead; verify it is between 1 and 50
  • RemoteConnector dependency: Use remoteConnectorPort only when Web Extension requires RemoteConnector tunneling, and mirror the same port in the RemoteConnectorConfig (.rcconfig file 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 displayTypes is omitted, the Web Extension defaults to widget
  • Widget height: For widget, widgetHeight defaults to 600, verify it is between 150 and 2000