Svelte Components trong MDX - Lỗi và Cách Fix

Svelte Components trong MDX - Lỗi và Cách Fix

Quan trọng: Bài viết này nói về việc dùng Svelte trong MDX files của Starlight. Nếu bạn muốn dùng Svelte trong .astro files, hãy xem hướng dẫn chính thức bên dưới.

Cách đúng để thêm Svelte vào Astro (cho .astro files)

Theo hướng dẫn chính thức 2026:

# Cách khuyến nghị
npx astro add svelte

---
import Button from '../components/Button.svelte';
---

<!-- Render tĩnh (không JS) -->
<Button />

<!-- Có tương tác -->
<Button client:load />

<!-- Chỉ render trên client -->
<Button client:only="svelte" />

Cách này KHÔNG gây xung đột vì:

• Astro tự nhận diện .svelte → không va chạm với .jsx, .vue
• Mỗi component là island độc lập
• Có thể mix: <ButtonSvelte /> + <CardReact /> + <ModalVue /> đều ổn

---

Vấn đề thực sự: Svelte trong MDX Files của Starlight

Khi sử dụng Astro Starlight (một documentation framework cho Astro), việc import và sử dụng Svelte components trực tiếp trong MDX files gây ra nhiều lỗi build.

Lỗi phổ biến

[@mdx-js/rollup] Could not parse import/exports with acorn

hoặc

MDXError: Unexpected end of file in expression, expected a corresponding closing brace for {

---

Các Components Gây Lỗi

1. Import Svelte Components trực tiếp ❌

Không hoạt động:

---
title: My Page
---

import Alert from '../../../components/svelte/Alert.svelte';
import GlassCard from '../../../components/svelte/GlassCard.svelte';

# Hello
<Alert type="info">Message</Alert>

Lý do: Starlight/MDX không hỗ trợ import Svelte components trực tiếp trong frontmatter.

2. Sử dụng JSX braces { trong Tables ❌

Không hoạt động:

| ChatGPT | Claude Code |
|---------|-------------|
| function ContactForm() { | ✓ Tạo file |

Lý do: MDX hiểu { là bắt đầu JavaScript expression.

Cách fix: Sử dụng HTML entities:

| ChatGPT | Claude Code |
|---------|-------------|
| function ContactForm() { | ✓ Tạo file |

---

Các Components Không Gây Lỗi ✅

1. Starlight Built-in Components ✅

Hoạt động tốt:

---
title: My Page
---

import { Aside } from '@astrojs/starlight/components';

:::tip
Đây là tip!
:::

:::caution
Cẩn thận!
:::

:::danger
Nguy hiểm!
:::

2. Starlight Steps Component ✅

---
title: My Page
---

import { Steps } from '@astrojs/starlight/components';

<Steps>
1. Bước đầu tiên
2. Bước thứ hai
3. Bước thứ ba
</Steps>

3. Code Blocks thông thường ✅

```javascript
function hello() {
  console.log('Hello');
}

### 4. Tables thông thường ✅

```mdx
| Cột 1 | Cột 2 |
|-------|-------|
| Dữ liệu | Dữ liệu |

5. Blockquotes ✅

> Đây là trích dẫn

---

Các Files Đã Fix

Dưới đây là các files đã được sửa lỗi:

File	Vấn đề	Cách fix
markdown/gioi-thieu-markdown.mdx	Import Svelte	Remove imports, dùng Starlight :::
markdown/markdown-co-ban.mdx	Import Svelte	Remove imports, dùng Starlight :::
code/svelte-counter-example.mdx	Import Svelte	Remove imports
code/component-examples.mdx	Import Svelte	Remove imports, dùng code blocks
web-dev/cai-dat-astro-local.mdx	Import Svelte	Remove imports, dùng Starlight :::
markdown/components-alert-boxes.mdx	Import Astro component	Remove imports, dùng Starlight :::
nhap/lap-trinh-cho-nha-tiep-thi.mdx	Braces trong table	Escape thành {

---

Giải pháp Thay thế

Cách 1: Sử dụng Starlight Aside (khuyến nghị)

:::tip[Tiêu đề]
Nội dung tip...
:::

:::caution[Chú ý]
Nội dung cảnh báo...
:::

:::danger[Lỗi]
Nội dung lỗi...
:::

Cách 2: Sử dụng CSS thay vì Components

Thay vì:

<GlassCard>
Nội dung
</GlassCard>

Dùng:

> **Tiêu đề**
> Nội dung bên trong

Cách 3: Đặt code trong fenced code blocks

Thay vì để { trực tiếp trong table, dùng:

| Code | Output |
|------|--------|
| `function() {` | ✓ |

---

Kết luận

• Không nên import Svelte components trực tiếp trong MDX files của Starlight
• Nên sử dụng Starlight built-in components như :::tip, :::caution, :::danger
• Cẩn thận với braces { và } trong tables - phải escape
• Thay thế bằng CSS styling hoặc markdown thuần khi cần custom components