An efficient and permeable alternative to iframes.
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.
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)
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.
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)
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)
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.
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.
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