Single Page XHR - The essential dom enhancement for static SSR powered web applications. SPX is a lightening fast, lightweight (18kb gzip) over the wire (push~state) solution that employs an incremental (snapshot) morphing tactic with DOM driven component capabilities integrated at the core.
Documentation lives on ➠ https://spx.js.org
Note
Documentation is still a WIP so please just read the codebase or refer to the type definitions for a better understanding. You can also check the test and docs directories for real-world implementations.
- Simple and painless drop-in integration.
- Supports components extendability.
- Pre-fetching capabilities using hover, intersection or proximity observers.
- Snapshot caching engine and per-page state control.
- Powerful pub/sub event driven lifecycle triggers.
- Gracefully handles script and style asset evaluation.
- Attribute driven programmatic control.
- Zero dependencies and lightweight
SPX is available for download on the NPM registry.
SPX is currently in the RC version release stage. Majority of its API has been ironed out and used in production.
<pnpm|npm> add spxSPX is distributed as an ESM module and designed for usage in browser. You need to establish a connection to invoke the module, this can be done by calling the spx() method.
import spx from 'spx';
spx({
fragments: [
'menu',
'main'
]
})(function (session) {
// Callback is invoked on DOMContentLoaded.
console.log(session)
});An SPX connection will initialize an SPX session. In the above example we are targeting the <nav> and <main> element fragments. In your web application, ensure both elements exist for each page, for example:
<header>
<nav id="menu">
<a href="/">Home</a>
<a href="/about">About</a>
</nav>
</header>
<main id="main">
<h1>Hello World!</h1>
</main>For more advanced cases, SPX provides component extendability. Connect components to DOM elements and use attribute driven control for state, events, and element queries:
import spx from 'spx';
class Counter extends spx.Component({
nodes: <const>['count'],
state: {
clicks: 0
}
}) {
increment () {
this.countNode.innerText = ++this.state.clicks
}
}
spx.register(Counter);Associate the component to a DOM elements, add the following within a defined fragment and allow SPX to do the rest:
<section spx-component="counter">
Clicked: <span spx-node="counter.count">0</span>
<button
type="button"
spx@click="counter.increment"> Increment </button>
</section>Contributions are welcome! This project uses pnpm for package management and is written in TypeScript.
- Ensure pnpm is installed globally
npm i pnpm -g - Leverage
pnpm envif you need to align node versions. - Clone this repository
git clone https://github.com/panoply/spx.git - Run
pnpm iin the root directory - Run
pnpm devfor development mode
The project uses tsup for producing the distributed bundle.
pnpm dev # Development in watch mode
pnpm build # Bundle distribution builds for production
pnpm docs # Documentation development environment
pnpm test # Spins up the testing web applicationThe tests directory contains a runtime for testing SPX. Given that SPX often involves actions that typical testing tools don't handle well, a custom test suite that performs e2e (end-to-end) testing is appropriated.
We generate a static site using 11ty and serve it locally. Each test case is written and then executed in the browser. We rely on good old-fashioned debugging techniques, such as using developer tools and monitoring the console, to ensure that features work as intended without errors.
In the cases directory, you'll find sub-directories named after individual test cases. Each sub-directory follows a common file-pattern structure:
├── readme.md # Information about the test to be injected into index.liquid
├── index.liquid # Markup for the test or a starting page
├── index.test.ts # Entry point script for the test (optional)
├── include
│ └── file.liquid # Optional include files used by the test case
├── pages
│ ├── page-a.liquid # Optional page A for testing navigation
│ ├── page-b.liquid # Optional page B for testing navigation
│ └── page-c.liquid # Optional page C for testing navigation
├── tests
│ ├── foo.liquid # Specific test-case or related content (optional)
│ └── foo.test.ts # Specific script for the test (optional)While this structure is recommended for consistency, all items labeled as optional can be omitted. The structure is flexible, allowing you to adapt it to your preferences and requirements.
The project is licensed under the Apache License, Version 2.0.