taproot
You'll find the following sections in this document:
What is taproot
taproot is a framework in the truest sense of the word.
taproot provides everything you need to get an application with sound architectural principles running, but doesn't provide any of the parts of that application.
Imagine that your application is a house you'd like to build; taproot pours the foundation and builds scaffolding. You bring the rest.
Quick Start
Installation
npm install -E @thomasrandolph/taproot
taproot ships native ES modules using bare module specifiers. If you don't already have a process that supports resolving bare module specifiers, you may want to read the Advanced Installation section.
Alternatively, see the Setup section for examples that use a version hosted by esm.sh.
Setup
taproot works in a minimal mode with zero configuration.
<html>
<head>
<script type="module">
import { setup } from "https://esm.sh/@thomasrandolph/taproot";
async function start(){
await setup();
}
start();
</script>
</head>
</html>By default taproot attaches itself to the global scope as window.taproot.
This is obviously undesireable in most cases, so a namespace can be provided.
await setup( {
"namespace": "MyApp"
} );Now your application runtime is accessible from window.MyApp.
In either case, taproot assigns your namespace to window.NAMESPACE, so it never needs to be hard-coded anywhere else.
console.log( window[ window.NAMESPACE ].startupOptions );If you run the above code, you'll notice that db is false, but routing is true.
By default, taproot assumes that your application will have multiple routes.
For now, we can turn routing off to simplify our application.
await setup( {
"namespace": "MyApp",
"routing": false
} );Now your application exists, but none of the useful features are available!
This is like pouring the foundation, but not setting up the scaffolding.
You might want to wait until you've completed other tasks before you start your application, so by default taproot is idle.
To start an idle taproot instance, you call .start().
var MyApp = await setup( {
"namespace": "MyApp",
"routing": false
} );
MyApp.start();To see the event-driven power of taproot in action, let's subscribe to an event and then start the application.
async function start(){
var MyApp = await setup( {
"namespace": "MyApp",
"routing": false
} );
MyApp.subscribeWith( {
"TAPROOT|START": () => {
document.body.innerHTML = "My application started up!";
}
} );
MyApp.start();
}
start();Writing an Application
import { setup } from "https://esm.sh/@thomasrandolph/taproot";
async function start(){
var MyApp = await setup( {
"namespace": "MyApp",
"routing": {
"routes": [
[
"/",
() => {
document.body.innerHTML = `Hello, world! Go to <a href="/account/put-your-name-here">/account/[your name]</a>!`;
}
],
[
"/account/:name",
( context ) => {
document.body.innerHTML = `Hello, ${context.params.name}`;
}
]
]
}
} );
MyApp.start();
}
start();Now you have a working application with routing!
But we should leverage the powerful message bus provided by taproot.
import { setup } from "https://esm.sh/@thomasrandolph/taproot";
async function start(){
var MyApp = await setup( {
"namespace": "MyApp",
"routing": {
"routes": [
[ "/", () => MyApp.publish( { "name": "VIEW_CHANGE", "view": "home" } ) ],
[ "/account/:name", ( context ) => MyApp.publish( { "name": "VIEW_CHANGE", "view": "account", context } ) ]
]
}
} );
MyApp.subscribeWith( {
"VIEW_CHANGE": ( message ) => {
let views = {
"home": () => document.body.innerHTML = `Hello, world! <br /><br /> Go to <a href="/account/put-your-name-here">/account/[your name]</a>`,
"account": ( msg ) => document.body.innerHTML = `Hello, ${msg.context.params.name}`,
"error": () => document.body.innerHTML = "There was an error trying to route you."
};
if( views[ message.view ] ){
views[ message.view ]( message );
}
else{
views.error();
}
}
} );
MyApp.start();
}
start();Advanced Concepts
Components
Almost any site could use components to break up unrelated code into encapsulated chunks, or enable convenient reuse.
To that end, taproot provides a simple base Component class to construct these basic application building blocks.
Most of the syntax you'll see is just Lit, since the taproot Component class is a very small wrapper around Lit.
Be careful that you're not over-componentizing. Ask yourself:
- Is splitting this code into two separate components necessary?
- Does componentizing this area of the code improve the application in the long run?
- Will you ever reuse this component anywhere else?
Keep in mind that the more components you have, the more JavaScript overhead there is in the browser.
Keep your performance budget front-of-mind.
Imagine you want to build an application to view and rate pups.
You will almost certainly need a component that displays a pup to the screen, so let's make that now:
import { Component, html } from "https://esm.sh/@thomasrandolph/taproot/Component";
export class Pup extends Component{
static properties = {
"pup": { "type": Object }
}
constructor(){
super();
this.pup = null;
}
render(){
return this.pup
? html`
<h1>${this.pup.name}</h1>
<img src="${this.pup.profilePicture}" />
<p>${this.pup.biography}</p>
`
: "No pup. ☹️";
}
}This component is a native Web Component, so you could register it like:
customElements.define( "pupsrater-pup", Pup );Now, when you render a pup, you can pass it a pup like:
<!-- other HTML -->
<pupsrater-pup .pup="${myPup}"></pupsrater-pup>Note that this uses Lit's
htmltemplate expression syntax.The equivalent code without Lit is:
<pupsrater-pup></pupsrater-pup> <script> var thePupElement = document.querySelector( "pupsrater-pup" ); thePupElement.pup = myPup; </script>
State machines
taproot Components also ship with a tiny finite state machine attached to them.
For more information about why finite state machines are included by default with Components, please refer to:
- https://kyleshevlin.com/enumerate-dont-booleanate
- https://medium.com/@asolove/pure-ui-control-ac8d1be97a8d
- https://css-tricks.com/robust-react-user-interfaces-with-finite-state-machines/
Fundamentally, the reason is: a UI should never be in confusing (or technically impossible) states, and more than one or two possible switches can cause exponential state combination growth. A finite state machine limits both the possible states, and their possible interactions.
Imagine our Pup component loads the pup dynamically:
import { Component, html } from "https://esm.sh/@thomasrandolph/taproot/Component";
export class Pup extends Component{
static properties = {
"pup": { "type": Object },
"isLoading": { "type": Boolean, "state": true },
"errorLoading": { "type": Boolean, "state": true },
"isRetrying": { "type": Boolean, "state": true },
"retries": { "type": Number, "state": true }
}
constructor(){
super();
this.pup = null;
// Internal state
this.isLoading = false;
this.errorLoading = false;
this.isRetrying = false;
this.retries = 0;
}
fetchPup(){
var pupUrl = "/api/pup/good-boi-1234";
var pup;
this.isLoading = true;
this.errorLoading = false;
try{
pup = await fetch( pupUrl );
this.isLoading = false;
this.isRetrying = false;
this.pup = pup;
}
catch( error ){
this.errorLoading = true;
this.isLoading = false;
this.isRetrying = false;
if( this.retries < 2 ){
++this.retries;
this.isRetrying = true;
this.fetchPup();
}
}
}
connectedCallback(){
this.fetchPup();
}
render(){
var output;
if( this.loading && !this.retrying ){
output = html`Playing fetch with this pup...`;
}
else if( this.retrying ){
output = html`Had trouble getting this pup to respond to the "Come" command, trying again, a little more firmly.`;
}
else if( this.errorLoading ){
output = html`Couldn't fetch this pup. ☹️`;
}
else if( !this.pup ){
output = html`No available pup. ☹️`;
}
else{
output = html`
<h1>${this.pup.name}</h1>
<img src="${this.pup.profilePicture}" />
<p>${this.pup.biography}</p>
`;
}
return output;
}
}This is a mess and - to be honest with you - I'm not even sure if it's right. Did I toggle all the booleans correctly? Did I handle each case properly? Do you move between the combined boolean states correctly? I'm not really sure.
Finite state machines solve this mess by:
- Defining each possible state
- Defining exactly how one state moves into others
- Only allowing those defined transitions
Let's rewrite with the included state machine:
import { Component, html } from "https://esm.sh/@thomasrandolph/taproot/Component";
export class Pup extends Component{
static properties = {
"pup": { "type": Object },
"retries": { "type": Number, "state": true }
}
constructor(){
super();
this.pup = null;
// Internal state
this.retries = 0;
this.state.init( {
"initial": "idle",
"states": {
"idle": {
"on": {
"FETCH": "loading"
}
},
"loading": {
"on": {
"ERROR": "error",
"LOADED": "pup"
}
},
"pup": {
"on": {
"FETCH": "loading"
}
},
"error": {
"on": {
"RESET": "idle",
"RETRY": "retrying",
}
},
"retrying": {
"on": {
"ERROR": "error",
"LOADED": "pup"
}
}
}
} );
this.state.start();
}
fetchPup(){
var pupUrl = "/api/pup/good-boi-1234";
var pup;
this.transition( "FETCH" );
try{
pup = await fetch( pupUrl );
this.transition( "LOADED" )
this.pup = pup;
}
catch( error ){
this.transition( "ERROR" );
if( this.retries < 2 ){
++this.retries;
this.transition( "RETRY" );
this.fetchPup();
}
}
}
connectedCallback(){
this.fetchPup();
}
render(){
var output = {
"idle": html`No available pup. ☹️`,
"loading": html`Playing fetch with this pup...`,
"retrying": html`Had trouble getting this pup to respond to the "Come" command, trying again, a little more firmly.`,
"error": html`Couldn't fetch this pup. ☹️`,
"pup": html`
<h1>${this.pup.name}</h1>
<img src="${this.pup.profilePicture}" />
<p>${this.pup.biography}</p>
`
};
return output[ this.state ] || html`Unhandled pup state!`;
}
}While the difference in how the finite state machine is integrated into the component is fairly minor, the under-the-hood guarantees are more than worth it:
- Linear - not exponential - potential states
- Impossible to move in an undefined way - each state + transition combination defines exactly how the app can change
- Single-value states rather than boolean combinations - which allows declared behavior lookups rather than imperative tests
Application architecture
taproot can be used in any application architecture, but the recommended approach is an Enhanced Multi-Page Application (EMPA).
EMPA
In an EMPA architecture, each main "page" is provided by a server and your JavaScript is loaded once the page has been parsed by the browser.
Both sides of that process should be fast, which is why taproot tries to stay as small and fast as possible without sacrificing features.
The server-side should also stay fast and light.
Let's go back to the pup rating app from the Component topic.
You might have three main pages for this application:
- A user profile page where the user can manage their account and see all of the dog ratings they have submitted
- A dog profile page where users can see dogs and rate them
- An index of all dogs
Your folder structure could be something like:
public/
⎣ js/
⎣ profile/
⎣ pups/
⎣ pup/
⎣ index.html
⎣ index.js
And each page file might look something like this example pup/index.html file:
<html>
<head>
<script type="module" src="./index.js"></script>
</head>
<body>
<pupsrater-pup></pupsrater-pup>
</body>
</html>Of course, for other pages, the top-level component might be <pupsrater-pups-list> or <pupsrater-profile> instead of <pupsrater-pup>.
In the case of the Pup page, you're going to need to tell the browser what a <pupsrater-pup> component is, so pup/index.js might look like:
import { Pup } from "../js/components/Pup/Pup.js";
customElements.define( "pupsrater-pup", Pup );In this case, we're assuming a very simple structure where the JavaScript for your application lives right next to the folders for your pages.
A more structured application might store
pageswithin your source and compile (and bundle) eachindex.jsout to a cloned directory in thepublicfolder so that the source code isn't public, only compiled pages are.
Notably, this Pup page can start our whole cascade of imports and behavior contained within the pupsrater-pup component, but those are all UI concerns. There are two more concerns that we should definitely handle here at the "application startup" level: Routing and "Business Logic".
"Business Logic" is used here broadly to encompass something roughly like "everything your app does that's not application infrastructure and not UI." You could think of it like "everything that happens automatically AFTER the application is running or manually after a user does something."
In our A-pup-lication, a single "Pup" page for all the many pups we want to rate isn't going to cut it, so we'll need a tiny bit of routing to figure out which pup we're looking at. We'll expand the above /pup/index.js file:
import { setup } from "https://esm.sh/@thomasrandolph/taproot";
import { Pup } from "../js/components/Pup/Pup.js";
customElements.define( "pupsrater-pup", Pup );
var pupsrater = setup( {
"namespace": "pupsrater",
"routing": {
"routes": [
[
"/pup/:id",
( context ) => {
pupsrater.publish( "VIEW_PUP", { "pupId": context.params.id } );
}
],
[
"/pup", // Single pup page, but no pup id?
() => window.location = "/pups"; // Redirect to the main pups list
]
]
}
} );
pupsrater.start();Now we've got a bit of front end magic for a dynamic route, but nothing can handle that.
Let's update our demo Pup component (js/components/Pup/Pup.js) from the Component topic to respond to VIEW_PUP events to show the right pup.
import { Component, html } from "https://esm.sh/@thomasrandolph/taproot/Component";
export class Pup extends Component{
static properties = {
"pup": { "type": Object },
"retries": { "type": Number, "state": true },
"subscriptions": { "type": Array, "state": true }
}
constructor(){
super();
this.pup = null;
// Internal state
this.retries = 0;
this.subscriptions = [];
this.state.init( {
// Snipped for brevity, same as before
} );
this.state.start();
}
connectedCallback(){
super.connectedCallback();
this.subscriptions.push( window.pupsrater.subscribeWith( {
"VIEW_PUP": ( event ) => {
this.fetchPup( event.pupId );
}
} ) );
}
disconnectedCallback(){
this.subscriptions.forEach( ( subscription ) => {
subscription.unsubscribe();
} );
super.disconnectedCallback();
}
fetchPup( pupId ){
var pupUrl = `/api/pup/${pupId}`;
// Snipped for brevity, this is the same rest of the function as before
}
render(){
// Snipped for brevity, same as before
}
}Note that the only changes here are the concept of "subscriptions" within the component - which are active when the component is in the DOM and removed when the component is removed from the DOM - and the fetchPup function now takes the pup ID to fetch instead of having it hard coded.
The only subscription here listens for our new VIEW_PUP event and loads the correct pup internally.
Finally, we should clean up "business logic" from within this UI component; it's not exactly appropriate that UI components might make a network request (or do any other "application" work other than render an interface and react to user interaction). Plus, fetching (and responding to errors while fetching) a pup might be something that other parts of the application might need to do.
taproot suggests extracting these kinds of behaviors out to a common directory like actions, which borrows from Flux-style global variables to name and define all potential behaviors.
public/
⎣ js/
❘ ⎣ components/
❘ ⎣ actions/
❘ ⎣ pups.js
⎣ profile/
⎣ pups/
⎣ pup/
⎣ index.html
⎣ index.js
In js/actions/pups.js, we'll define a common registration function and the potential actions we want to abstract:
export function registerPupsActions( { publish, subscribeWith } = window.pupsrater ){
return subscribeWith( {
"VIEW_PUP": ( event ) => {
let tries = event.previousTries || 0;
let sequenceId = event.tx;
let pupUrl = `/api/pup/${event.pupId}`;
let pup;
try{
pup = await fetch( pupUrl );
publish( {
"tx": sequenceId,
"name": "LOADED_PUP",
pup
} );
}
catch( error ){
publish( {
"tx": sequenceId,
"name": "LOAD_PUP_FAILURE",
error
} );
if( tries < 2 ){
++tries;
publish( {
...event,
"previousTries": tries
} );
}
}
}
} );
}Then, we'll pupdate our a-pup-lication entry module (/pup/index.js) to load those actions and register them:
import { setup } from "https://esm.sh/@thomasrandolph/taproot";
import { registerPupsActions } from "../js/actions/pups.js";
import { Pup } from "../js/components/Pup/Pup.js";
customElements.define( "pupsrater-pup", Pup );
var pupsrater = setup( {
"namespace": "pupsrater",
"routing": {
"routes": [
[
"/pup/:id",
( context ) => {
pupsrater.publish( "VIEW_PUP", { "pupId": context.params.id } );
}
],
[
"/pup", // Single pup page, but no pup id?
() => window.location = "/pups"; // Redirect to the main pups list
]
]
}
} );
registerPupsActions( pupsrater );
pupsrater.start();As a last step of cleaning up the business logic, let's pull the network fetching out of the UI component (js/components/Pup/Pup.js) and rely on events:
import { Component, html } from "https://esm.sh/@thomasrandolph/taproot/Component";
export class Pup extends Component{
static properties = {
"pup": { "type": Object },
// No more tracking of retries here!
"subscriptions": { "type": Array, "state": true }
}
constructor(){
super();
this.pup = null;
// Internal state
// No more setting the initial retries count here!
// Snipped for brevity, same as before
}
connectedCallback(){
super.connectedCallback();
this.subscriptions.push( window.pupsrater.subscribeWith( {
"VIEW_PUP": ( event ) => {
let transition = event.previousTries > 0 ? "RETRYING" : "LOADING";
this.transition( transition );
},
"LOADED_PUP": ( { pup } ) => {
this.pup = pup;
this.transition( "LOADED" );
},
"LOAD_PUP_FAILURE": () => this.transition( "ERROR" )
} ) );
}
disconnectedCallback(){
// Snipped, same as before
}
// fetchPup method is removed!
render(){
// Snipped, same as before
}
}SPA
A Single Page Application architecture would look roughly like the EMPA architecture, with a couple key differences.
Consider: Does your application require a single page? Ask yourself:
- Could I make more of my content compiled ahead of time, so that a server round trip is fast?
- Have I prepared for the potential of long-running memory leaks, and factored that into my performance and maintenance budget?
- Would upcoming platform-native View Transitions smooth any potential rough edges instead?
For a single page, your application obviously wouldn't need any single-page directories.
public/
⎣ js/
❘ ⎣ myapp.js
⎣ index.html
How you get js/myapp.js is up to you, but - for production sites - it is recommended that you compile to that target, rather than shipping your source code.
In this scenario, index.html could simply be:
<html>
<head>
<script defer type="module" src="/js/myapp.js"></script>
</head>
<body>
</body>
</html>Note the
deferattribute.
While the HTML parser will encounter your application script early, it will not block on loading it, and it won't execute it until the DOM has been fully parsed.
Then, in js/myapp.js you could determine what top-level component to render (instead of the HTML content having it already, like in the EMPA architecture):
import { setup } from "https://esm.sh/@thomasrandolph/taproot";
import { html, render } from "https://esm.sh/@thomasrandolph/taproot/Component";
import { Profile } from "../js/components/Profile/Profile.js";
import { Pup } from "../js/components/Pup/Pup.js";
import { PupsList } from "../js/components/PupsList/PupsList.js";
customElements.define( "pupsrater-profile", Profile );
customElements.define( "pupsrater-pup", Pup );
customElements.define( "pupsrater-pups-list", PupsList );
function renderTopComponent( byName ){
var components = {
"profile": html`<pupsrater-profile></pupsrater-profile>`,
"pup": html`<pupsrater-pup></pupsrater-pup>`,
"pups-list": html`<pupsrater-pups-list></pupsrater-pups-list>`
}
render( components[ byName ], document.body );
}
var pupsrater = setup( {
"namespace": "pupsrater",
"routing": {
"routes": [
[
"/pup/:id",
( context ) => {
renderTopComponent( "pup" );
pupsrater.publish( "VIEW_PUP", { "pupId": context.params.id } );
}
],
[
"/pup", // Single pup page, but no pup id?
() => window.location = "/pups"; // Redirect to the main pups list
],
[
"/pups",
() => renderTopComponent( "pups-list" );
],
[
"/profile",
() => renderTopComponent( "profile" );
]
]
}
} );
pupsrater.start();Keep in mind that there is much inefficiency here as a result of the single page nature of this application.
One simple improvement might be to expand the functionality of renderTopComponent so that the component itself is imported dynamically and registered only when it is needed.
import { setup } from "https://esm.sh/@thomasrandolph/taproot";
import { html, render } from "https://esm.sh/@thomasrandolph/taproot/Component";
// The components are not imported or defined here, like they were before!
async function renderTopComponent( byName ){
var components = {
"profile": [
"../js/components/Profile/Profile.js",
"Profile",
"pupsrater-profile",
html`<pupsrater-profile></pupsrater-profile>`,
],
"pup": [
"../js/components/Pup/Pup.js",
"Pup",
"pupsrater-pup",
html`<pupsrater-pup></pupsrater-pup>`,
],
"pups-list": [
"../js/components/PupsList/PupsList.js",
"PupsList",
"pupsrater-pups-list",
html`<pupsrater-pups-list></pupsrater-pups-list>`,
]
}
var [ registerPath, className, definitionName, output ] = components[ byName ];
var mod = await import( registerPath );
customElements.define( definitionName, mod[ className ] );
render( output, document.body );
}
// The rest remains as beforeKeep in mind that much of this dynamicism could be achieved with an EMPA architecture.
Most of this code "duplicates" what a browser with static HTML and a per-page JavaScript file could do implicitly.
The View helper
taproot provides a simple helper called render to very slightly simplify rendering a new top-level component.
import { render } from "https://esm.sh/@thomasrandolph/taproot/View";
render( "pupsrater-pup" );You could update renderTopComponent again to use this instead of Lit's html and render.
import { render } from "https://esm.sh/@thomasrandolph/taproot/View";
async function renderTopComponent( byName ){
var components = {
"profile": [
"../js/components/Profile/Profile.js",
"Profile",
"pupsrater-profile"
],
"pup": [
"../js/components/Pup/Pup.js",
"Pup",
"pupsrater-pup"
],
"pups-list": [
"../js/components/PupsList/PupsList.js",
"PupsList",
"pupsrater-pups-list"
]
}
var [ registerPath, className, definitionName ] = components[ byName ];
var mod = await import( registerPath );
customElements.define( definitionName, mod[ className ] );
render( definitionName );
}In most cases, Lit's
renderis more efficient than other DOM rendering utilities - like taproot'srender.However, because the top-level component is the only child, a direct replacement like how taproot's
renderworks isn't materially worse.
taproot's render skips modifying the DOM if the target element already contains the requested element name.
Regardless of whether the DOM is updated or not, the requested element is returned, which means you can perform actions on the component.
import { render } from "https://esm.sh/@thomasrandolph/taproot/View";
var Pup = render( "pupsrater-pup" );
Pup.pup = {
"name": "Good Boi",
"profilePicture": "/images/pups/good-boi-1234.jpg",
"biography": "He's a very good boi."
};If you directly modify a component this way, make sure your changes don't require statefulness.
As a general rule, you should only set properties on the component, which is the standard API that would be used when rendering HTML normally.
Storage
IndexedDB
Documentation coming soon.
LocalStorage
Documentation coming soon.
SessionStorage
Documentation coming soon.
Event sequences
Documentation coming soon.
Advanced Installation
Use esbuild to create importable libraries
- Install esbuild:
npm install -E -D esbuild - Run a script for all your dependencies:
import { build } from "esbuild"; async function run(){ await build( { "entryPoints": [ "./node_modules/@thomasrandolph/taproot", // Etc. ], "allowOverwrite": true, "bundle": true, "splitting": true, "chunkNames": "common/[hash]", "format": "esm", "outdir": "./web_modules/" } ); } run();
- When you import the module, use
web_modules/@thomasrandolph/taproot.js - Repeat step 2 whenever your dependencies change (this can be automated, for example as a postinstall hook)
Optional: Consider emptying the
./web_modulesdirectory entirely before building your dependencies to clean up vestigial packages and chunks.
Use other bundling options
Any combination of bundlers and transpilers can resolve bare module specifiers into something that works on the web.
As long as your bundler understands ECMAScript Modules (the standard module specification for JavaScript), you can use taproot in your build pipeline.