Vue Flow Builder Expert

Expert guidance for building flow-based applications using vue-flow with TypeScript, Vue 3, and modern tooling.

Description

This skill provides best practices for developing flow-based applications with vue-flow, leveraging Vue 3 Composition API, TypeScript, Vite, Pinia for state management, and Tailwind CSS for styling. Optimized for maintainability, performance, and developer experience.

Instructions

Code Style and Structure

1. **Write concise, maintainable TypeScript code**

- Use functional and declarative programming patterns

- Avoid classes; prefer composition

- Follow DRY principles through iteration and modularization

- Use descriptive variable names with auxiliary verbs (e.g., `isFlowReady`, `hasNodeError`)

- Organize files systematically: one concern per file (component + helpers + types)

2. **Naming Conventions**

- Use lowercase with dashes for directories: `components/flow-builder`

- Prefer named exports for components

- Use clear, semantic names for flow nodes and edges

3. **TypeScript Usage**

- Use TypeScript for all code

- Prefer `interface` over `type`

- Avoid `enum`; use `const` objects or maps instead

- Define interfaces for flow nodes, edges, and custom data structures

Vue.js Conventions

1. **Always use Vue 3 Composition API with `<script setup>`**

```vue

<script setup lang="ts">

import { ref, computed } from 'vue'

import { VueFlow } from '@vue-flow/core'

interface FlowNode {

id: string

type: string

position: { x: number; y: number }

data: Record<string, unknown>

}

const nodes = ref<FlowNode[]>([])

</script>

```

2. **Use `function` keyword for pure functions**

- Benefits from hoisting and clarity

- Example: `function calculateNodePosition(index: number) { ... }`

3. **Leverage VueUse utilities**

- Use `@vueuse/core` functions for reactivity, DOM interactions, and lifecycle management

- Example: `useElementSize`, `useWindowSize`, `useDebounce`

Vue Flow Best Practices

1. **Define custom node types clearly**

- Create reusable node components in `components/flow-nodes/`

- Register custom nodes with vue-flow

- Use TypeScript interfaces for node data structures

2. **Handle flow state with Pinia**

- Create a flow store for nodes, edges, and flow state

- Keep flow logic separate from UI components

- Example store structure:

```typescript

import { defineStore } from 'pinia'

import { ref } from 'vue'

export const useFlowStore = defineStore('flow', () => {

const nodes = ref([])

const edges = ref([])

function addNode(node) { ... }

function removeNode(id) { ... }

return { nodes, edges, addNode, removeNode }

})

```

3. **Optimize flow rendering**

- Use `fitView` for initial positioning

- Implement viewport restrictions if needed

- Lazy load node types for large flows

UI and Styling

1. **Use Shadcn UI and Tailwind CSS**

- Build flow controls and panels with Shadcn components

- Use Tailwind utility classes for styling

- Implement responsive design with mobile-first approach

2. **Style custom nodes consistently**

- Use Tailwind classes within node components

- Maintain visual hierarchy

- Ensure sufficient contrast and touch targets

Performance Optimization

1. **Optimize bundle size**

- Implement code splitting in Vite config

- Lazy load non-critical flow node types

- Use dynamic imports for heavy components

2. **Image and asset optimization**

- Use WebP format for images

- Implement lazy loading

- Include size data to prevent layout shifts

3. **Wrap async components in Suspense**

```vue

<Suspense>

<template #default>

<FlowBuilder />

</template>

<template #fallback>

<LoadingSpinner />

</template>

</Suspense>

```

4. **Monitor Web Vitals**

- Optimize LCP, CLS, and FID

- Use Lighthouse or WebPageTest for auditing

State Management

1. **Use Pinia for global flow state**

- Store nodes, edges, and flow configuration

- Keep flow history for undo/redo

- Persist flow state when needed

2. **Use `nuqs` for URL search parameters**

- Sync flow ID or view state to URL

- Enable shareable flow links

Key Conventions

Examples

Basic Flow Setup

```vue

<script setup lang="ts">

import { ref } from 'vue'

import { VueFlow, useVueFlow } from '@vue-flow/core'

import '@vue-flow/core/dist/style.css'

const nodes = ref([

{ id: '1', type: 'input', position: { x: 0, y: 0 }, data: { label: 'Start' } }

])

const edges = ref([])

const { fitView } = useVueFlow()

onMounted(() => {

fitView()

})

</script>

<template>

<VueFlow :nodes="nodes" :edges="edges" />

</template>

```

Custom Node Component

```vue

<script setup lang="ts">

import { Handle, Position } from '@vue-flow/core'

interface Props {

data: {

label: string

status: 'idle' | 'running' | 'complete'

}

}

defineProps<Props>()

</script>

<template>

<div class="px-4 py-2 rounded-lg border-2 bg-white shadow-sm">

<Handle :position="Position.Left" type="target" />

<div class="font-medium">{{ data.label }}</div>

<div class="text-sm text-gray-500">{{ data.status }}</div>

<Handle :position="Position.Right" type="source" />

</div>

</template>

```

Constraints