Astro組件庫建構指南：標準化開發流程

建立可維護的Astro組件庫對提升開發效率至關重要。本文介紹組件庫建構的最佳實踐，從架構設計到發布流程的完整指南。

良好的組件庫能提升代碼重用性、維護效率與團隊協作品質。

1. 組件庫架構設計

src/
├── components/
│   ├── ui/              # 基礎UI組件
│   │   ├── Button.astro
│   │   ├── Input.astro
│   │   └── Card.astro
│   ├── layout/          # 版面組件
│   │   ├── Header.astro
│   │   ├── Footer.astro
│   │   └── Sidebar.astro
│   ├── content/         # 內容組件
│   │   ├── BlogPost.astro
│   │   └── Portfolio.astro
│   └── index.ts         # 統一出口

命名規範

• 使用PascalCase組件名稱
• 一個檔案包含一個組件
• 依功能分類組織資料夾

2. TypeScript 型別系統

// types/components.ts
export interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  href?: string;
  target?: '_blank' | '_self';
  class?: string;
}

export interface CardProps {
  title?: string;
  description?: string;
  image?: ImageMetadata;
  href?: string;
  tag?: string;
}

---
// Button.astro
import type { ButtonProps } from '../types/components';

type Props = ButtonProps;

const { 
  variant = 'primary',
  size = 'md',
  disabled = false,
  href,
  target = '_self',
  class: className = ''
} = Astro.props;

const Component = href ? 'a' : 'button';
---

<Component
  class={`btn btn-${variant} btn-${size} ${className}`}
  href={href}
  target={href ? target : undefined}
  disabled={disabled}
>
  <slot />
</Component>

3. 樣式系統整合

/* styles/design-tokens.css */
:root {
  /* Colors */
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --color-success: #10b981;
  --color-danger: #ef4444;
  
  /* Spacing */
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  --space-xl: 2rem;
  
  /* Typography */
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
}

<!-- 組件中使用設計令牌 -->
<style>
  .btn {
    padding: var(--space-sm) var(--space-md);
    font-size: var(--font-size-base);
    border-radius: 0.375rem;
    transition: all 0.2s ease;
  }
  
  .btn-primary {
    background-color: var(--color-primary);
    color: white;
  }
</style>

4. 文檔化與展示

---
// pages/components/button.astro
import Button from '../../../../../components/ui/Button.astro';
---

<Layout title="Button Component">
  <h1>Button 組件</h1>
  
  <section>
    <h2>基本用法</h2>
    <Button>Primary Button</Button>
    <Button variant="secondary">Secondary Button</Button>
    <Button variant="ghost">Ghost Button</Button>
  </section>
  
  <section>
    <h2>尺寸變化</h2>
    <Button size="sm">Small</Button>
    <Button size="md">Medium</Button>
    <Button size="lg">Large</Button>
  </section>
  
  <section>
    <h2>程式碼範例</h2>
    <pre><code>
&lt;Button variant="primary" size="lg"&gt;
  Click me
&lt;/Button&gt;
    </code></pre>
  </section>
</Layout>

5. 組件測試

// tests/Button.test.ts
import { expect, test } from '@playwright/test';

test.describe('Button Component', () => {
  test('renders with correct variant classes', async ({ page }) => {
    await page.goto('/components/button');
    
    const primaryBtn = page.locator('[data-testid="btn-primary"]');
    await expect(primaryBtn).toHaveClass(/btn-primary/);
    
    const secondaryBtn = page.locator('[data-testid="btn-secondary"]');  
    await expect(secondaryBtn).toHaveClass(/btn-secondary/);
  });
  
  test('handles click events', async ({ page }) => {
    await page.goto('/components/button');
    
    const button = page.locator('[data-testid="clickable-btn"]');
    await button.click();
    
    await expect(page.locator('[data-testid="click-count"]')).toHaveText('1');
  });
});

發布與維護

{
  "name": "@yourname/astro-ui",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": "./dist/index.js",
    "./components/*": "./dist/components/*"
  },
  "files": ["dist"],
  "peerDependencies": {
    "astro": "^4.0.0"
  }
}

維護最佳實踐

實用工具推薦

建立組件庫需要長期規劃與持續維護，但能顯著提升開發效率與代碼品質。