https://github.com/lxsmnsyc/waystone
MPAs that feels like SPAs
https://github.com/lxsmnsyc/waystone
routing
Last synced: 24 days ago
JSON representation
MPAs that feels like SPAs
- Host: GitHub
- URL: https://github.com/lxsmnsyc/waystone
- Owner: lxsmnsyc
- License: mit
- Created: 2022-07-31T13:35:19.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2023-03-01T12:48:57.000Z (about 2 years ago)
- Last Synced: 2025-04-06T04:32:08.895Z (about 1 month ago)
- Topics: routing
- Language: TypeScript
- Homepage:
- Size: 957 KB
- Stars: 49
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# waystone
> MPAs that feels like SPA
[](https://www.npmjs.com/package/waystone) [](https://github.com/airbnb/javascript)
## Install
```bash
npm i waystone
```
```bash
yarn add waystone
```
```bash
pnpm add waystone
```
## Usage
```js
import 'waystone';
```
**NOTE**: Waystone is required to only run once, so it's ideal to serve it on JS files where the module is going to be instanciated once.
### Replace instead of Push
You can use `ws:replace` to replace the History state rather than push when navigating
```html
My page
```
### Scroll control
By default, anchor tags will scroll up instantly to the top of the page when navigated to. You can add `ws:scroll="none"` to preserve scroll or you can use `ws:scroll="smooth"` if you want the page to scroll up smoothly.
### Prefetch strategies
You can add one of the following attributes to your anchor tags prefetch strategies:
- `ws:animation-frame`: Prefetches through `requestAnimationFrame`
- `ws:delay="1000"`: Prefetches through `setTimeout`
- `ws:idle`: Prefetches through `requestIdleCallback`
- `ws:interaction`: Prefetches when the element receives focus, is hovered or about to be touched.
- `ws:load`: Prefetches after the current window has loaded.
- `ws:media="(orientation: portrait)"`: Prefetches using media query
- `ws:ready-state="interactive"`: Prefetches using `document.readyState`
- `ws:visible`: Prefetches when the element is visible in the viewport
### Opting-out
You can add `ws:disabled` to your anchor element.
```html
My Page
```
### Lifecycle Events
Waystone provides lifecycle events through `on`.
```js
import { on } from 'waystone';
on('unload', () => {
cleanupStuff();
});
```
Waystone lifecycle involves three steps:
- `beforeunload`: This is called before `unload` happens. In this event, you can cancel the navigation by calling `event.preventDefault()`
```js
on('beforeunload', (event) => {
const prompt = window.confirm('Are you sure you want to leave?');
if (!prompt) {
event.preventDefault();
}
})
```
- `unload`: This is called before the document is replaced.
- `load`: This is called after the document is replaced.
### DOM diffing
**Please use with caution!**
By default, waystone replaces the entire page when navigating to a new one, which means that every element from the previous page would get disposed. If you want to skip elements that are similar from the previous page (or any page), you can add `ws:diff` to your ``.
```html
...
```
`ws:diff` utilizes [`morphdom`](https://github.com/patrick-steele-idem/morphdom) and `DOMParser`.
The difference, however, would be:
- Scripts will no longer run on the new page.
- `window`'s `DOMContentLoaded` and `load` events wouldn't work.
## Live demos
- Basic Astro demo [](https://codesandbox.io/s/github/LXSMNSYC/waystone/tree/main/examples/demo)
- Astro Blog template demo [](https://codesandbox.io/s/github/LXSMNSYC/waystone/tree/main/examples/blogs-demo)
## Sponsors
## License
MIT © [lxsmnsyc](https://github.com/lxsmnsyc)