Vue Integration Patterns

The @naylence/vue package provides a set of composables and components to integrate Naylence agents and fabric connectivity into Vue applications. This guide outlines the essential usage patterns for building Vue-based Naylence apps.

Installation

To get started, install the Vue integration package along with the Agent SDK:


npm install @naylence/vue

Fabric Provider

The foundation of any Naylence Vue application is the FabricProvider. It manages the lifecycle of the FameFabric instance, handling connection and cleanup automatically.

Wrap your application (or the part of it that needs connectivity) with FabricProvider:


<script setup>
  import { FabricProvider } from '@naylence/vue';
  import { clientConfig } from './config';
</script>
 
<template>
  <FabricProvider :opts="clientConfig">
    <YourAppContent />
  </FabricProvider>
</template>

Accessing Fabric State

Use the useFabric composable to access the current fabric instance and its connection status. Note that the returned values are Vue Refs.


<script setup>
  import { useFabric } from '@naylence/vue';
 
  const { fabric, status, error } = useFabric();
</script>
 
<template>
  <div v-if="error">Error: {{ error }}</div>
  <div v-else-if="status !== 'ready'">Connecting...</div>
  <div v-else>Connected to Fabric</div>
</template>

Consuming Remote Agents

The most common pattern for client-side components is to consume a remote agent. The useRemoteAgent composable simplifies creating a typed proxy to a remote service. It returns a ComputedRef that updates automatically when the fabric becomes ready.


<script setup lang="ts">
  import { useRemoteAgent } from '@naylence/vue';
  import type { HelloAgent } from './HelloAgent';
 
  // Get a typed proxy to the remote agent
  const agent = useRemoteAgent<HelloAgent>('hello@fame.fabric');
 
  const handleClick = async () => {
    if (!agent.value) return;
    const response = await agent.value.runTask({ message: 'Hello' });
    console.log(response);
  };
</script>
 
<template>
  <button @click="handleClick" :disabled="!agent">
    Call Agent
  </button>
</template>

Hosting Agents in the Browser

You can also host agents directly in the browser (e.g., for a Sentinel node or a peer-to-peer application). Use useFabricEffect to register the agent when the fabric becomes ready.


<script setup>
  import { useFabricEffect } from '@naylence/vue';
  import { MyLocalAgent } from './MyLocalAgent';
 
  useFabricEffect((fabric) => {
    const agent = new MyLocalAgent();
  
    // Serve the agent on the fabric
    fabric.serve(agent, 'my-service@fame.fabric');
  
    // Cleanup function (optional)
    return () => {
      // Custom cleanup if needed
    };
  }, []); // Dependencies
</script>
 
<template>
  <div>Service is running</div>
</template>

Configuration for Browser Communication

When hosting agents in the browser (e.g., a Sentinel node) and connecting to them from other components (Client nodes), you need to configure the BroadcastChannelListener and BroadcastChannelConnectionGrant.

This setup allows different parts of your application (or different tabs) to communicate via the browser’s BroadcastChannel API.

It is recommended to generate a unique channel name for each application session to prevent interference between multiple tabs running the same application.


import { generateId } from '@naylence/core';
 
// Generate a unique channel name for this page session
// This prevents interference between multiple tabs running the same app
const pageId = generateId();
const channelName = `default-${pageId}`;
 
// Sentinel (Host) Configuration
export const sentinelConfig = {
  rootConfig: {
    node: {
      type: 'Sentinel',
      requestedLogicals: ['fame.fabric'],
      listeners: [
        {
          type: 'BroadcastChannelListener',
          channelName,
        },
      ],
      security: {
        type: 'DefaultSecurityManager',
        security_policy: {
          type: 'NoSecurityPolicy',
        },
        authorizer: {
          type: 'NoopAuthorizer',
        },
      },
    },
  },
};
 
// Client Configuration
export const clientConfig = {
  rootConfig: {
    node: {
      hasParent: true,
      requestedLogicals: ['fame.fabric'],
      admission: {
        type: 'DirectAdmissionClient',
        connectionGrants: [
          {
            type: 'BroadcastChannelConnectionGrant',
            purpose: 'node.attach',
            channelName,
            ttl: 0,
            durable: false,
          },
        ],
      },
      security: {
        type: 'DefaultSecurityManager',
        security_policy: {
          type: 'NoSecurityPolicy',
        },
        authorizer: {
          type: 'NoopAuthorizer',
        },
      },
    },
  },
};

Agent Definition

Agents in Vue applications follow the same pattern as standard Naylence agents, extending BaseAgent.


import { BaseAgent } from '@naylence/agent-sdk';
 
export class HelloAgent extends BaseAgent {
  async runTask(payload: { message: string }): Promise<string> {
    return `Received: ${payload.message}`;
  }
}