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

Every shadcn/ui component

One row per component on ui.shadcn.com/docs/components, with the Radix primitive, Base UI package and MUI component that mean the same thing. A row marked none (gap #n) has no component here: use the workaround in the row and keep the issue number in a ca-ui-workaround(#n) marker. The same data answers get_equivalent("Dialog") in the MCP server and drives bunx @codeatlasdev/ui migrate-react.

From Tailwind

The library does not need utility classes for what its components own, and it keeps layout in typed props so there is no class string to drift. Map the intent, not the class.

Two rules keep the port clean. Never write a hex color or a pixel size: use a token (bun run a search_tokens call to find it). And do not recreate a utility layer; a one-off style goes in a scoped class using tokens.

<script lang="ts">
  import { Card, Flex, Grid } from "@codeatlasdev/ui";
</script>

<Grid columns={{ base: 1, md: 3 }} gap="4">
  <Card title="Revenue"><Flex align="center" gap="2">$12k</Flex></Card>
  <Card title="Orders"><Flex align="center" gap="2">340</Flex></Card>
  <Card title="Refunds"><Flex align="center" gap="2">12</Flex></Card>
</Grid>

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.

React patterns that change shape

Each pattern shows the React code and the Svelte code that replaces it. The Svelte blocks are type-checked against the built package in CI, like every demo, so they keep working when the API moves.

Context and global state

const ThemeContext = createContext<Theme>("light");
export const useTheme = () => useContext(ThemeContext);

A module with $state replaces the provider. Put it in a .svelte.ts file; a plain .ts file does not track.

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

  // colorScheme is the library's own store: preference, resolved scheme, preset.
  const label = $derived(`Theme: ${colorScheme.resolved}`);
</script>

<Button variant="ghost" onclick={() => toast.show(label)}>{label}</Button>

Data fetching

const { data, isPending } = useQuery({ queryKey: ["users"], queryFn: fetchUsers });

Fetch in load, so the page renders with its data on the server. Reach for TanStack Query only for client-side caching, and then the Svelte adapter takes the options as a function.

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

  // data comes from +page.ts / +page.server.ts `load`; no effect, no loading flag.
  let { data } = $props();
</script>

{#if data.users.length}
  <AppList title="Users" data={data.users} searchKeys={["name"]} perPage={10}>
    {#snippet children(list)}
      {#each list.rows as u (u.id)}<p>{u.name}</p>{/each}
    {/snippet}
  </AppList>
{:else}
  <EmptyState title="No users yet" />
{/if}

Routing

The signed-in frame takes the router as two props, so it needs no adapter:

<script lang="ts">
  import { goto } from "$app/navigation";
  import { page } from "$app/state";
  import { AppShellLayout } from "@codeatlasdev/ui";

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

<AppShellLayout modules={data.modules} pathname={page.url.pathname} onNavigate={(path) => goto(path)}>
  {@render children()}
</AppShellLayout>

Forms

const [name, setName] = useState("");
<form onSubmit={(e) => { e.preventDefault(); save(name); }}>

A form action replaces the handler and works without JavaScript; use:enhance keeps the page in place.

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

  let { form } = $props();
  let saving = $state(false);
</script>

<form method="POST" use:enhance={() => { saving = true; return async ({ update }) => { await update(); saving = false; }; }}>
  <TextField name="name" label="Name" error={form?.errors?.name} />
  <Button type="submit" variant="filled" loading={saving}>Save</Button>
</form>

SSR and global state

A module-level $state is created once per server process, so it is shared by every request. Do not keep per-user data in it. Per-request data goes through load and event.locals; per-tree data goes through setContext during component init. The library follows the same rule: setLocale is client-only.

i18n per request

<IntlProvider locale={locale} messages={messages}>

I18nProvider in the root layout is the SSR-safe equivalent. The locale comes from load, never from a module.

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

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

<I18nProvider locale={data.locale}>
  {@render children()}
</I18nProvider>

Your own strings keep using your catalog; useLocale() gives the current tag inside the tree for Intl formatting.

Compare the result with the old app

bunx @codeatlasdev/ui compare <oldUrl> <newUrl> opens both in Chromium at 390 and 1280 px (--viewport), measures each data-testid element (or --selector CSS) and prints the differences sorted by size: box, computed styles (--props) and a pixel diff. A button that differs in weight and padding gives exactly those rows. Box deltas up to --tolerance px (0.5) are ignored; exit 1 on any difference, 2 without playwright in the project. In tests, measure(el, props) from @codeatlasdev/ui/testing gives the same data.

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.