Getting started

Migrate from React

Move a React app (MUI, shadcn/Radix or Chakra) to Svelte 5 and CodeAtlas UI. Decision flow, hook-to-rune map, component maps, layout, theme and data table recipes, and how to report gaps.

This page is written for a coding agent and for the person reviewing its work. Every component and prop named here exists in the generated manifest (get_component, get_export), and a test fails when one stops existing. If you cannot find an equivalent for something in your app, that is a gap: write a documented workaround and report it, do not invent a component.

Decide first: incremental or rewrite

Never mount React inside Svelte (or the reverse) to save time: two reconcilers on one page means two focus models and two sets of effects. A route is either React or Svelte.

Port in this order, whatever you picked: theme and shell, then one list page, one form page, one settings page, then the rest. Keep the React app’s API calls as they are; only the UI layer moves.

Project setup

React to Svelte 5 runes

Effect pitfalls

• Do not use $effect to compute a value. useEffect plus setState becomes $derived. An effect that writes state it also reads can loop.
• Reads after await are not tracked. Read every reactive value before the first await inside an effect.
• Return a cleanup function for timers, listeners and observers, exactly like useEffect. It runs before the next run and on destroy.
• There is no effect on the server. Code that touches window, localStorage or matchMedia belongs in onMount or $effect, or behind browser from $app/environment.
• Reading $state outside a component (a plain .ts file) does not track. Put shared reactive state in a .svelte.ts file.

<script lang="ts">
  import { Button, TextField } from "@codeatlasdev/ui";

  let name = $state("");
  let saving = $state(false);
  let valid = $derived(name.trim().length > 1);

  async function save() {
    saving = true;
    await fetch("/api/users", { method: "POST", body: JSON.stringify({ name }) });
    saving = false;
  }
</script>

<TextField label="Name" bind:value={name} />
<Button variant="filled" loading={saving} disabled={!valid} onclick={save}>Save</Button>

Component map

Targets are real exports of @codeatlasdev/ui unless the import path says otherwise. Props that differ from what you expect are listed; for the rest, call get_component.

MUI

shadcn/ui and Radix

Chakra UI

Layout patterns

Do not port a React page wrapper one-to-one. Pick the template that matches what the page is, then fill its snippets. They own the scroll behaviour, the header, the footer and the mobile layout.

<script lang="ts">
  import { AppList, Button, SimpleTable, StatusChip } from "@codeatlasdev/ui";

  let { data } = $props();
</script>

<AppList title="Users" data={data.users} searchKeys={["name", "email"]} perPage={10}>
  {#snippet actions()}
    <Button variant="filled" href="/users/new">New user</Button>
  {/snippet}

  {#snippet children(list)}
    <SimpleTable>
      <thead><tr><th>Name</th><th>Status</th></tr></thead>
      <tbody>
        {#each list.rows as u (u.id)}
          <tr>
            <td>{u.name}</td>
            <td><StatusChip status={u.active ? "success" : "neutral"} label={u.active ? "Active" : "Inactive"} /></td>
          </tr>
        {/each}
      </tbody>
    </SimpleTable>
  {/snippet}
</AppList>

Do not wrap fields in Stack or Flex for layout inside FormSection: layout is grid by default, list for switches and stack for composite blocks. Mobile rules (viewport units, safe areas, keyboard) are in Mobile.

Theme mapping

There is one ThemeOptions object in src/lib/theme.ts. Map your design tokens into it instead of recreating a theme provider:

// src/lib/theme.ts
import type { ThemeOptions } from "@codeatlasdev/ui/vite";

export const theme: ThemeOptions = {
  presets: [{ id: "app", color: "#2563eb" }],
  defaultPreset: "app",
  defaultScheme: "system",
  radius: 0.8,
  density: "comfortable",
  fonts: { body: "Inter, system-ui, sans-serif" },
};

Delete the React theme provider, the Tailwind color config and every sx, className and style prop that only set color, spacing or radius.

Data tables

TanStack Table for React becomes DataTable from the @codeatlasdev/ui/table entry, built on @tanstack/svelte-table. Column helpers keep the same accessor idea; search, sorting, paging and the column toggle are built in.

<script lang="ts">
  import { DataTable, createCaColumnHelper } from "@codeatlasdev/ui/table";

  type User = { name: string; email: string };
  let { users }: { users: User[] } = $props();

  const col = createCaColumnHelper<User>();
  const columns = col.columns([
    col.accessor("name", { header: "Name", meta: { label: "Name" } }),
    col.accessor("email", { header: "Email", meta: { label: "Email" } }),
  ]);
</script>

<DataTable {columns} data={users} />

Details and controlled mode: DataTable. For a plain list without search or sorting, SimpleTable inside AppList is lighter.

Gaps and workarounds

If something in the React app has no equivalent in the library (a component, a prop, a behaviour), do not fake it and do not leave it undocumented:

1. Check twice. Call search_demos, get_component and get_export with the React name and with a description of what it does. list_components shows everything.

2. Write a workaround in the app’s own code, with a one-line marker so it can be found and removed later:

   <!-- ca-ui-workaround(#123): no equivalent of MUI TreeView, using nested Collapsible -->

   In script code use // ca-ui-workaround(#123): reason. Use the issue number once you have it; until then write the marker without a number and add it after step 3.

3. Report it. Call the MCP tool report_issue with kind: "migration-gap", a neutral title, expected (what the React component did), actual (what the library offers), a minimal repro and your workaround. It returns a sanitized issue body and a prefilled link; it never posts by itself. Open the link, or run the gh issue create command it prints.

Never put project, company or customer names, file paths, URLs, environment values, secrets, data or business logic in the report. Use neutral names (Foo, items) in the repro. bunx @codeatlasdev/ui workarounds lists the markers in your code and which of their issues are closed, so you know when to delete a workaround.