windmill/frontend/CLAUDE.md

Frontend Development (Svelte 5)

Core Principles

• Follow @svelte5-best-practices.mdc for detailed guidelines
• Use Runes ($state, $derived, $effect) for reactivity
• Keep components small and focused
• Always use keys in {#each} blocks

UI Guidelines

• Follow existing design system
• Use consistent spacing and colors

Backend API

• If you need to call the backend API, you can find the available routes in ../backend/windmill-api/openapi.yaml
• You can also use the associated types and services that are auto generated from the openapi file. They are in src/lib/gen/*gen.ts files

OpenAPI Autogeneration

Windmill automatically generates TypeScript types and services from the OpenAPI specification.

Service Generation Pattern

The autogeneration follows this pattern:

• Tag → Service Name: The OpenAPI tag becomes the service name with "Service" suffix
• operationId → Method Name: The operationId becomes the method name in the service

Example

Given this OpenAPI specification:

/w/{workspace}/audit/list:
  get:
    summary: list audit logs (requires admin privilege)
    operationId: listAuditLogs
    tags:
      - audit
    parameters:
      - $ref: '#/components/parameters/WorkspaceId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Before'
      - $ref: '#/components/parameters/After'
      - $ref: '#/components/parameters/Username'
      - $ref: '#/components/parameters/Operation'
      - name: operations
        in: query
        description: comma separated list of exact operations to include
        schema:
          type: string

This generates:

• Service: AuditService (from tag "audit")
• Method: listAuditLogs (from operationId)

Method Arguments

The generated method arguments correspond to the OpenAPI parameters:

AuditService.listAuditLogs({
  workspace: string,           // from WorkspaceId parameter
  page?: number,              // from Page parameter
  perPage?: number,           // from PerPage parameter
  before?: string,            // from Before parameter
  after?: string,             // from After parameter
  username?: string,          // from Username parameter
  operation?: string,         // from Operation parameter
  operations?: string         // from operations parameter
})