Frontend Guide

Frontend coding guidelines

Coding standards for frontend development in LightlyStudio using SvelteKit and TypeScript.

Key Principles

• Write concise, technical TypeScript code. Use Svelte-specific features (like runes) only when necessary within Svelte-compiled components.
• Keep components under 100 lines. Split code into logical, testable parts.
• Embrace TDD. Use vitest for unit and integration tests.
• Follow Svelte and SvelteKit official documentation.

Framework-agnostic approach

Minimize framework-specific syntax to reduce coupling and improve testability:

• Prefer writable/readable/derived stores over runes for state management - stores have explicit imports and clearer dependencies.
• Use runes only when their specific features are necessary for component-level reactivity.
• Less framework coupling means easier maintenance, onboarding, and migration.

Project structure & naming

• PascalCase for component names and their folders (e.g., AuthForm/AuthForm.svelte).
• camelCase for non-component files, variables, functions, and props (e.g., useAuth.ts, const myVar).
• Every component and hook lives in its own folder scoping related files together.

Canonical layout:

src/
  components/
    AuthForm/
      AuthForm.svelte
      AuthForm.test.ts
      AuthForm.stories.svelte       # if needed
    UserDashboard/
      UserDashboard.svelte
      UserDashboard.test.ts
      UserDashboard.helpers.ts       # if needed
      UserProfile/                   # subcomponent
        UserProfile.svelte
        UserProfile.test.ts
  lib/
    hooks/
      index.ts                       # barrel exports
      useAuth/
        useAuth.ts
        useAuth.test.ts
      useData/
        useData.ts
        useData.test.ts

• Use .svelte.ts files for component logic, state machines, and hooks that use TanStack Query (since v6 uses runes internally).
• Use barrel exports (index.ts) to define a module's public API. Import from module level, not deep paths:

// ✅ from "$lib/hooks"  - not "$lib/hooks/useData/useData"
import { useData, useAuth } from "$lib/hooks";

Imports

• Absolute imports for shared modules: from "$lib/hooks", from "$lib/components/ui/button".
• Relative imports only within the same module folder: from "../UserDashboard.helpers".

TypeScript

• Use TypeScript for all code.
• Define interface for component props, function parameters, and return types:

interface UseDataParams {
  title: string;
  onClick: () => void;
}

interface UseDataReturn {
  data: string;
  isLoading: boolean;
}

export function useData(params: UseDataParams): UseDataReturn {
  return { data: params.title, isLoading: false };
}

• Avoid exporting/importing types. Derive types from source code using utility types to keep things DRY:

type UseDataParams = Parameters<typeof useData>[0];
type UseDataReturn = ReturnType<typeof useData>;
type TitleOnly = Pick<UseDataParams, "title">;
type WithoutTitle = Omit<UseDataParams, "title">;

UI and Styling

• Shadcn components from $lib/components/ui for standard UI elements (buttons, inputs, cards, tabs, alerts, tables).
• Project-specific components from $lib/components when combining multiple Shadcn components, adding business logic, or needing custom behavior.
• Bits-UI as the base component library underlying Shadcn.
• Lucide Icons for all icons - import from @lucide/svelte.
• Use cn() from $lib/utils for conditional Tailwind class composition.
• Prefer explicit props over object spreading - components should receive only the specific props they need. Exception: forwarding HTML attributes via ...rest, or intentional wrapper/proxy components.

Performance

Keep JS chunk sizes below 500KB. Use dynamic imports for heavy components:

<script lang="ts">
  import { onMount } from 'svelte';

  let HeavyChart;

  onMount(async () => {
    const module = await import('$lib/components/HeavyChart.svelte');
    HeavyChart = module.default;
  });
</script>

{#if HeavyChart}
  <svelte:component this={HeavyChart} />
{/if}

When reviewing bundle size:

• Check build output for chunk-size warnings.
• Identify heavy dependencies before adding them to eagerly loaded routes.
• Prefer lazy loading, vendor splitting, or dependency deduplication when a chunk exceeds the limit.

Svelte 5 syntax

Use Svelte 5 patterns in all new code:

Props - use $props() with a typed interface:

<script lang="ts">
  interface Props {
    value: string;
    placeholder?: string;
    onSearch: (query: string) => void;
    disabled?: boolean;
  }

  let {
    value,
    placeholder = 'Enter text',
    onSearch,
    disabled = false
  }: Props = $props();
</script>

Event handlers - use onclick, onchange, etc. (not on:click, on:change).

Reactive declarations - use $derived or derived() stores, not $:. Do not mix the two approaches - pick one per file/module.

Page state - use $app/state, not $app/stores:

import { page } from "$app/state";
page.params.sampleId; // no $ prefix needed

Hooks and reactivity - for hooks that wrap TanStack Query, accept a getter function (thunk) for reactive parameters. TanStack Query v6 uses thunks for reactivity — do not pass Svelte stores or $derived values:

// Hook definition (useFrames.svelte.ts — must be .svelte.ts for TanStack v6)
export const useFrames = (
  getParams: () => { video_frame_collection_id: string; filter: VideoFrameFilter }
) => {
  const query = createInfiniteQuery(() => {
    const { video_frame_collection_id, filter } = getParams();
    return {
      ...getAllFramesInfiniteOptions({
        path: { video_frame_collection_id },
        body: { filter }
      }),
      getNextPageParam: (lastPage) => lastPage.nextCursor || undefined
    };
  });
  return { query };
};

// Consumer (+page.svelte)
const { query } = useFrames(() => ({
  video_frame_collection_id: collectionId,
  filter: currentFilter
}));
// query is a reactive proxy — access query.isSuccess, query.data directly (no $ prefix)

For non-TanStack hooks with static parameters, pass values via SvelteKit's page load function or direct props.