Native Vue Router

Native Vue Router is a gesture-first navigation runtime for Vue 3 and Vue Router 5. It keeps Vue Router in charge of matching, URLs, guards, and history while rendering live route stacks that can be manipulated interactively.

The repository includes a reusable headless core, a platform-adaptive visual preset, Capacitor and Electron adapters, and one messaging demo delivered as a PWA and through native hosts.

What works

• Interactive edge pop that can be held indefinitely at any progress.
• Ordered horizontal route paging with replace-by-default history.
• Component-originated route dragging with a live target route.
• Interactive push, adjacent-page sibling slide, modal, sheet, fade, and application-defined presentations.
• Concurrent from and to routes using only public Vue Router 5 APIs.
• Guarded commits: previews do not alter the URL, and rejected navigation springs back.
• Cold-start predictive back through declared parent routes.
• Bounded live view caching, nested router views, focus isolation, RTL, and reduced motion.
• PWA, Electron, and Capacitor iOS/Android hosts.

Run it

npm install
npm run dev

The default app is the installable messaging PWA. Other useful commands:

npm run build          # packages, declarations, demo, and service worker
npm test               # core transaction tests
npm run test:e2e       # desktop and mobile Playwright projects
npm run electron       # build and launch the Electron host
npm run cap:sync       # build and synchronize iOS and Android projects

Native projects live under apps/capacitor/ios and apps/capacitor/android. Open or run them from apps/capacitor with npx cap open ios, npx cap open android, or npx cap run <platform>.

Test the installed iOS PWA

Run the normal npm run dev command, expose its printed network address through an HTTPS URL, and open that URL on the iPhone. The development server includes the PWA service worker and already listens on the local network. Safari still requires a secure context for the service worker; a plain LAN http:// address is not sufficient. Choose Share → Add to Home Screen, then launch NVR Messenger from its Home Screen icon.

The Navigation Lab reports Standalone, ready, and App reserved when the correct environment is active. Open a conversation and drag from the extreme left edge. The “Leading-edge touches claimed” counter should increment while the router renders its live predictive-back view.

An installed web app cannot access WKWebView.allowsBackForwardNavigationGestures. The demo therefore reserves leading-edge touch sequences at the web-content boundary as an iOS standalone-only safeguard. Capacitor remains the deterministic option when native-level gesture suppression is required.

Minimal integration

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { createNativeRouter } from '@native-vue-router/core'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home },
    {
      path: '/chat/:id',
      component: Chat,
      meta: {
        native: { presentation: 'push', parent: '/', gesture: 'edge' },
      },
    },
  ],
})

const nativeRouter = createNativeRouter({ router })
createApp(App).use(router).use(nativeRouter).mount('#app')

<script setup lang="ts">
import { NativeGestureLink, NativeNavigator, NativeRouterView } from '@native-vue-router/core'
</script>

<template>
  <NativeNavigator :siblings="['/', '/stories', '/profile']">
    <NativeRouterView />
  </NativeNavigator>
  <NativeGestureLink to="/chat/maya" presentation="reveal">
    Drag this row into the chat route
  </NativeGestureLink>
</template>

Import @native-vue-router/core/style.css for the built-in presentation layers. The demo imports @native-vue-router/preset-native/style.css as well.

Use nativeRouter.sibling(to) for tab or peer-route navigation. Direction is derived from siblingOrder, repeated navigation to the active route is a no-op, and siblingHistory: 'replace' keeps cached tab views out of the back stack.

Packages

• @native-vue-router/core — transactions, route ledger, concurrent views, gestures, caching, and public components/composables.
• @native-vue-router/preset-native — adaptive tab/back controls, safe-area CSS, and platform motion defaults.
• @native-vue-router/capacitor — hardware back, deep links, pause cancellation, root exit, and haptics.
• @native-vue-router/electron — Chromium history-gesture suppression and renderer back/forward bridging.

See architecture and platform integration for the transaction lifecycle and host-specific behavior.

Support contract

The target is Vue 3.5+ and Vue Router 5. Installed PWAs, current Electron, and Capacitor 8 are first-class. Normal browser tabs remain functional but browsers can reserve edge gestures that page content cannot consistently override.

MIT