.astroと.tsx＋CSS Modules、両方使ってわかったAstro開発体験の違い

Qlip（株式会社クリップ）のフロントエンドエンジニアの岡田です。
案件でAstroを使う中で、astro構文とtsx + CSS Modulesの両方に触れる機会がありました。

どちらの構成で組むべきか、場面によって迷うこともあるかと思います。
この記事では、実際の開発体験をもとに、それぞれの特徴や良かった点・気になった点などをまとめています。
選択に迷った際の参考になれば幸いです。

Astroとは

コンテンツ重視のウェブサイトを高速に構築するためのモダンなフロントエンドフレームワークです。Webサイトの速度とパフォーマンスを最大化することができ、React・Vue・Svelteなどのフレームワークなどと併用できる特徴を持っています。

tsxとCSS Modulesとは

tsx

Reactなどのライブラリを使って開発を行う際に、TypeScriptとjsxを組み合わせたファイルを指します。
TypeScriptの型チェック機能と、jsxの直感的でわかりやすい構文を利用できます。より安全で効率的なコンポーネント開発が可能になります。

CSS Modules

CSSのクラス名やアニメーション名をローカルスコープに限定することで、クラス名の衝突を防ぎ、コンポーネント指向の設計を可能にするための仕組みです。
コンポーネントにスタイルが紐づくため、予期せぬスタイルの衝突が起こりづらくなる他にスタイル等の追跡・修正が行いやすくなります。

.astroでの開発体験

Astroでは、.astroという拡張子で開発を行うことができます。標準で備わっているAstro本来の書き方の開発体験を記載します。

書き方の特徴（マークアップ・スタイル）

一般的なHTMLとCSSの記述スタイルを使用できる点が特徴としてあります。以下のように1つのファイルの中にそれぞれ記述ができるため、ファイルの往復を行わなくても良いです。

<main>
　<p>テキストが入ります。</p>
</main>

<style lang="scss">
  main {
    width: 100%;
    min-height: 100vh;
  }
</style>

また、ReactやVueのようなフレームワーク同様にコンポーネント単位で読み込み値を渡すことも可能です。

---
import Layout from '../layouts/Layout.astro';
const pageTitle = "トップページ";
---

<Layout title={pageTitle}>

</Layout>

.astroを使って感じたこと

.astro(Astro専用の構文)を使用して実際に感じた良い点と課題点を整理しています。

良かった点

• 通常通りのHTMLやCSSの書き方ができるので、導入コストが低く馴染みやすい。

• 1つのファイルにまとめて記述できるので、管理がしやすい

• サーバー側とクライアント側の記述場所が明確で見やすい

気になった点

• コード量が多くなるとコードの見通しが悪くなってしまう

• コンポーネントにCSSやJSがまとまっているため、コンポーネント単位の共通化がしにくい

• .astroはAstro専用の構文なので、他のプロジェクトやフレームワークに移植しづらい

tsx＋CSS Modulesでの開発体験

Astroではなく、tsxファイルを使用してスタイルをCSS Modulesで行った際の開発体験を記載します。

書き方の特徴（マークアップ・スタイル）

tsx

関数コンポーネント＋明示的な Props 型定義が基本となっています。一般的なHTMLというよりは、JavaScriptを扱っているような感覚に近いです。普段書いているclassもclassNameに変わる点も特徴として挙げられます。

import styles from "./Mv.module.scss";

export default function MvSection() {
  return (
    <div className={styles.wrapper}></div>
  );
}

データの受け渡し(Props)がある場合は、以下のように型を定義してより安全にデータを扱うことができます。

interface FaqItem {
  id: number;
  question: string;
  answer: string;
}

const faqData: FaqItem[] = [
  {
    id: 1,
    question: "",
    answer: "",
  },
];

export default function FaqSection() {
  return (
          <ul className={styles.items}>
          　{faqData.map((faq: FaqItem) => (
              <li key={faq.id} className={styles.item}></li>
            ))}
          </ul>
  );
}

CSS Modules

JavaScript側にインポートして利用する点が大きな特徴として挙げられます。これにより型補完やリファクタリングの恩恵を受けやすくなります。

import styles from "./Button.module.css";

export function Button() {
  return <button className={styles.root}>Click</button>;
}

ユニークな名前が自動で付与されるため、クラス名を端的にすることが可能です。これにより名前空間を意識して命名する必要がないので、非常に快適に進めることができます。

//Button.module.css

.root {
  padding: 12px;
}

tsx + CSS Modulesを使って感じたこと

tsx + CSS Modulesを使用して実際に感じた良い点と課題点を整理しています。

良かった点

• 複雑なロジックや状態管理の場合は、型定義や補完のおかげで安心できる

• CSS Modulesはクラス名が自動でユニーク化されるので、スタイルの衝突がおこらない

• CSS Modulesはコンポーネント毎にスタイルが完結するので、再利用がしやすく長期的に見て運用しやすい

気になった点

• tsxコンポーネントとmodule.cssファイルの行き来が発生してしまう

• CSS Modulesはスコープが自動的に閉じてしまうため、グローバルなスタイル適用が若干面倒になってしまう

• 純粋なマークアップをコンポーネント化すると冗長になってしまう

実際に感じた違い

Astro本来のAstroファイルは、HTMLとCSSをそのまま書けるため、マークアップ中心のサイト制作に非常に向いていると感じました。特にコンテンツ量の多いコーポレートサイトや採用サイトなどでは、構造を意識しながら視覚的に全体を把握できる点が大きな利点です。
一方で、tsx＋CSS Modulesを使うと、ロジックの制御や動的なコンポーネントの構築が格段にしやすくなります。フォームやFAQ、アニメーションを伴うセクションなど、「状態」や「繰り返し構造」が関わる場面では、TypeScriptの型安全性が非常に心強く感じました。
また、CSS Modulesの自動スコープ化によって、スタイルの管理がより明確になり、複数人での開発でも安心して進められます。

どう使い分けるのがよさそうか

最も大きな基準は「静的か、動的か」だと感じます。
静的なページ構成で、主にHTMLとCSSで完結する部分はAstroファイルで書くのがシンプルで速いです。構造を直感的に把握しやすく、メンテナンス性も高くなります。
例えば、シンプルなコーポレートサイトやランディングページのようなものが該当すると思います。
一方、動的なデータの連携や複雑なUIコンポーネントが必要な場合は、tsxとCSS Modulesの組み合わせの方が長期的な運用を考えてもよさそうです。ロジックを整理しやすく、型の恩恵も受けられ、より安全に開発ができると感じました。

最終的には、「ページの目的」と「メンテナンス性」を基準に、Astroとtsxを適材適所で使い分けるのがベストだと思います。

おわりに

今回は、Astroとtsx + CSS Modulesの開発体験の違いについて紹介しました。それぞれに良さがあると感じました。
どちらかというと.astroの方が一般的な制作の書き方に近しい部分があるので、まずはこちらから触って慣れていくのも良いのではないかと思います。
皆さんもそれぞれの組み合わせを試して、開発体験の違いを感じてみてください。

最後まで読んでいただきまして、ありがとうございました！
また次の記事でお会いしましょう🙌