Flows and Automation

Without Flows:
1. Create component file
2. Add boilerplate code
3. Create test file
4. Add test boilerplate
5. Create styles file
6. Update exports

With Flow "Create React Component":
1. Run flow
2. Enter component name
3. All files created instantly

Cmd/Ctrl+Shift+P → "Flows: Open Panel"

1. Open Flows panel
2. Select flow (e.g., "Create React Component")
3. Enter parameters:
   - Component name: UserProfile
   - Include tests: Yes
   - Include styles: CSS Modules
4. Click "Run"
5. Files are created

name: Create React Component
inputs:
  - name: componentName
    type: string
    prompt: "Component name"
  - name: includeTests
    type: boolean
    default: true
  - name: styling
    type: select
    options: ["none", "css", "css-modules", "styled-components"]

outputs:
  - path: components/{{componentName}}/{{componentName}}.tsx
  - path: components/{{componentName}}/{{componentName}}.test.tsx
    condition: includeTests
  - path: components/{{componentName}}/{{componentName}}.module.css
    condition: styling == "css-modules"

components/
└── UserProfile/
    ├── UserProfile.tsx
    ├── UserProfile.test.tsx
    └── UserProfile.module.css

Route name: users
Methods: GET, POST
Validation: Yes (Zod)

// app/api/users/route.ts
import { NextResponse } from 'next/server'
import { z } from 'zod'

const userSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
})

export async function GET() {
  const users = await prisma.user.findMany()
  return NextResponse.json(users)
}

export async function POST(request: Request) {
  const body = await request.json()
  const validated = userSchema.parse(body)
  const user = await prisma.user.create({ data: validated })
  return NextResponse.json(user, { status: 201 })
}

Feature name: subscription
Include: model, service, api, ui, tests

src/
├── prisma/
│   └── migrations/add_subscription/
├── services/
│   └── subscription.service.ts
├── app/api/subscriptions/
│   ├── route.ts
│   └── [id]/route.ts
├── components/
│   └── Subscription/
│       ├── SubscriptionCard.tsx
│       └── SubscriptionForm.tsx
├── types/
│   └── subscription.ts
└── tests/
    └── subscription/
        ├── subscription.service.test.ts
        └── subscription.api.test.ts

.windsurf/
└── flows/
    ├── create-feature.yaml
    ├── add-endpoint.yaml
    └── generate-types.yaml

# .windsurf/flows/create-feature.yaml
name: Create Feature
description: Scaffold a complete feature with all components
version: 1.0.0

inputs:
  - name: featureName
    type: string
    prompt: "Feature name (e.g., 'subscription')"
    validate: "^[a-z][a-z0-9-]*$"

  - name: includeAPI
    type: boolean
    prompt: "Include API routes?"
    default: true

  - name: includeUI
    type: boolean
    prompt: "Include UI components?"
    default: true

steps:
  - action: create_file
    path: "services/{{featureName}}.service.ts"
    template: service.template.ts

  - action: create_file
    path: "types/{{featureName}}.ts"
    template: types.template.ts

  - action: create_file
    path: "app/api/{{featureName}}/route.ts"
    template: api-route.template.ts
    condition: "{{includeAPI}}"

  - action: create_directory
    path: "components/{{featureName | pascalCase}}"
    condition: "{{includeUI}}"

  - action: create_file
    path: "components/{{featureName | pascalCase}}/{{featureName | pascalCase}}.tsx"
    template: component.template.tsx
    condition: "{{includeUI}}"

  - action: run_command
    command: "npm run lint:fix"

// .windsurf/templates/service.template.ts
import { prisma } from '@/lib/prisma'
import type { {{featureName | pascalCase}} } from '@/types/{{featureName}}'

export class {{featureName | pascalCase}}Service {
  async findAll(): Promise<{{featureName | pascalCase}}[]> {
    return prisma.{{featureName}}.findMany()
  }

  async findById(id: string): Promise<{{featureName | pascalCase}} | null> {
    return prisma.{{featureName}}.findUnique({ where: { id } })
  }

  async create(data: Omit<{{featureName | pascalCase}}, 'id'>): Promise<{{featureName | pascalCase}}> {
    return prisma.{{featureName}}.create({ data })
  }

  async update(id: string, data: Partial<{{featureName | pascalCase}}>): Promise<{{featureName | pascalCase}}> {
    return prisma.{{featureName}}.update({ where: { id }, data })
  }

  async delete(id: string): Promise<void> {
    await prisma.{{featureName}}.delete({ where: { id } })
  }
}

- action: create_file
  path: "path/to/file.ts"
  template: template-file.ts
  overwrite: false  # Don't overwrite if exists

- action: create_directory
  path: "path/to/directory"

- action: run_command
  command: "npm install some-package"
  cwd: "{{workspaceRoot}}"

- action: modify_file
  path: "package.json"
  operation: json_merge
  data:
    scripts:
      "{{featureName}}:dev": "..."

- action: cascade_prompt
  prompt: |
    Create a README for the {{featureName}} feature.
    Include usage examples and API documentation.
  output: "docs/{{featureName}}.md"

- action: create_file
  path: "tests/{{name}}.test.ts"
  condition: "{{includeTests}}"

- action: create_file
  path: "{{name}}.styles.ts"
  condition: "{{styling == 'styled-components'}}"

- action: create_file
  path: "{{name}}.module.css"
  condition: "{{styling == 'css-modules'}}"

.windsurf/
└── flows/
    └── team-flows/
        ├── create-feature.yaml
        ├── add-migration.yaml
        └── README.md

Flows Panel → Your Flow → Export

Flows Panel → Import → Select .flow file

# v1: Simple
steps:
  - action: create_file
    path: "components/{{name}}.tsx"
    template: component.tsx

# v2: Add options
inputs:
  - name: includeTests
    type: boolean
    default: true

# v3: Add conditional steps
# v4: Add post-processing

# ❌
name: cf

# ✅
name: Create React Feature Component
description: Creates a feature component with tests, styles, and stories

inputs:
  - name: componentName
    validate: "^[A-Z][a-zA-Z0-9]*$"
    errorMessage: "Component name must be PascalCase"

name: Create API Endpoint
description: |
  Creates a complete API endpoint with:
  - Route handler
  - Input validation
  - Error handling
  - TypeScript types

  Usage: Run this flow and provide the endpoint name.

1. Check file location (.windsurf/flows/)
2. Verify YAML syntax
3. Reload Windsurf

1. Check template path
2. Verify variable names match inputs
3. Test helpers (pascalCase, etc.)

1. Check boolean vs string comparison
2. Use correct syntax: {{variable == 'value'}}
3. Ensure input names match