Installation

SPX is available for consumption via the NPM registry as an ESM module and is designed for usage in Browser environments. SPX is lightweight with a distribution size of 15kb (gzipped) and ships with types included.

PNPM


$ pnpm add spx --save

NPM


$ npm install spx --save

YARN


$ yarn add spx

BUN


$ bun add spx

Bundling SPX

SPX is distributed as an ESM module, with the generated bundle compiled into ECMAScript 6 (ES6) from TypeScript. When bundling SPX and if you intend of leveraging to module as the core solution in your project, you’ll often yield the best results and overall productivity by using a single entry point and exporting the spx method as default.


import spx from 'spx';
export default spx({
  //
  // Options
  //
})(async function(session) {
  // The connect returns a callback function after
  // connection was established. Lets inspect the session:
  console.log(session);
  // You initialize third party JavaScript in this callback
  // It's the equivalent of DOMContentLoaded.
});

The recommended bundler to utilize with SPX is tsup, offering a lightweight and efficient addition to any JavaScript project. While Vite is favored by some developers, tsup stands out as a leaner and more versatile tool. Opting for tsup empowers independent OSS contributors, contributing to a more vibrant and diverse open-source ecosystem.

CDN USAGE

If you’re new to JavaScript or prefer a straightforward setup, you can easily integrate SPX into your website by fetching it from a CDN and dropping it into your project. Ensure that SPX is included before any other JavaScript files and add the <script type="module"> attribute to the script tag. By default, SPX will replace the entire <body> fragment during navigation.

Option 1

Importing SPX using the esm.sh CDN:


<head>
  <meta charset="UTF-8" />
  <title>SPX | Single Page XHR</title>
  <!-- Import the module and connect with spx() -->
  <script
    type="module"
    spx-eval="false">
    import spx from 'https://esm.sh/spx';
    spx({ /* options */})
  </script>
</head>
<body>
  <h1>Hello World</h1>
</body>

Option 2

Importing SPX using the unpkg.com CDN:


<head>
  <meta charset="UTF-8" />
  <title>SPX | Single Page XHR</title>
  <!-- Include the module and connect with spx() -->
  <script
    src="https://unpkg.com/spx"
    type="module"
    async="true"
    spx-eval="false">
    spx({ /* options */})
  </script>
</head>
<body>
  <h1>Hello World</h1>
</body>

Getting Help Connect