vue-page-stack

vue-page-stack currently targets Vue 3. For the Vue 2 version, see v1.5.0.

English | 简体中文

A Vue 3 SPA navigation stack that preserves route state in stack order, so back navigation feels closer to a native app than a full page remount.

Example

preview

demo code

Features

• Works on top of vue-router without changing your route definitions
• Stores newly rendered pages on push and forward
• Restores previous pages from the stack on back and go(-n) so local UI state can survive
• Removes unreachable pages from the stack after back navigation
• Replaces the current stack entry on replace
• Emits back and forward events for direction-aware transitions
• Supports browser back and forward buttons

Compared with KeepAlive

• VuePageStack manages pages in navigation order instead of providing include, exclude, or max
• KeepAlive keeps previously cached pages around until they are evicted; VuePageStack trims pages that are no longer reachable in the stack
• Navigating to the same route again creates a fresh page, while returning to an earlier page restores its cached instance

Installation and use

Installation

pnpm install vue-page-stack

Use

import { createApp } from 'vue';
import { VuePageStackPlugin } from 'vue-page-stack';

const app = createApp(App);

app.use(VuePageStackPlugin, { router });

<template>
  <router-view v-slot="{ Component }">
    <vue-page-stack @back="onBack" @forward="onForward">
      <component :is="Component" :key="$route.fullPath" />
    </vue-page-stack>
  </router-view>
</template>

<script setup>
const onBack = () => {
  console.log('back');
};

const onForward = () => {
  console.log('forward');
};
</script>

Use a stable route key on the rendered route component. In most apps, $route.fullPath is the safest default because it treats different params and query strings as distinct stack entries.

API

Install

Use app.use to install vue-page-stack.

import { VuePageStackPlugin } from 'vue-page-stack';

//...
app.use(VuePageStackPlugin, { router });

Options:

| Attribute | Description | Type | Accepted Values | Default | | --------- | ----------- | ---- | --------------- | ------- | | router | vue-router instance | Router | router created by createRouter | required |

Events

Use the back and forward events to react to navigation direction changes.

<vue-page-stack @back="onBack" @forward="onForward">
  <component :is="Component" :key="$route.fullPath" />
</vue-page-stack>

Notes

• The default slot should render a single route component vnode for stack behavior to apply
• Multiple slot children are passed through unchanged
• The implementation depends on Vue renderer internals, so upgrades should be validated with the test suite

Example app

Development

pnpm install
pnpm run build
pnpm run lint
pnpm run test:run
pnpm run test:coverage

dist/ is treated as a release artifact and is generated automatically by npm pack / npm publish through the prepack script, so it does not need to stay checked in during normal development.

Documentation

• Architecture and maintenance notes: docs/ARCHITECTURE.md

Notes

Changelog

Release-by-release changes are documented in the release notes.

Principle

The page instance management model is inspired by Vue's KeepAlive implementation.

Thanks

This plugin draws on both vue-navigation and vue-nav. Thanks for the inspiration.

Contributors ✨

Thanks goes to these wonderful people (emoji key):