@virou/nuxt 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,335 @@
+# 🧭 Virou
+
+<p>
+  <a href="https://www.npmjs.com/package/@virou/core"><img src="https://img.shields.io/npm/v/@virou/core.svg?style=flat&colorA=18181B&colorB=39737d" alt="Version"></a>
+  <a href="https://www.npmjs.com/package/@virou/core"><img src="https://img.shields.io/npm/dm/@virou/core.svg?style=flat&colorA=18181B&colorB=39737d" alt="Downloads"></a>
+  <a href="https://bundlephobia.com/package/@virou/core"><img src="https://img.shields.io/bundlephobia/min/@virou/core?style=flat&colorA=18181B&colorB=39737d" alt="Bundle Size"></a>
+  <a href="https://github.com/tankosinn/virou/tree/main/LICENSE"><img src="https://img.shields.io/github/license/tankosinn/virou.svg?style=flat&colorA=18181B&colorB=39737d" alt="License"></a>
+</p>
+
+Virou is a high-performance, lightweight virtual router for Vue with dynamic routing capabilities.
+
+> Perfect for modals, wizards, embeddable widgets, or any scenario requiring routing without altering the browser's URL or history.
+
+## ✨ Features
+
+- 🪄 **Dynamic Virtual Routing**: Navigate without altering the browser's URL or history
+- 🍂 **Multiple Router Instances**: Manage independent routing contexts within the same app
+- 🪆 **Nested Routing**: Seamlessly handle complex, nested routes
+- 🦾 **Type-Safe**: Written in [TypeScript](https://www.typescriptlang.org/)
+- ⚡ **SSR-Friendly**: Compatible with server-side rendering
+
+## 🐣 Usage
+```vue
+<script setup lang="ts">
+import { useVRouter } from '@virou/core'
+
+// Define your routes
+const routes = [
+  {
+    path: '/',
+    component: () => import('./views/Home.vue'),
+  },
+  {
+    path: '/about',
+    component: () => import('./views/About.vue'),
+  },
+]
+
+// Create a virtual router instance
+const { router, route } = useVRouter(routes)
+</script>
+
+<template>
+  <!-- Renders the current route's component -->
+  <VRouterView />
+</template>
+```
+
+## 📦 Installation
+
+Install Virou with your package manager:
+
+```bash
+pnpm add @virou/core
+```
+
+Register the `virou` plugin in your Vue app:
+
+```typescript
+import { virou } from '@virou/core'
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App)
+  .use(virou)
+  .mount('#app')
+```
+
+### 🧩 Using with Nuxt
+
+Install Virou Nuxt module with your package manager:
+
+```bash
+pnpm add @virou/nuxt
+```
+
+Add the module to your Nuxt configuration:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@virou/nuxt',
+  ],
+})
+```
+
+## 🧱 Essentials
+
+### 🌿 Routes
+
+Declare your routes as an array of objects with required `path` and `component`, and optional `meta` and `children` properties.
+
+```typescript
+const routes: VRouterRaw[] = [
+  {
+    path: '/', // static path
+    component: Home,
+  },
+  {
+    path: '/user/:id', // dynamic path with parameter
+    component: () => import('./views/User.vue'),
+    meta: {
+      foo: 'bar',
+    }
+  },
+  {
+    path: '/**:notFound', // Named wildcard path
+    component: defineAsyncComponent(() => import('./views/NotFound.vue')),
+  }
+]
+```
+
+**Props**:
+- `path`: the URL pattern to match. Supports:
+  - Static ("/about") for exact matches
+  - Dynamic ("/user/:id") for named parameters
+  - Wildcard ("/**") for catch-all segments
+  - Named wildcard ("/**:notFound") for catch-all with a name
+- `component`: the Vue component to render when this route matches. Can be synchronous or an async loader.
+- `meta`: metadata for the route.
+- `children`: an array of child routes.
+
+> Virou uses [rou3](https://github.com/h3js/rou3) under the hood for create router context and route matching.
+
+### 🪆 Nested Routes
+
+To define nested routes, add a children array to a route record. Child path values are relative to their parent (leading `/` is ignored).
+
+```typescript
+const routes: VRouterRaw[] = [
+  // ...
+  {
+    path: '/user/:id',
+    component: User,
+    children: [
+      {
+        path: '', // /user/:id  -> default child route
+        component: UserProfile,
+      },
+      {
+        path: '/settings', // /user/:id/settings
+        component: UserSettings,
+        children: [
+          {
+            path: '/', // /user/:id/settings -> deep default child route
+            component: UserSettingsGeneral,
+          },
+          {
+            path: '/notifications', // /user/:id/settings/notifications
+            component: UserSettingsNotifications,
+          },
+        ],
+      },
+    ]
+  },
+  // ...
+]
+```
+
+### 🌳 Router
+
+Create (or access) a virtual router instance with `useVRouter` composable.
+
+```typescript
+const { router, route } = useVRouter('my-wizard', routes)
+```
+
+> `useVRouter` must be called inside `setup()`.
+
+**Params:**
+- `key`: a unique key for the router instance. If you do not provide a key, Virou will generate one via `useId()`.
+- `routes`: an array of route objects.
+- `options`:
+  - `initialPath`: the path to render on initialization (defaults to `/`).
+
+**Returns:**
+- `route`: a Vue shallow ref that contains the current route object.
+  ```typescript
+  export interface VRoute {
+    fullPath: string
+    path: string
+    search: string
+    hash: string
+    meta?: Record<PropertyKey, unknown>
+    params?: Record<string, string>
+    _renderList: Component[] | null
+  }
+  ```
+- `router`:
+  - `replace(path: string): void`: navigate to a new path.
+  - `addRoute(route: VRouteRaw): void`: add a route at runtime.
+
+#### 🍃 Multiple Router Instances
+
+Virou allows you to create multiple independent router instances within the same app.
+
+```vue
+<script setup lang="ts">
+// Settings modal router
+useVRouter('settings-modal', [
+  {
+    path: '/profile',
+    component: UserProfile,
+  },
+  {
+    path: '/preferences',
+    component: UserPreferences,
+  },
+  // ...
+], { initialPath: '/profile' })
+
+// Onboarding wizard router
+useVRouter('onboarding-wizard', [
+  {
+    path: '/profile',
+    component: OnboardingProfile,
+  },
+  {
+    path: '/teamspace',
+    component: OnboardingTeamspace,
+  },
+  // ...
+], { initialPath: '/profile' })
+</script>
+
+<template>
+  <SettingsModal>
+    <VRouterView router-key="settings-modal" />
+  </SettingsModal>
+
+  <Wizard>
+    <VRouterView router-key="onboarding-wizard" />
+  </Wizard>
+</template>
+```
+
+## 📺 Rendering
+
+`<VRouterView>` mounts the matched component at its current nesting depth.
+
+```vue
+<template>
+  <VRouterView router-key="my-router">
+    :keep-alive="true"     <!-- preserve component state -->
+    :view-key="(route, key) => `${key}|${route.fullPath}`" <!-- custom vnode key -->
+    >
+    <!-- default slot receives { Component, route } -->
+    <template #default="{ Component, route }">
+      <Transition name="fade" mode="out-in">
+        <component :is="Component" v-bind="route.params" />
+      </Transition>
+    </template>
+
+    <!-- fallback slot shown while async loader resolves -->
+    <template #fallback>
+      <div class="spinner">
+        Loading...
+      </div>
+    </template>
+  </VRouterView>
+</template>
+```
+
+**Props:**
+- `routerKey`: key of the router instance to render. If not provided, uses the nearest router instance.
+- `keepAlive`: wraps the rendered component in `<KeepAlive>` when set to true, preserving its state across navigations.
+- `viewKey`: accepts either a string or a function `(route, key) => string` to compute the vnode key for the rendered component.
+
+**Slots:**
+- `default`: slot receives `{ Component, route }` so you can wrap or decorate the active component.
+- `fallback`: receives `{ route }` and is displayed inside `<Suspense>` while an async component is resolving.
+
+> Virou wraps components in `<Suspense>` by default. To combine `<Suspense>` with other components, see the [Vue docs](https://vuejs.org/guide/built-ins/suspense#combining-with-other-components).
+
+## 🛠️ Advanced
+
+### 🌐 Global Routers
+
+By default, routers created with `useVRouter(key, routes)` are disposable—they unregister themselves automatically once no components reference them.
+
+To keep a router alive for your app’s entire lifecycle, register it as a global router.
+
+#### Plugin-Registered Globals
+
+Defined routers in the `virou` plugin options are registered as global routers:
+
+```ts
+createApp(App)
+  .use(virou, {
+    routers: {
+      'embedded-widget-app': {
+        routes: [
+          { path: '/chat', component: () => import('./views/Chat.vue') },
+          { path: '/settings', component: () => import('./views/Settings.vue') },
+        ],
+        options: { initialPath: '/chat' }
+      },
+      // add more global routers here...
+    }
+  })
+  .mount('#app')
+```
+
+Later:
+
+```ts
+const { router, route } = useVRouter('embedded-widget-app')
+```
+
+#### Runtime-Registered Globals
+
+You may also mark a router as global at runtime by passing the `_isGlobal` option:
+
+```ts
+useVRouter(routes, { _isGlobal: true })
+```
+
+That router will stay registered even after components that use it unmount.
+
+### 🧪 Create Standalone Virtual Router
+
+You can create a standalone virtual router with `createVRouter`:
+
+```ts
+export function useCustomRouter() {
+  const { router, route } = createVRouter(routes)
+
+  // Custom logic here...
+}
+```
+
+## 📝 License
+
+[MIT License](https://github.com/tankosinn/virou/blob/main/LICENSE)

package/dist/module.d.mts

@@ -1,5 +1,14 @@
-import * as nuxt_schema from 'nuxt/schema';
+import * as _nuxt_schema from '@nuxt/schema';
+import { VirouPluginOptions } from '@virou/core';
 
-declare const _default: nuxt_schema.NuxtModule<nuxt_schema.ModuleOptions, nuxt_schema.ModuleOptions, false>;
+interface ModuleOptions extends VirouPluginOptions {
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
-export { _default as default };
+declare module '@nuxt/schema' {
+    interface PublicRuntimeConfig {
+        virou?: ModuleOptions;
+    }
+}
+
+export { type ModuleOptions, _default as default };

package/dist/module.json

@@ -1,9 +1,9 @@
 {
-  "name": "virou",
+  "name": "@virou/nuxt",
   "configKey": "virou",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "builder": {
-    "@nuxt/module-builder": "0.8.4",
-    "unbuild": "3.3.1"
+    "@nuxt/module-builder": "1.0.1",
+    "unbuild": "3.5.0"
   }
 }

package/dist/module.mjs

@@ -1,4 +1,5 @@
-import { defineNuxtModule, addImports, addComponent } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addPlugin, addImports, addComponent } from '@nuxt/kit';
+import { defu } from 'defu';
 
 const functions = [
   "useVRouter"
@@ -8,14 +9,18 @@ const components = [
 ];
 const module = defineNuxtModule({
   meta: {
-    name: "virou"
+    name: "@virou/nuxt",
+    configKey: "virou"
   },
-  setup(_options, _nuxt) {
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.virou = defu(nuxt.options.runtimeConfig.public.virou, options);
+    addPlugin(resolver.resolve("./runtime/plugin"));
     functions.forEach((name) => {
       addImports({ name, as: name, from: "@virou/core", priority: -1 });
     });
     components.forEach((name) => {
-      void addComponent({ name, export: name, filePath: "@virou/core", priority: -1 });
+      addComponent({ name, export: name, filePath: "@virou/core", priority: -1 });
     });
   }
 });

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,6 @@
+import { virou } from "@virou/core";
+import { defineNuxtPlugin, useRuntimeConfig } from "nuxt/app";
+export default defineNuxtPlugin((nuxtApp) => {
+  const options = useRuntimeConfig().public.virou;
+  nuxtApp.vueApp.use(virou, options);
+});

package/dist/types.d.mts

@@ -1,7 +1 @@
-import type { NuxtModule } from '@nuxt/schema'
-
-import type { default as Module } from './module.js'
-
-export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
-
-export { default } from './module.js'
+export { type ModuleOptions, default } from './module.mjs'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@virou/nuxt",
   "type": "module",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Virou Nuxt Module",
   "author": "Tankosin<https://github.com/tankosinn>",
   "license": "MIT",
@@ -25,28 +25,25 @@
   ],
   "sideEffects": false,
   "exports": {
-    ".": {
-      "types": "./dist/types.d.ts",
-      "import": "./dist/module.mjs",
-      "require": "./dist/module.cjs"
-    }
+    "types": "./dist/types.d.mts",
+    "default": "./dist/module.mjs"
   },
-  "main": "./dist/module.cjs",
-  "types": "./dist/types.d.ts",
+  "main": "./dist/module.mjs",
   "files": [
     "dist"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.12.0"
   },
   "dependencies": {
-    "@nuxt/kit": "^3.15.2",
-    "@virou/core": "0.1.0"
+    "@nuxt/kit": "^3.17.2",
+    "defu": "^6.1.4",
+    "@virou/core": "1.0.0"
   },
   "devDependencies": {
-    "@nuxt/module-builder": "0.8.4",
-    "@nuxt/schema": "3.15.2",
-    "nuxt": "3.15.2"
+    "@nuxt/module-builder": "1.0.1",
+    "@nuxt/schema": "3.17.2",
+    "nuxt": "3.17.2"
   },
   "scripts": {
     "build": "nuxt-module-build build"

package/dist/module.cjs

@@ -1,5 +0,0 @@
-module.exports = function(...args) {
-  return import('./module.mjs').then(m => m.default.call(this, ...args))
-}
-const _meta = module.exports.meta = require('./module.json')
-module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.ts

@@ -1,5 +0,0 @@
-import * as nuxt_schema from 'nuxt/schema';
-
-declare const _default: nuxt_schema.NuxtModule<nuxt_schema.ModuleOptions, nuxt_schema.ModuleOptions, false>;
-
-export { _default as default };

package/dist/types.d.ts

@@ -1,7 +0,0 @@
-import type { NuxtModule } from '@nuxt/schema'
-
-import type { default as Module } from './module'
-
-export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
-
-export { default } from './module'