Download

Introduction Last updated: 09-30-2021

Exalt is a JavaScript framework for developing websites, web apps and component libraries. Exalt prioritizes bundle size and cross framework compatibilty by making use of Web Components. As a result of using web components, you can use Exalt components with your favorite libraries and frameworks without being restricted to a specific tech stack.

What is Exalt?

Exalt is a JavaScript framework built as a minimal layer on top of web standards. This was done in order to provide a great developer experience without bloating your app bundles with framework code. Unlike other major frameworks that immediately bloat your bundles, Exalt is ~2kb minified + gzipped.

One of key benefits to using web standards is not only smaller bundle sizes but there is less to learn in order to get a project up and running. Exalt can be used to develop websites, web apps and component libraries. Component libraries powered by the Exalt runtime are able to be used in any other framework thanks to the capabilities provided by Web Components.

Key features of Exalt include:
  • Component API with built in encapsulation
  • Standards based declarative templates
  • Store API for cross component state management
  • Developer tools to streamline the development process
  • Painless prerendering via @exalt/toolchain

Notice

Exalt uses web standards that are not available in outdated browsers such IE 11 and older. The @exalt/toolchain provides a "legacy" option to support older browsers. However we do not provide official support for browsers that dont support the Web Component spec.

Installation

Exalt is easy to get up and running. First install the Exalt CLI globaly. This will give you access to the exalt commands to help you create and develop your project. To install the Exalt CLI, run the following command: npm install -g @exalt/cli

When the Exalt CLI is used outside a project folder, it can only generate projects but when used inside a project folder, it can load the specified toolchain and power the development commands. This allows the CLI to be used regardless of build requirements. If the default toolchain does not fit your needs you can create your own.

If you are using VSCode, you can get a better development experience by using the Exalt VSCode Extension. This extension provides support for syntax highlighting, auto completion, and intellisense for Exalt templates.

Getting Started

Create a new project

You can create a new project by running the create command and supplying the project name. This will generate your new project, install the required dependencies, and initialize a new git repository. By default @exalt/toolchain is used to power your projects build pipeline. This can be changed using the toolchain option in your exalt.json file.

exalt create <app-name>

Run the application

While using the default toolchain, the dev command will launch a web server, watch your files, and build the app as you make changes. As soon as the initial build is complete it will open your app in your default web browser. Any builds after this will refresh the page.

Navigate to your project and launch the dev server cd <app-name> && exalt dev

Exalt Core Last updated: 09-30-2021

Exalt Core is the framework runtime. It provides the component model, declarative templates, and the Store API.

npm install @exalt/core

Building Components

Exalt Components are a small wrapper over native Web Components. This means they work as valid HTML elements and can be used anywhere HTML can be used, including other frameworks. You can use components to build independent and reusable pieces of your application. Components allow you to define your own html tags and hook into the component state and lifecycle.

Component names must have a hypen in the name as required by the custom elements standard. By Default Exalt components make use of the Shadow DOM in order to provide encapsulation. This can easily be disabled using the component options.

Component Options:
  • tag: string - Sets the component tag
  • shadow: boolean - Tells the component to use the ShadowDOM
  • styles: string[] - Set the styles to be used in the component
  • connect: Store[] - tells the component to react to changes in the provided stores
You can define default component options by setting the Component.defaultOptions property.

To create a component all you need to do is create a class that extends "Component" and return a template in the render method.

import { Component, html } from "@exalt/core";
import { define } from "@exalt/core/decorators";
@define("hello-world")
export class HelloWorld extends Component {
render() {
return html`
<h1>Hello World!</h1>
`;
}
}
view raw build-components.js hosted with ❤ by GitHub

Warning

The ShadowDOM provides slots and DOM and CSS encapsulation when enabled. If you are using a global css framework such as bootstrap or tailwindcss, the ShadowDOM must be disabled.

Styling Components

You can apply css to your components in a variety of ways including importing a global stylesheet, inline style elements, and inline style attributes. When using the ShadowDOM, we reccomend using the "styles" component option. You can import your stylesheet as a string and pass an array of stylesheets to the component.

import { Component, html } from "@exalt/core";
import { define } from "@exalt/core/decorators";
import styles from "./hello-world.css";
@define({ tag: "hello-world", styles: [styles] })
export class HelloWorld extends Component {
render() {
return html`
<h1>Hello World!</h1>
`;
}
}
view raw styling-components.js hosted with ❤ by GitHub

Component Lifecycle

In your components, you may want to run specific code at certain times in a components life. Exalt provides a couple lifecycle methods for this purpose.

Lifecycle Methods:
  • render() - render the components html
  • mount() - called when the component is added to the DOM
  • unmount() - called when the component is removed from the DOM
  • onUpdate(key, value) - called when a component's state or attributes are updated
  • shouldUpdate(key, value) - called when a component is about to be updated

import { Component, html } from "@exalt/core";
import { define } from "@exalt/core/decorators";
@define("hello-world")
export class HelloWorld extends Component {
/* render the components html */
render() {}
/* called when the component is added to the DOM */
mount() {}
/* called when the component is removed from the DOM */
unmount() {}
/* called when a component's state or attributes are updated */
onUpdate(key, value) {}
/* called when a component is about to be updated */
shouldUpdate(key, value) {}
}
view raw component-lifecycle.js hosted with ❤ by GitHub

Reactive Properties

Components have access to state an attributes for updating the DOM. When making use of state, users can initialize a reactive property using super.reactive(). This function will take the value and make the property reactive so that whenever the value is changed, the view automatically updates. This example displays the current time and updates the time every second.

import { Component, html } from "@exalt/core";
import { define } from "@exalt/core/decorators";
@define("my-clock")
export class Clock extends Component {
date = super.reactive(new Date());
render() {
return html`
<h1>Current Time: ${this.date}</h1>
`;
}
mount() {
this.timer = setInterval(() => this.date = new Date(), 1000);
}
unmount() {
clearInterval(this.timer);
}
}
view raw reactive-properties.js hosted with ❤ by GitHub

Component Attributes

Attributes are passed into a component like any other html element. When an attribute changes, the component is automatically updated. Attributes can be accessed using the this.props property. THe attributes are also passed into the render() method for easy destructuring.

import { Component, html } from "@exalt/core";
import { define } from "@exalt/core/decorators";
@define("say-hello")
export class SayHello extends Component {
render({ name }) {
return html`
<h1>Hello ${name}!</h1>
`;
}
}
view raw component-attributes.js hosted with ❤ by GitHub

The component can then be used as <say-hello name="John Doe" />

DOM Manipulation

Sometimes you may need to access a DOM element from the template. Because Exalt renders directly to the real dom, you can simply use normal dom manipulation methods. Alternatively Exalt offers a ref api to help clean up your DOM manipulation code.

Simply use the component's createRef() method and give an element the corresponding ref attribute name.

import { Component, html } from "@exalt/core";
import { define } from "@exalt/core/decorators";
@define("hello-world")
export class HelloWorld extends Component {
header = super.createRef();
render() {
return html`
<h1 ref="header">Hello World!</h1>
`;
}
mount() {
this.header.innerHTML = "Goodbye World!";
}
}
view raw dom-manipulation.js hosted with ❤ by GitHub

Writing Templates

Exalt provides a tagged template function for creating templates. This is similar to JSX but its entirely native to the web. You can write standard HTML inside them and use JavaScript expressions through placeholders indicated by curly braces prefixed with a dollar sign.

The html function provides an easier way to bind events to elements and pass data to components, You can pass any data you want as an attribute and Exalt will process it for you. Events are functions bound to attributes with the "on" prefix, these can be any native dom events or custom events.

import { html } from "@exalt/core";
/* bind an event */
html`<button onclick=${() => alert("I was clicked!")}>Click Me!</button>`;
/* bind data as attributs */
const items = [
{ id: Math.random(), value: "1" },
{ id: Math.random(), value: "2" }
];
html`<list-view items=${items} />`;
view raw writing-templates.js hosted with ❤ by GitHub

Additionally you can spread an object as attributes using the spread attribute. All properties on the object will be bound as an attribute using the key as the attribute name, and the value as the attribute value.

import { html } from "@exalt/core";
const details = {
name: "John Doe",
age: 34
};
html`<user-details ...=${details} />`;
view raw writing-templates-spread.js hosted with ❤ by GitHub

Store API

Exalt Components have reactive properties for updating the component it belongs to, but in cases where components need to share state, Exalt provides a global state solution via a store api. You can create a store and then tell individial components to listen to changes on the store using the connect component option. It is best practice to not manipulate the store directly and instead define functions inside the store.

import { Component, html, createStore } from "@exalt/core";
import { define } from "@exalt/core/decorators";
/* create the store */
const store = createStore({
count: 0,
increment() {
this.count++
}
});
@define({ tag: "my-container", connect: [store] })
export class Counter extends Component {
render() {
return html`
<button onclick=${() => store.increment()}>Clicked: ${store.count}</button>
`;
}
}
view raw store-api.js hosted with ❤ by GitHub

Exalt CLI Last updated: 09-30-2021

Exalt CLI provides a clean interface to start new exalt projects and run your build pipeline.

npm install -g @exalt/cli

Create a New Project

You can create a new project by running the create command and supplying the project name. This will generate your new project, install the required dependencies, and initialize a new git repository. By default @exalt/toolchain is used to power your projects build pipeline. This can be changed using the toolchain option in your exalt.json file.

If you wish to generate a component library simply add the --library flag to the command.

exalt create [app-name] <options>

Notice

The Exalt CLI can only generate projects when used outside a project folder. However when using the cli inside a folder containing an exalt.json file. It provides access to the full cli capabilities.

Running a Development Server

The dev command will launch a web server, watch your files, and build the app as you make changes. As soon as the initial build is complete it will open your app in your default web browser. Any builds after this will refresh the page.

exalt dev <options>

Building for Production

You can build the project for production using the build command. This will build the project and place the files into the dist directory.

exalt build <options>

Running your Production App

After building your app for production, you can run it using the start command. This will run your app on a simple http server capable of serving a single page app or static files.

exalt start <options>

Exalt Toolchain Last updated: 09-30-2021

Exalt Toolchain provides a standard development environment with all the features you need for developing websites, web apps, and component libraries with exalt.

npm install --save-dev @exalt/toolchain

Toolchain Features

Exalt Toolchain provides a set of standard build pipleline features.

Features:
  • JavaScript & TypeScript bundling, transpiling, and minification
  • Import aliasing
  • Live reloading development server
  • HTML generation based on build output
  • Support for importing css files
  • Support for importing json files
  • Support for folder components
  • Support for decorators
  • Code splitting support
  • Prerendering support

Toolchain Options

This toolchain offers some options to configure this functionality.

Options:
  • target (default: "es2015") - sets the JavaScript version to be transpiled to
  • publicPath (default: "/") - the asset path to append to the beginning of all asset paths
  • dest (default: "dist") - the build output directory
  • port (default: 3000) - sets the web server port
  • open (default: true) - tells the cli whether or not to launch your app or not
  • prerender (default: false) - tells the cli to prerender your app to static html files
  • legacy (default: false) - sets the build output to support legacy browsers
  • paths (default: {}) - object that maps aliases to file paths
  • external (default: []) - sets the modules to be exluded from the bundle

TypeScript Support

Typescript support is ready out of the box. All you need to do is change your files to have a .ts file extension and make sure your input field is updated in exalt.json. The toolchain will then automatically compile your code down to JavaScript.

Build your own Toolchain

We try to make sure that the default toolchain meets the needs of most projects. In cases where it fails to meet your project requirements, we offer an easy solution to build your own toolchain.

A toolchain is a file that exports a default function and returns an object of command functions. This function recieves the config object consiting of name, input and toolchainOptions properties. The commands that are availble for toolchains to control are dev, start, and build.

Config Object
The config object is controlled by your config file. The config object includes these properties.
  • name: string - the project name
  • input: string | object | array - the entry files to compile
  • toolchainOptions: object - the options to customize the toolchain

export default ({ name, input, toolchainOptions }) => {
return {
dev: () => {},
start: () => {},
build: () => {}
};
};
view raw build-your-own-toolchain.js hosted with ❤ by GitHub

Warning

If you make use of ESM module syntax such as export and import, you must first compile it to commonjs format.

Exalt Router Last updated: 09-30-2021

Exalt Router provides simple client side routing in a declarative manner for Exalt Apps. The components provided by @exalt/router are developed using Exalt itself so they can be treated as any other Exalt component.

npm install @exalt/router

Router Component

The exalt-router component is used to handle all the routing. It parses the routes behehind the scenes and will use push state routing by default. If you want to use hash routing, you can set the hash attribute to enable it.

If you want to programatically change the route, ExaltRouter exposes a static navigate method.

import { ExaltRouter } from "@exalt/router";
ExaltRouter.navigate("/about");
view raw exalt-router-programatically.js hosted with ❤ by GitHub

Route Component

The exalt-route component is used to define a route and assign a component to it. It takes two attributes, url and component.

Parameters are path fragments that are prefixed with a colon and if you want the parameter to be optional you can end it with a question mark. Any route parameters get passed as attributes on the rendered component.

When you want to split the bundle at the route level, you can add an onresolve event.

import { html } from "@exalt/core";
import "@exalt/router/exalt-route";
html`<exalt-route url="/" component="home-page" onresolve=${() => import("@pages/home-page")} />`;
view raw code-splitting-routes.js hosted with ❤ by GitHub

When defining a default route to render if there is no match, just omit the url attribute.

<exalt-router>
<exalt-route url="/" component="home-page" />
<exalt-route url="/about" component="about-page" />
<exalt-route url="/about/:topic?" component="about-page" />
<exalt-route component="not-found" />
</exalt-router>
view raw exalt-route.html hosted with ❤ by GitHub

Redirect Component

The exalt-redirect component is used to conditionally redirect to another page or website. As soon as the component is rendered it will determine how to redirect based on the url attribute and then the page will be redirected.

<exalt-redirect url="/redirected-route" />
view raw exalt-redirect.html hosted with ❤ by GitHub

Exalt SSR Last updated: 09-30-2021

Exalt SSR is a module that provides everything you need to render your app on the server. For rendering your app to static html you can use the --prerender option in @exalt/toolchain.

npm install @exalt/ssr

Loading your App

@exalt/ssr provides a loadBundle(path) function that will initalize the DOM environment and load the application bundle.

The loadBundle function returns whatever exports your app has, in most cases this will be your App component.

import { loadBundle } from "@exalt/ssr";
import path from "path";
const bundlePath = path.join(process.cwd(), "dist", "index.js");
/* loadBundle returns the bundle exports, in this case it returns the App component */
const { App } = loadBundle(bundlePath);
const component = new App();
view raw loading-your-app.js hosted with ❤ by GitHub

Rendering your App

For rendering your app on the server, @exalt/ssr provides a renderToString(component, callback) function that will take your component and render it out to a string.

The DOM environment provided is a subset of the DOM spec and is designed to render exalt components, however as long as the required apis are provided any web component can be rendered. Whenever the renderer encounters a shadow root, it will be rendered as a declarative shadow root.

The renderToString function provides a optional second argument that acts as a callback. This callback recieves the node currently being rendered so you can modify or do extra processing per node. This callback is used to detect the routes to be rendered when using @exalt/toolchain's --prerender option.

import { loadBundle, renderToString } from "@exalt/ssr";
import path from "path";
const bundlePath = path.join(process.cwd(), "dist", "index.js");
/* loadBundle returns the bundle exports, in this case it returns the App component */
const { App } = loadBundle(bundlePath);
const html = renderToString(new App(), (currentNode) => {
console.log(`Rendering: ${currentNode.nodeName}`);
});
console.log(html);
view raw rendering-your-app.js hosted with ❤ by GitHub