terrar
TypeScript icon, indicating that this package has built-in type declarations

0.0.1 • Public • Published

Tulipe logo

Terrar.js

An efficient and permeable alternative to iframes.


GitHub Workflow Status GitHub Downloads GitHub License Semantic-release: angular



Disclaimer

This project is a prototype, it has not been through any audit and is even not well tested. DO NO USE IN PRODUCTION. If you're interested in this repo, please give it a start 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 Proxy class to create parent-jailed HTMLElement objects
  • the native Shadow DOM API to create HTML & CSS isolated contexts
  • the Esprima library to prevent the encapsulated context from accessing disallowed objects

Installation

For server-side usage (NodeJS), Terrar.js can be installed like any NPM package :

npm install terrar

And then you can import it in your scripts using :

import "terrar";

For client-side usage (browser), simply put this <script> tag inside of your HTML document :

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

Usage

Like iframes, Terrar frames are a client-side way of isolating some content from the main context. However Terrar frames support SSR, which means that you can pre-populated frames with content generated on server side to reduces the amount of requests the page has to perform.

From JS

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

From HTML

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

or

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

Configuration

The preview Usage section simply shows how to insert an HTML content into a Terrar frame using the default configurations.

If the default configuration should fit most use cases, each Terrar frame can be me manually fine-grained configured to :

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

Limitations

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

So Terrar.js is especially useful with :

  • Contents you own but don't trust (e.g. user-provided HTML content)
  • Contents you dynamically generate from JS and want to prevent collisions between them

Package Sidebar

Install

npm i terrar

Weekly Downloads

7

Version

0.0.1

License

MIT

Unpacked Size

6.95 MB

Total Files

14

Last publish

Collaborators

  • lilarest