AGENTS.md - Coding Guidelines for CLQMS Frontend

Project Overview

SvelteKit frontend for Clinical Laboratory Quality Management System (CLQMS). Uses Svelte 5 runes, TailwindCSS 4, DaisyUI, and Lucide icons.

Build Commands

# Development server
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

# Sync SvelteKit (runs automatically on install)
npm run prepare

Testing

No test framework configured yet. When adding tests:

Use Vitest for unit tests (recommended with SvelteKit)
Use Playwright for E2E tests
Run single test: vitest run src/path/to/test.js
Run tests in watch mode: vitest

Code Style Guidelines

JavaScript/TypeScript

ES Modules: Always use import/export (type: "module" in package.json)
Semicolons: Use semicolons consistently
Quotes: Use single quotes for strings
Indentation: 2 spaces
Trailing commas: Use in multi-line objects/arrays
JSDoc: Document all exported functions with JSDoc comments

Svelte Components

<script>
  // 1. Imports first - group by: Svelte, $lib, external
  import { onMount } from 'svelte';
  import { goto } from '$app/navigation';
  import { auth } from '$lib/stores/auth.js';
  import { login } from '$lib/api/auth.js';
  import { Icon } from 'lucide-svelte';
  
  // 2. Props (Svelte 5 runes)
  let { children, data } = $props();
  
  // 3. State
  let loading = $state(false);
  let error = $state('');
  
  // 4. Derived state (if needed)
  let isValid = $derived(username.length > 0);
  
  // 5. Effects
  $effect(() => {
    // side effects
  });
  
  // 6. Functions
  function handleSubmit() {
    // implementation
  }
</script>

Naming Conventions

Components: PascalCase (LoginForm.svelte)
Files/Routes: lowercase with hyphens (+page.svelte, user-profile/)
Variables: camelCase (isLoading, userName)
Constants: UPPER_SNAKE_CASE (API_URL, STORAGE_KEY)
Stores: camelCase, descriptive (auth, userStore)
Event handlers: prefix with handle (handleSubmit, handleClick)

Imports Order

Svelte imports (svelte, $app/*)
$lib aliases ($lib/stores/*, $lib/api/*, $lib/components/*)
External libraries (lucide-svelte)
Relative imports (minimize these, prefer $lib)

Project Structure

src/
  lib/
    api/          # API client and endpoints
    stores/       # Svelte stores
    components/   # Reusable components
    assets/       # Static assets
  routes/         # SvelteKit routes
    (app)/        # Route groups
    login/
    dashboard/

API Client Patterns

// src/lib/api/client.js - Base client handles auth
import { apiClient, get, post, put, del } from '$lib/api/client.js';

// src/lib/api/feature.js - Feature-specific endpoints
export async function getItem(id) {
  return get(`/api/items/${id}`);
}

export async function createItem(data) {
  return post('/api/items', data);
}

Error Handling

// API errors are thrown with message
try {
  const result = await api.login(username, password);
} catch (err) {
  error = err.message || 'An unexpected error occurred';
  console.error('Login failed:', err);
}

Styling with Tailwind & DaisyUI

Use Tailwind utility classes
DaisyUI components: btn, card, alert, input, navbar
Color scheme: primary (emerald), base-100, base-200
Custom colors in app.css with @theme

Authentication Patterns

Auth state in $lib/stores/auth.js
Check auth in layout onMount
Redirect to /login if unauthenticated
API client auto-redirects on 401

Environment Variables

const API_URL = import.meta.env.VITE_API_URL || '';

LocalStorage

Only access in browser: check browser from $app/environment
Use descriptive keys: clqms_username, clqms_remember

Proxy Configuration

API requests to /api are proxied to http://localhost:8000 in dev.

Important Notes

No ESLint or Prettier configured yet - add if needed
No test framework configured yet
Uses Svelte 5 runes: $props, $state, $derived, $effect
SvelteKit file-based routing with +page.svelte, +layout.svelte

4.2 KiB Raw Blame History