Lesson 1: Building your first triweb app (TWA) ​

Intro ​

Welcome to the first step of our short tutorial about triweb applications (TWAs). We are excited to have you here, and should you have any questions please get in touch with us and the triweb community through the discussion forum on github.com/triweb

In this lesson you will:

  1. Learn what is a triweb application,
  2. Create a basic app structure,
  3. Write application manifest file,
  4. Learn how to setup any domain and link it to your app.

At the end of the lesson you will have a simple TWA that domain administrators (including you) can deploy to their domains. Once anyone visits such domain your TWA will get installed into the web browser on the visitor's device and remain available under that domain name even when the device is offline. The TWA will not yet do anything fancy - we will start with a simple "Hello world" message shown to the visitors.

External resources and services ​

Through this tutorial we will use the GitHub Gist service to store and serve our code, as it's arguably the easiest and most accessible way to publish code online. If you don't own a domain name yet, you can use the noip.com service to get a free temporary domain name for testing purposes.

INFO

Please note that we are not affiliated with GitHub or NoIP. You use them at your own risk.

1. What is a triweb application (TWA)? ​

Triweb Applications (TWAs) are client-side web applications that use HTML, CSS, and JavaScript. They are similar to Progressive Web Applications (PWAs) as they are installed on user's devices, work in offline mode, and can do everything PWAs can do, with the added superpowers of not being limited to any specific domain name and the build-in ability to communicate and share data with each other across devices.

INFO

If you haven't already, you can learn more about what makes TWAs so special on the Core concepts ➔ Triweb App page.

2. File structure and manifest file ​

Let's start by configuring a basic TWA file structure. Just like any client-side web application, the TWA may be composed of multiple html, css, javascript and other asset files.

The most important file and an entry point to all TWAs is their manifest.json file which should be present in the app's root directory, and specify all files that make the TWA. The manifest.json file uses a syntax which is a superset of the Web app manifest standard as used for PWAs, and extends it with useful properties.

Let's start with a minimal manifest:

json
{
  "id": "tutorial/fabulous-twa",
  "name": "My first fabulous triweb application",
  "description": "An example hello world application"
}
{
  "id": "tutorial/fabulous-twa",
  "name": "My first fabulous triweb application",
  "description": "An example hello world application"
}

While such manifest is technically valid, it won't do much as it's missing the listing of files that make the TWA. Let's correct that by creating a simple index.html file that would be an entry point to our application, and by listing it under assets in the manifest.json so that it gets copied to the web browsers of domain visitors:

json
{
  "id": "tutorial/fabulous-twa",
  "name": "My first fabulous triweb application",
  "short_name": "MyFabulousApp",
  "description": "An example hello world application",
  "assets": [
    "index.html"
  ]
}
{
  "id": "tutorial/fabulous-twa",
  "name": "My first fabulous triweb application",
  "short_name": "MyFabulousApp",
  "description": "An example hello world application",
  "assets": [
    "index.html"
  ]
}
html
<html>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>
<html>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

With just this you have now created your first TWA! 🎉 It's time to publish it somewhere, so that domain administrators can deploy it on their domains. Once deployed, the app will get automatically installed into the web browsers of domain visitors, and it will work and present the "Hello world!" text under that domain even when the user's device is offline.

3. Publishing your TWA ​

To publish the app you can make its manifest.json and asset files available online through any means, but through this tutorial we are going to use the Github Gist to store, customize and serve your new TWA files.

To continue go ahead and fork your private copy of our minimal TWA template gist. You can make any changes you like, for example, you can modify the index.html file, add more assets and reference them in manifest.json file, or just leave the template as it is.

To get the URL of the manifest.json file for your cloned Gist, click on the Raw button next to manifest.json, and copy the URL from the browser's address bar. You can give this URL to any domain administrator, and they will be able to deploy your TWA under their domain, straight from the domain control panel.

4. Deploying to a domain ​

Once your TWA is published, any domain administrator can deploy it to their domain. All they need to know is the URL of your app's manifest file.

This can be done in two simple steps from their domain control panel:

  1. Point their domain at a triweb relay server

    For triweb to work, the domain name needs to be pointed at one of the triweb relay servers. Domain administrator can use our default relay server by adding a CNAME DNS record that points at triweb.io, e.g.,:

    www.mydomain.example    CNAME   triweb.io.
    www.mydomain.example    CNAME   triweb.io.

    The relay server will take care of issuing a free SSL certificate for the domain, and serving the Triweb Container Management Code to its visitors.

  2. Add an app TXT record for a _triweb. subdomain that references the URL of your TWA manifest file

    To deploy your TWA to their domain, domain administrators must also publish a DNS TXT record under the _triweb. subdomain that references the URL of your TWA's manifest.json file. Such record may look like below (just make sure to replace the gist URL below with your own):

    _triweb.www.mydomain.example    TXT   "app https://gist.githubusercontent.com/triweb-dev/1be6be6323413eb09ee0132499d01b4a/raw/316870276ef387742e7689d5496cdc9a1ea94da9/manifest.json"
    _triweb.www.mydomain.example    TXT   "app https://gist.githubusercontent.com/triweb-dev/1be6be6323413eb09ee0132499d01b4a/raw/316870276ef387742e7689d5496cdc9a1ea94da9/manifest.json"
    How this works?

    Once the Triweb Container Management code loads, it will scan the _triweb. subdomain of the current domain for a TXT record that starts with app keyword, and use it value as an URL of the manifest.json file to download and install the selected TWA.

Once these two records are published in DNS, anyone who visits the domain will be greeted by your TWA 💪