Windsurf

User: How do I add dark mode?
AI: Here's the code for dark mode... [shows snippet]
User: Where do I put it?
AI: In the ThemeProvider file...
User: And how do I update the components?
AI: You need to... [another instruction]

User: Add dark mode to the application

Cascade:
1. Analyzing project structure...
   → Found Next.js App Router with Tailwind
2. Checking current styling system...
   → Tailwind with next-themes will work best
3. Creating dark theme configuration...
   → Updating tailwind.config.ts
4. Adding ThemeProvider...
   → Creating providers/ThemeProvider.tsx
5. Updating layout...
   → Modifying app/layout.tsx
6. Adding toggle in Header...
   → Creating components/ThemeToggle.tsx
7. Testing changes...
   → Checking in browser

✓ Dark mode added. Modified files:
  - tailwind.config.ts
  - providers/ThemeProvider.tsx
  - app/layout.tsx
  - components/ThemeToggle.tsx
  - package.json (added next-themes)

User: Where are payments handled in this project?

Cascade:
I've analyzed the project structure. Payments are handled in:

1. API Endpoint: app/api/payments/route.ts
   - Creating Stripe sessions
   - Handling webhooks

2. Frontend: components/checkout/CheckoutForm.tsx
   - Payment form UI
   - Stripe Elements integration

3. Utils: lib/stripe.ts
   - Stripe client configuration
   - Helper functions

4. Types: types/payment.ts
   - TypeScript interfaces

Would you like me to explain the payment flow?

User: Create a new API endpoint for handling newsletters with validation and database storage

Cascade:
Creating a complete newsletter endpoint...

[Step 1] Creating validation schema with Zod
→ lib/validations/newsletter.ts

[Step 2] Creating Prisma model
→ Updating prisma/schema.prisma
→ Running: npx prisma generate

[Step 3] Creating API endpoint
→ app/api/newsletter/subscribe/route.ts

[Step 4] Adding error handling
→ lib/errors/newsletter-errors.ts

[Step 5] Creating tests
→ __tests__/api/newsletter.test.ts

[Step 6] Running tests
→ npm test newsletter

Done! Newsletter endpoint is working:
POST /api/newsletter/subscribe
Body: { email: "user@example.com", name?: "Jan" }

User: Find all places where we use useEffect without cleanup

Cascade:
Searching the project for useEffect without cleanup...

Found 7 problematic cases:

1. components/Chat.tsx:45
   useEffect(() => {
     socket.on('message', handleMessage)
   }, []) // Missing cleanup for socket listener

2. hooks/useWindowSize.ts:12
   useEffect(() => {
     window.addEventListener('resize', handler)
   }, []) // Missing cleanup for event listener

3. components/Timer.tsx:23
   useEffect(() => {
     const id = setInterval(tick, 1000)
   }, []) // Missing clearInterval

[... remaining cases ...]

Should I fix these issues automatically?

User: Configure the project for deployment on Vercel

Cascade:
Configuring the project for Vercel...

[Terminal] Checking if Vercel CLI is installed
→ vercel --version
→ Not found, installing...
→ npm install -g vercel

[Terminal] Logging into Vercel
→ vercel login
→ Open browser to log in

[File] Creating vercel.json with configuration
→ Setting Node.js 20, regions, redirects

[File] Updating .env.example
→ Adding variables required in production

[Terminal] Linking project
→ vercel link

[Terminal] Setting environment variables
→ vercel env add DATABASE_URL production

Project ready for deployment!
Run 'vercel --prod' to deploy.

User: Add pagination to the product list

Cascade [Write Mode]:
→ Modifying ProductList.tsx
→ Adding usePagination hook
→ Updating API endpoint
→ Creating Pagination component

User: [Chat Mode] Explain how this sorting algorithm works

Cascade [Chat Mode]:
This algorithm is QuickSort with the following optimizations...
[explanation without code modifications]

User: [Review] Check this PR for security issues

Cascade [Review Mode]:
Security analysis of PR #123:

⚠️ High risk:
1. SQL Injection on line 45
   Suggested fix: [code]

⚠️ Medium risk:
2. Missing rate limiting on endpoint
   Suggested fix: [code]

✓ Accept suggestions to apply them

# .windsurf/flows/new-component.yaml
name: New React Component
description: Creates a new React component with tests and storybook
author: team
version: 1.0.0

inputs:
  - name: componentName
    type: string
    description: Component name (PascalCase)
    required: true
  - name: withTests
    type: boolean
    default: true
  - name: withStorybook
    type: boolean
    default: true
  - name: componentType
    type: select
    options:
      - client
      - server
    default: client

steps:
  - name: Create component file
    action: create_file
    path: src/components/{{componentName}}/{{componentName}}.tsx
    template: |
      {{#if (eq componentType "client")}}
      'use client'

      {{/if}}
      import { cn } from '@/lib/utils'

      interface {{componentName}}Props {
        className?: string
        children?: React.ReactNode
      }

      export function {{componentName}}({ className, children }: {{componentName}}Props) {
        return (
          <div className={cn('', className)}>
            {children}
          </div>
        )
      }

  - name: Create index file
    action: create_file
    path: src/components/{{componentName}}/index.ts
    template: |
      export { {{componentName}} } from './{{componentName}}'

  - name: Create test file
    condition: "{{withTests}}"
    action: create_file
    path: src/components/{{componentName}}/{{componentName}}.test.tsx
    template: |
      import { render, screen } from '@testing-library/react'
      import { {{componentName}} } from './{{componentName}}'

      describe('{{componentName}}', () => {
        it('renders children correctly', () => {
          render(<{{componentName}}>Test content</{{componentName}}>)
          expect(screen.getByText('Test content')).toBeInTheDocument()
        })

        it('applies custom className', () => {
          const { container } = render(
            <{{componentName}} className="custom-class">Content</{{componentName}}>
          )
          expect(container.firstChild).toHaveClass('custom-class')
        })
      })

  - name: Create Storybook file
    condition: "{{withStorybook}}"
    action: create_file
    path: src/components/{{componentName}}/{{componentName}}.stories.tsx
    template: |
      import type { Meta, StoryObj } from '@storybook/react'
      import { {{componentName}} } from './{{componentName}}'

      const meta: Meta<typeof {{componentName}}> = {
        title: 'Components/{{componentName}}',
        component: {{componentName}},
        tags: ['autodocs'],
      }

      export default meta
      type Story = StoryObj<typeof {{componentName}}>

      export const Default: Story = {
        args: {
          children: '{{componentName}} content',
        },
      }

  - name: Update barrel export
    action: update_file
    path: src/components/index.ts
    insert_after: "// Components"
    content: |
      export { {{componentName}} } from './{{componentName}}'

# In Command Palette (Cmd+Shift+P)
> Windsurf: Run Flow

# Or directly
> Run Flow: New React Component

# Dialog:
Component Name: ProductCard
With Tests: ✓
With Storybook: ✓
Component Type: client

# Cascade executes the Flow:
→ Created src/components/ProductCard/ProductCard.tsx
→ Created src/components/ProductCard/index.ts
→ Created src/components/ProductCard/ProductCard.test.tsx
→ Created src/components/ProductCard/ProductCard.stories.tsx
→ Updated src/components/index.ts

# .windsurf/flows/crud-api.yaml
name: CRUD API Endpoints
description: Generates complete CRUD API for an entity

inputs:
  - name: entityName
    type: string
    required: true
  - name: fields
    type: array
    items:
      - name: fieldName
        type: string
      - name: fieldType
        type: select
        options: [string, number, boolean, date]
    required: true
  - name: withAuth
    type: boolean
    default: true

steps:
  # Prisma schema
  - name: Update Prisma Schema
    action: update_file
    path: prisma/schema.prisma
    insert_before: "// END MODELS"
    template: |
      model {{entityName}} {
        id        String   @id @default(cuid())
        {{#each fields}}
        {{this.fieldName}} {{#if (eq this.fieldType "string")}}String{{/if}}{{#if (eq this.fieldType "number")}}Int{{/if}}{{#if (eq this.fieldType "boolean")}}Boolean{{/if}}{{#if (eq this.fieldType "date")}}DateTime{{/if}}
        {{/each}}
        createdAt DateTime @default(now())
        updatedAt DateTime @updatedAt
      }

  # API routes - iteration
  - name: Create List Endpoint
    action: create_file
    path: app/api/{{lowercase entityName}}s/route.ts
    template: |
      import { prisma } from '@/lib/prisma'
      import { NextResponse } from 'next/server'
      {{#if withAuth}}
      import { auth } from '@/lib/auth'
      {{/if}}

      export async function GET() {
        {{#if withAuth}}
        const session = await auth()
        if (!session) {
          return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
        }
        {{/if}}

        const items = await prisma.{{lowercase entityName}}.findMany()
        return NextResponse.json(items)
      }

      export async function POST(request: Request) {
        {{#if withAuth}}
        const session = await auth()
        if (!session) {
          return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
        }
        {{/if}}

        const data = await request.json()
        const item = await prisma.{{lowercase entityName}}.create({ data })
        return NextResponse.json(item, { status: 201 })
      }

  # Repeat for each endpoint...

# .windsurf/flows/ai-refactor.yaml
name: AI-Powered Refactoring
description: Uses Cascade for intelligent refactoring

inputs:
  - name: targetFile
    type: file
    required: true
  - name: refactorType
    type: select
    options:
      - Extract Functions
      - Add TypeScript Types
      - Improve Performance
      - Add Error Handling
    required: true

steps:
  - name: Analyze with AI
    action: cascade_analyze
    file: "{{targetFile}}"
    prompt: |
      Analyze this file for: {{refactorType}}.
      Identify all areas that need improvement.

  - name: Apply Refactoring
    action: cascade_refactor
    file: "{{targetFile}}"
    instruction: |
      Based on the analysis, perform {{refactorType}}.
      Preserve existing functionality.
      Add comments where changes are significant.

  - name: Verify Changes
    action: run_command
    command: npm test -- --findRelatedTests {{targetFile}}

  - name: Format Code
    action: run_command
    command: npx prettier --write {{targetFile}}

# Flows can be shared within a team:
# 1. Locally in .windsurf/flows/
# 2. Company flows repository
# 3. Windsurf Marketplace

# Installing from marketplace:
> Windsurf: Install Flow
> Search: "nextjs api crud"
> Install: "NextJS CRUD Generator by @company"

// Traditional autocomplete:
// Suggests only based on local context

const user = {
  na| // Suggests: "name", "navigate", "NaN"
}

// Windsurf Supercomplete:
// Understands the project structure

// If the project contains:
// types/user.ts: interface User { name: string; email: string; role: 'admin' | 'user' }

const user: User = {
  na| // Suggests: "name" (string) - with full type
}

// After selection:
const user: User = {
  name: '|' // Suggests values based on existing data in the project
}

// I start typing:
import { use|

// Supercomplete understands the project and suggests:
// → useAuth (from hooks/useAuth.ts)
// → useCart (from hooks/useCart.ts)
// → useToast (from @/components/ui/use-toast)
// → useState (from react)
// → useEffect (from react)

// The ordering is intelligent - local imports first, then dependencies

// In file components/ProductCard.tsx
// Project uses TailwindCSS and shadcn/ui

function ProductCard({ product }: { product: Product }) {
  return (
    <Card className="|
    // Supercomplete suggests:
    // → "p-4 hover:shadow-lg" (pattern from other cards in the project)
    // → "flex flex-col gap-4" (common pattern)

// Knowing the API structure in the project:

async function getProduct(id: string) {
  const response = await fetch|
  // Supercomplete:
  // → fetch(`/api/products/${id}`) - based on existing endpoints

// .windsurf/settings.json
{
  "supercomplete": {
    "enabled": true,
    "debounceMs": 100,
    "maxSuggestions": 5,
    "contextDepth": "project", // "file" | "directory" | "project"
    "prioritizeLocal": true,
    "learnFromEdits": true,
    "excludePatterns": [
      "node_modules/**",
      "dist/**",
      ".git/**"
    ]
  }
}

Cmd+K → Opens AI Command

Examples:
"refactor this to use hooks"
"add error handling"
"convert to TypeScript"
"explain this code"
"add tests for this function"
"make this component responsive"

// Select code and press Cmd+K

function processData(data) {  // ← Selected
  const result = [];
  for (let i = 0; i < data.length; i++) {
    if (data[i].active) {
      result.push(data[i].value * 2);
    }
  }
  return result;
}

// Cmd+K → "convert to functional style"

// Result:
const processData = (data: DataItem[]): number[] =>
  data
    .filter(item => item.active)
    .map(item => item.value * 2);

Cmd+Shift+K → AI Command for multiple files

"add loading states to all components in components/dashboard"
"update all API calls to use new error handling pattern"
"migrate class components to functional"

User: Install and configure TailwindCSS

Cascade:
[1/4] Installing dependencies...
> npm install -D tailwindcss postcss autoprefixer

[2/4] Initializing Tailwind...
> npx tailwindcss init -p

[3/4] Configuring tailwind.config.js...
→ Updating file with appropriate paths

[4/4] Adding directives to CSS...
→ Updating globals.css

✓ TailwindCSS configured!

User: Tests in auth.test.ts are failing, help me fix them

Cascade:
[1/3] Running tests to see the errors...
> npm test auth.test.ts

Error on line 45: "TypeError: Cannot read property 'user' of undefined"

[2/3] Analyzing the problem...
→ Mock for useSession returns undefined instead of a session object

[3/3] Fixing the test...
→ Updating mock in auth.test.ts

Re-running tests...
> npm test auth.test.ts

✓ All 12 tests passed!

User: Run tests in watch mode and fix errors automatically

Cascade:
> npm test -- --watch

[Watch] Test failed: ProductCard.test.tsx
→ Analyzing error...
→ Missing 'onAddToCart' prop
→ Updating test...
→ Test passed!

[Watch] Test failed: useCart.test.ts
→ Analyzing error...
→ State is not reset between tests
→ Adding beforeEach with reset...
→ Test passed!

[Watch] All tests passing ✓
Monitoring for further changes...

# Homebrew
brew install --cask windsurf

# Or download from windsurf.ai
curl -fsSL https://windsurf.ai/install.sh | sh

# Winget
winget install Codeium.Windsurf

# Or download the installer from windsurf.ai

# Ubuntu/Debian
wget -qO- https://windsurf.ai/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/windsurf.gpg
echo "deb [signed-by=/usr/share/keyrings/windsurf.gpg] https://windsurf.ai/apt stable main" | sudo tee /etc/apt/sources.list.d/windsurf.list
sudo apt update && sudo apt install windsurf

# Arch Linux (AUR)
yay -S windsurf-bin

# Flatpak
flatpak install flathub ai.windsurf.Windsurf

# 1. Launch Windsurf
windsurf

# 2. Log in to Codeium (free account)
# → Click "Sign In" in the bottom-right corner
# → Authorize via GitHub/Google/Email

# 3. Configure your project
# → Open the project folder
# → Windsurf will automatically index the code

// .windsurf/settings.json (project)
// or ~/.config/windsurf/settings.json (global)

{
  // Cascade
  "cascade": {
    "enabled": true,
    "model": "gpt-4-turbo", // or "claude-3-opus", "custom"
    "temperature": 0.3,
    "maxTokens": 8192,
    "autoApprove": false, // true = automatically apply changes
    "showDiff": true
  },

  // Supercomplete
  "supercomplete": {
    "enabled": true,
    "debounceMs": 150,
    "maxSuggestions": 5,
    "contextDepth": "project"
  },

  // Terminal
  "terminal": {
    "cascadeIntegration": true,
    "autoRunSuggested": false,
    "shell": "/bin/zsh"
  },

  // Privacy
  "privacy": {
    "telemetry": false,
    "shareUsageData": false,
    "localIndexing": true
  },

  // Appearance
  "theme": "windsurf-dark",
  "fontSize": 14,
  "fontFamily": "JetBrains Mono"
}

# Windsurf automatically imports:
# - Extensions (most are compatible)
# - Settings
# - Keybindings
# - Snippets

# Manual migration:
windsurf --import-from-vscode

# Or copy settings:
cp ~/.config/Code/User/settings.json ~/.config/windsurf/

User: Prepare a commit with a meaningful description

Cascade:
Analyzing changes in the staging area...

Found changes:
- components/Cart.tsx: Added quantity validation
- hooks/useCart.ts: Error handling on update
- api/cart/route.ts: New DELETE endpoint

Proposed commit message:
---
feat(cart): add quantity validation and error handling

- Add min/max quantity validation in Cart component
- Implement error handling in useCart hook
- Add DELETE endpoint for removing items
---

Accept? (Y/n)

User: Create a Dockerfile for this Next.js project

Cascade:
Analyzing project structure...

→ Next.js 14 with App Router
→ Uses Prisma (requires generate)
→ Environment variables: DATABASE_URL, NEXTAUTH_SECRET

Creating an optimized Dockerfile:

[File] Dockerfile
[File] .dockerignore
[File] docker-compose.yml (with PostgreSQL)

Run the build? (docker build -t app .)

# .github/workflows/windsurf-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  cascade-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Windsurf AI Review
        uses: codeium/windsurf-action@v1
        with:
          api-key: ${{ secrets.CODEIUM_API_KEY }}
          review-mode: security,performance,best-practices

      - name: Post Review Comments
        uses: codeium/windsurf-comment@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

# 1. Be specific in your instructions

❌ "Fix this bug"
✅ "The calculateTotal function in Cart.tsx doesn't account for discounts.
   Add support for percentage discounts from the discount field."

# 2. Provide context

❌ "Add a form"
✅ "Add a user registration form matching the design
   in Figma (link). Use React Hook Form and Zod for validation.
   Fields: email, password, confirmPassword, name."

# 3. Break down complex tasks

❌ "Build the entire authentication system"
✅ "Step 1: Configure NextAuth with GitHub provider
   Step 2: Add middleware for protected routes
   Step 3: Create Login and Register components"

# 4. Use Review Mode for learning

"[Review] Check my code and explain what can be improved"

# Directory structure
.windsurf/
├── flows/
│   ├── components/       # Component generation
│   │   ├── react-component.yaml
│   │   └── page-component.yaml
│   ├── api/             # API generation
│   │   ├── crud-endpoint.yaml
│   │   └── graphql-resolver.yaml
│   ├── testing/         # Test generation
│   │   ├── unit-test.yaml
│   │   └── e2e-test.yaml
│   └── refactoring/     # Refactoring
│       ├── to-typescript.yaml
│       └── extract-hook.yaml
├── templates/           # Templates for flows
│   ├── component.tsx.hbs
│   └── test.tsx.hbs
└── settings.json

// For large projects
{
  "supercomplete": {
    "contextDepth": "directory", // Instead of "project"
    "excludePatterns": [
      "**/*.test.ts",
      "**/*.spec.ts",
      "**/__mocks__/**",
      "**/fixtures/**"
    ],
    "priorityPaths": [
      "src/components/**",
      "src/hooks/**",
      "src/lib/**"
    ]
  }
}

# 1. Reindex the project
Cmd+Shift+P → "Windsurf: Reindex Project"

# 2. Check .windsurfignore
# Make sure you're not ignoring important files

# 3. Add a CLAUDE.md or WINDSURF.md with a project description
echo "# Project: E-commerce
Tech: Next.js, Prisma, Tailwind
Structure: app/ (pages), components/, lib/" > WINDSURF.md

// Optimization for slower machines
{
  "supercomplete": {
    "debounceMs": 300,
    "contextDepth": "file",
    "maxSuggestions": 3
  }
}

# Check terminal permissions
# macOS: System Preferences → Security → Full Disk Access → Windsurf

# Check PATH
# .windsurf/settings.json
{
  "terminal": {
    "env": {
      "PATH": "/usr/local/bin:/usr/bin:$PATH"
    }
  }
}