Triweb Application (TWA) ​

What are TWAs? ​

Triweb Applications (TWAs) are client-side web applications that are installed into and served by web browsers of their users. They store data locally in web browsers on users' devices and communicate with each other through a relay server.

TWAs are:

1. Decentralized - TWAs are similar to Progressive Web Applications (PWAs) in that they are installed into the web browser on user's device. What makes TWAs special is that they are not bound to any specific domain name and can operate without web servers. Once developer creates a TWA, any number of domain administrators can choose to use it on their domains, and such TWA will get automatically installed into the web browsers of domain visitors.

2. Distributed - TWAs function in a distributed manner, communicating and sharing data over a relay server and, where possible, through WebRTC peer-to-peer connections. This allows each instance of the TWA, functioning in individual users' browsers under the same domain to interact and share data with one another, allowing them to act together and appear as a cohesive, synchronized application across multiple devices,
3. Local-first - TWAs store data locally on their user's devices without a need for any centralized database. This allows TWAs to work in offline mode and gives users full control over their data.

TWA Structure and Manifest File ​

Just like any client-side web application, TWAs are usually made using HTML, CSS and Javascript. They can consist of multiple files, of which the most important is the TWA manifest file, which should be placed in the root directory of the application and named as manifest.json.

The manifest.json file specifies, among others, the TWA unique identifier, name, icon, and a list of files it is made of. It uses a schema which is a superset of the Web app manifest standard, and should at least include the following properties:

• id - [required] an unique identifier of the TWA in the format matching a /^([a-z_][a-z0-9-_.\/]+)$/ regexp,
• name - the application name as displayed to the user,
• version - the current version,
• assets - an array specifying a list of files that the TWA is made of.

Such manifest.json file may look as below:

{
  "id": "example-app",
  "name": "An example TWA",
  "version": "0.0.3a",
  "assets": [
    "index.html",
    "index.js",
    "index.css",
    "icon.svg"
  ]
}

{
  "id": "example-app",
  "name": "An example TWA",
  "version": "0.0.3a",
  "assets": [
    "index.html",
    "index.js",
    "index.css",
    "icon.svg"
  ]
}

A more complete manifest.json example would include the app description, its icon, and any other useful properties defined for the Web app manifest standard.

Deploying TWA to a domain ​

Once TWA manifest.json file is published anywhere on the web, users can deploy it to their domains by by adding an app DNS TXT record under the _triweb. sub-domain of their domain like below:

_triweb.www.mydomain.example    TXT    "app https://dev.example/manifest.json"

_triweb.www.mydomain.example    TXT    "app https://dev.example/manifest.json"

Given that the mydomain.example in the example above is pointed at a triweb relay server (e.g., triweb.io), and that the manifest at https://dev.example/manifest.json is accessible, this would be enough to make the web browsers of mydomain.example visitors to automatically install and serve the TWA to its users.

👏 🔥

TWApps Catalog ​

When domain administratos specify the location of the TWA which they want to deploy to their domain, they can use a full form which requires a complete valid URL of the manifest file (e.g., as in the example above), or a shorthand form that specifies only the unique app identifier (e.g., example-app). For the shorthand form to work, the TWA needs to be published in the TWApps catalog.

To publish your app in the TWApps catalog, please read the requirements and follow instructions on the github.com/triweb/triweb-apps page.

TWA Runtime Arguments ​

When a TWA is deployed to a domain, a domain administrator may specify additional runtime arguments in DNS TXT records that would be accessible to the triweb application. Such runtime arguments are similar to commandline arguments that are given to desktop applications, and are a basic way of customizing the TWA for a specific domain.

For example, the mydomain.example domain administrator may add following DNS TXT records:

_triweb.mydomain.example    TXT    "app https://dev.example/manifest.json" 
_triweb.mydomain.example    TXT    "heading 'Hello World!'"
_triweb.mydomain.example    TXT    "subheading 'Welcome to mydomain.example' style=bold"

_triweb.mydomain.example    TXT    "app https://dev.example/manifest.json" 
_triweb.mydomain.example    TXT    "heading 'Hello World!'"
_triweb.mydomain.example    TXT    "subheading 'Welcome to mydomain.example' style=bold"

And the TWA may be programmed to read the heading and subheading runtime arguments and act accordingly for the the mydomain.example visitors (e.g., by displaying a personalized texts).

triweb.js API ​

TWAs may include and use the triweb.js library which gives them access to the full functionality offered by the triweb platform.

To learn more visit the triweb.js library documentation on GitHub.