Astro 專題 - DevPulse：極簡開發者技術雷達 (Tech Radar)-1

這是一個讓開發者管理自己「想學、正在學、已精通」技術清單的工具，強調極速的頁面切換與流暢的 UI。

環境架構設計

• astro v5
• tailwind v4
• Nano Stores
• vercel 佈署

第一步：環境初始化

# 建立專案
npm create astro@latest DevPulse

# 進入目錄
cd DevPulse

# 安裝 Tailwind v4 (目前 v4 推薦直接透過 Vite 插件整合)
npm install tailwindcss @tailwindcss/vite

# 安裝 Nano Stores
npm install nanostores @nanostores/react

💡 配置 Tailwind v4

在 Astro 5 中，修改 astro.config.mjs：

import { defineConfig } from 'astro/config'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
})

並在 src/styles/global.css 中引入：

@import 'tailwindcss';

💡 環境初始化與型別定義對齊 (Environment Initialization & Type Alignment)

當 astro 來到 ^5.16.15，tsconfig.json 將有所不同：

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "target": "ESNext",
    "module": "ESNext",
    "strict": true
  },
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

• "extends": "astro/tsconfigs/strict"：
  繼承 Astro 官方定義的最高標準嚴格規則
• compilerOptions 編譯器設定：
• 1. "moduleResolution": "Bundler" 定義「模組解析策略」。告訴 TypeScript：「請模仿 Vite 或 Webpack 這些打包工具找檔案的方式」。這讓你寫 import ... from 'astro:content' 時，電腦才找得到東西。
  2. "target": "ESNext" 設定輸出的 JavaScript 版本目標。告訴電腦：「我的程式碼要編譯成最新、最現代的 JavaScript 格式」。它支援所有最新的語法。
  3. "module": "ESNext" 指定要使用哪種模組系統。使用現代的 import 和 export 語法
  4. "strict": true 開啟所有嚴格型別檢查選項。
• "include": [".astro/types.d.ts", "**/*"]
  告訴 TypeScript 哪些檔案是它需要負責「看管」的。
• "exclude": ["dist"]
  告訴 TypeScript 哪些檔案完全不用理會。

第二步：建立 Nano Stores 狀態中心

我們需要一個全域狀態來存儲使用者的技術過濾條件。在 src/store/techStore.js 中建立：

import { atom } from 'nanostores'

// 定義目前的過濾分類：'all', 'learning', 'mastered'
export const categoryFilter = atom('all')

export function setCategory(value) {
  categoryFilter.set(value)
}

第三步：利用 Astro 5 Content Layer 建立資料

Astro 5 的強項在於 Content Layer。在 src/content/config.ts 定義你的技術清單：

import { defineCollection, z } from 'astro:content'
import { glob } from 'astro/loaders'

const techs = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/techs' }),
  schema: z.object({
    name: z.string(),
    status: z.enum(['learning', 'mastered', 'wishlist']),
    icon: z.string(),
  }),
})

export const collections = { techs }

💡 astro:content ：

• 當遇到 IDE 錯誤訊息 Cannot find module 'astro:content' or its corresponding type declarations.

  # terminal 執行
  npx astro sync
  # 執行完後，跟目錄會生成 .astro 資料夾，錯誤訊息也會消失

• 為什麼會遇到這個錯誤？
  astro:content 是由 Astro 動態生成的虛擬模組。
  如果是剛建立專案、新增了 src/content/config.ts，或者剛從 Git 下載專案，TypeScript 就會因為找不到實體檔案而報錯。
• npx astro sync 的用途是什麼？
  這個指令的核心目的是 「同步專案的狀態與 TypeScript 的型別定義」。
  當你執行 npx astro sync 時，Astro 會在後台做這幾件事：
• 1. 生成內容快照： 掃描 src/content/ 資料夾中的所有內容。
  2. 建立檔案結構： 在專案的 .astro/ 目錄下生成必要的檔案。
  3. 生成型別定義： 這也是最重要的，它會自動產生 types.d.ts 檔案，讓 VS Code 或其他編輯器能辨識 astro:content。它會根據 config.ts 中定義的 zod schema，把 Markdown/MDX 的 frontmatter 轉換成強型別。

第四步：實作互動式 UI (Tailwind v4 實踐)

在首頁 src/pages/index.astro 中，我們結合 Astro 的靜態渲染與 Nano Stores 的動態過濾。

---
import Layout from '../layouts/Layout.astro';
import { getCollection } from 'astro:content';
const allTechs = await getCollection('techs');
---

<Layout title="DevPulse">
  <main class="max-w-4xl mx-auto p-8">
    <h1 class="text-4xl font-bold tracking-tight text-gray-900 mb-8">
      My Tech Radar
    </h1>

    <div class="flex gap-4 mb-10">
      <button class="px-4 py-2 bg-indigo-600 text-white rounded-full hover:scale-105 transition">
        All
      </button>
      </div>

    <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
      {allTechs.map(tech => (
        <div class="p-6 border border-gray-200 rounded-2xl hover:shadow-lg transition-shadow">
          <h3 class="text-xl font-semibold">{tech.data.name}</h3>
          <span class="text-sm text-indigo-500 uppercase">{tech.data.status}</span>
        </div>
      ))}
    </div>
  </main>
</Layout>

💡 getCollection('techs') ：

• 當遇到 IDE 錯誤訊息

  No overload matches this call.
  Overload 1 of 2, '(collection: never, filter?: ((entry: never) => entry is never) | undefined): Promise<never[]>', gave the following error.
  Argument of type '"techs"' is not assignable to parameter of type 'never'.
  Overload 2 of 2, '(collection: never, filter?: ((entry: never) => unknown) | undefined): Promise<never[]>', gave the following error.
  Argument of type '"techs"' is not assignable to parameter of type 'never'.

  # terminal 一樣執行
  npx astro sync
  # 執行完後，會掃描 src/content/ 資料夾中的所有內容，並生成對應型別

第五步：Vercel 部署

1. 將程式碼推送到 GitHub。
2. 登入 Vercel。
3. 點擊 Import Project 並選擇該 Repo。
4. Vercel 會自動偵測到這是 Astro 專案，保持預設設定即可。
5. 點擊 Deploy。

💡 下方提供一些可以使用的 Markdown 範例檔案

src/content/techs/astro.md

---
name: 'Astro'
status: 'mastered'
icon: '🚀'
---

Astro 是我目前最愛的 Web 框架，其「孤島架構」(Islands Architecture) 能極大化減少客戶端 JS 載入量。

src/content/techs/tailwind-v4.md

---
name: 'Tailwind CSS v4'
status: 'learning'
icon: '🎨'
---

全新的氧化物引擎 (Oxide engine)，不再需要繁瑣的 `tailwind.config.js`，速度快到令人髮指！

src/content/techs/rust.md

---
name: 'Rust'
status: 'wishlist'
icon: '🦀'
---

聽說性能強大且記憶體安全，是我 2026 年一定要排進時程學習的語言。

src/content/techs/nanostores.md

---
name: 'Nano Stores'
status: 'mastered'
icon: '🧪'
---

極簡、輕量、去中心化的狀態管理工具，配合 Astro 這種多框架環境簡直是天作之合。