@route-weaver/vue
Version:
Vue integration for route-weaver
189 lines (131 loc) • 5.82 kB
Markdown
# @route-weaver/vue
[](https://badge.fury.io/js/@route-weaver%2Fvue)
[](https://opensource.org/licenses/MIT)
The official Vue integration for `route-weaver`. It offers a plugin and a set of Composables to integrate `route-weaver` into your Vue applications, providing a reactive and intuitive API with full typesafety.
## Why @route-weaver/vue?
Tired of string-based navigation and the runtime errors that come with it? `@route-weaver/vue` brings the power of TypeScript to your Vue routing, ensuring that your routes are always valid at compile-time. This means no more typos in route names, no more missing parameters, and a more robust and maintainable application. By leveraging Vue's reactivity system, it provides a seamless and intuitive developer experience.
## Installation
```bash
npm install @route-weaver/core @route-weaver/vue
```
## Setup
First, create your `routeWeaver` instance and install the Vue plugin in your `main.ts`.
```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { createRouteWeaver } from '@route-weaver/core';
import { createRouteWeaverVue } from '@route-weaver/vue';
const routeWeaver = createRouteWeaver({
home: { label: 'Home', path: '/' },
users: {
label: 'Users',
path: 'users',
children: {
view: { label: 'View User', path: ':id' },
},
},
});
const navInstance = routeWeaver.build({
main: ['home', 'users'],
});
const app = createApp(App);
app.use(createRouteWeaverVue(navInstance, routeWeaver));
app.mount('#app');
```
## Expanded API Reference
### `useNavigation(groupName)`
* **Why and When to Use**: Use this composable to get a reactive reference to a specific navigation group. It's ideal for building dynamic navigation menus that automatically update when the underlying data changes.
* **`groupName`**: The name of the navigation group (e.g., `'main'`).
* **Returns**: A `Ref<StructuredNavItem[]>` for the specified group.
**Practical Example**:
```vue
<script setup lang="ts">
import { useNavigation } from '@route-weaver/vue';
const mainNav = useNavigation('main');
</script>
<template>
<nav>
<router-link v-for="item in mainNav" :key="item.id" :to="item.fullPath">
{{ item.label }}
</router-link>
</nav>
</template>
```
---
### `useActiveRoute()`
* **Why and When to Use**: Use this composable to get a computed property for the active route. This is useful for displaying details about the current page, highlighting active links, or conditionally rendering components based on the current route.
* **Returns**: A `ComputedRef<ActiveRoute | undefined>`.
**Practical Example**:
```vue
<script setup lang="ts">
import { useActiveRoute } from '@route-weaver/vue';
const activeRoute = useActiveRoute();
</script>
<template>
<h1 v-if="activeRoute">{{ activeRoute.route.label }}</h1>
</template>
```
---
### `useBreadcrumbs()`
* **Why and When to Use**: Use this composable to get a computed property for the breadcrumb trail of the active route. It's the perfect tool for building breadcrumb navigation components that help users orient themselves within your app.
* **Returns**: A `ComputedRef<StructuredNavItem[]>`.
**Practical Example**:
```vue
<script setup lang="ts">
import { useBreadcrumbs } from '@route-weaver/vue';
const breadcrumbs = useBreadcrumbs();
</script>
<template>
<nav>
<span v-for="(crumb, index) in breadcrumbs" :key="crumb.id">
<router-link :to="crumb.fullPath">{{ crumb.label }}</router-link>
<span v-if="index < breadcrumbs.length - 1"> > </span>
</span>
</nav>
</template>
```
---
### `useBuildPath()`
* **Why and When to Use**: This is your go-to composable for creating typesafe links. It provides the `buildPath` function, which ensures that you can only build URLs for routes that actually exist and that you provide all the necessary parameters. This eliminates a whole class of common routing errors.
* **Returns**: The `buildPath(routeId, params)` function.
**Practical Example**:
```vue
<script setup lang="ts">
import { useBuildPath } from '@route-weaver/vue';
const buildPath = useBuildPath();
const userProfilePath = buildPath('users.view', { id: '42' });
</script>
<template>
<router-link :to="userProfilePath">View User Profile</router-link>
</template>
```
## Before and After: The Typesafety Advantage
### Before: Risky, String-Based Paths
```vue
// This is not typesafe. If the route changes, this link will break silently.
const userProfilePath = `/users/123`;
```
This is brittle. A typo or a change in the route structure leads to runtime errors.
### After: Reactive, Typesafe, and Error-Free
```vue
<script setup lang="ts">
import { useBuildPath } from '@route-weaver/vue';
const buildPath = useBuildPath();
// ✅ Correct: Autocompletion for 'users.view' and 'id'.
const userDetailPath = buildPath('users.view', { id: '123' });
// ❌ Compile-Time Error: 'userId' is not a valid parameter.
// const invalidPath = buildPath('users.view', { userId: '123' });
// ❌ Compile-Time Error: 'posts' is not a valid route name.
// const nonExistentPath = buildPath('posts', { id: '456' });
</script>
```
Refactor with confidence. TypeScript will instantly flag any invalid `buildPath` calls.
## Live Examples
Explore interactive examples on CodeSandbox to see `@route-weaver/vue` in action.
* **Basic Setup**: [Link to CodeSandbox](https://codesandbox.io/p/sandbox/route-weaver-vue-example-y7qj9m)
* **Advanced Usage with Pinia**: [Link to CodeSandbox] (coming soon)
## Contributing
Contributions are welcome! Please see the main [CONTRIBUTING.md](../../CONTRIBUTING.md) file for details.
## License
MIT