README.md

Terrar.js

An efficient and permeable alternative to iframes.

Disclaimer

Do not use in production. This project is a prototype, has not been audited, and has not been thoroughly tested.

Interested in using this library ? Give it a ⭐ to encourage further development.

Introduction

Terrar.js offers HTML, CSS and JS isolations by using :

• the SES library to create rights-less JS compartements
• the native Shadow DOM API to create HTML & CSS isolated contexts
• the Esprima library to prevent the isolated context from accessing disallowed objects (e.g., elements outside of the Shadow Root)

Installation

In an NPM environnement, Terrar.js can be installed like any NPM package :

npm install terrar

You can then import the terrar object using :

import "terrar";

For browser usage, simply put this <script> tag inside your HTML document :

<script src="https://unpkg.com/terrar@latest/dist/terrar.umd.js"></script>

The terrar object will be available in the global scope.

Usage

From JS

To create a Terrar Frame from Javascript, you can use the createFrame() method of the terrar object.

This method takes a string as parameter, which is the HTML content you want to isolate.

const content = `<!-- Your isolated HTML here -->`
const frame = terrar.createFrame(content)

From HTML

To create a Terrar Frame from HTML, you can use the <terrar-frame> custom element.

This element takes a src attribute, which is the URL of the HTML content you want to isolate.

...
<terrar-frame src="https://isolated-content.here/index.html"></terrar-frame>
...

Or you can also pass a content directly to it by wrapping since between <template> tags.

...
<terrar-frame>
  <template>
    <!-- Your isolated HTML here -->
  </template>
</terrar-frame>
...

Note that :

• the src attribute has priority over the <template> tag
• the <template> tag is only used to pass content to the frame, it is not rendered in the main context
• wrapping between <template> and </template> is mandatory (else the isolated content will be executed in the main context)

Configuration

While the default configuration should fit most use cases, you can configure each or all the Terrar frames of the page to :

• allow/restrict the usage of some tags
• expose/hide functions from the main context

Currently, some work remains to make configuration fully functional. This section will not be detailed here yet.

SSR (Server Side Rendering)

Like iframes, Terrar Frames provide a client-side way to isolate content from the main context.

As seen in the Usage section, HTML content can be directly inserted in the HTML document using the <terrar-frame> element.

This means that a server can pre-populate the document before serving it to client. This helps to reduce the number of requests and Javascript executionx the page has to perform.

In the future, it will also be possible to pre-process script on server-side to reduce even more computations on client-side.

Limitations

Since Terrar.js creates SES compartement instead of a whole new Realm (a new JS context) like iframes, many external ressources may not load because of their CORS policy.

So, at the moment, Terrar.js* is especially useful with :

• Contents you own but don't trust (e.g., user-provided HTML contents)
• Contents that trusts you but you don't trust (e.g. partner third-party widgets)
• Contents dynamically generated from JS that you want to prevent from colliding with each other