Panda CSSでスタイリングしたAstroのデザインテーマAstro Sarkraをv2にアップデートしました。Astro Sarkaraは2023年10月にv1をリリースしており、11ヶ月ぶりのメジャーバージョンです。このサイトもAstro Sarkaraで作成しています。

v2の新機能

新機能は、ありません！

Astro Sarkara v2はPanda CSSの仕様変更に対応することが主目的でした。

Panda CSSの仕様変更

Astro Sarkara v1ではPanda CSSのemitPackageという機能を使っていました。
この機能がPanda CSS v0.32(2024年3月)で非推奨 となり、 v0.42(2024年7月)で廃止された ことから、代替の方法を見つける必要がありました。

emitPackageは、通常プロジェクトのルートに生成されるPanda CSSのスタイルシステムをnode_modules傘下に生成することによって、スタイルシステムを擬似的にパッケージとして扱う方法です。この機能により、パッケージ(@cieloazul310/astro-sarkara)に含まれるコンポーネントとユーザーが同じスタイルシステム(node_modulesに生成する@cieloazul310/sarkara-css)を参照することができました。

emitPackage廃止の代替として、コンポーネントライブラリにおいてはimportMapという機能を使うことが推奨されていましたが、試してみたところあまり上手くいきませんでした。

雑記

v2へのアップデートに関連するあれこれをメモしておきます。

Astroの設定ファイルはPath aliasを感知しない

Astroの設定ファイルastro.config.tsはTSConfigのPath aliasを感知しません。Astro設定ファイルでインポートするファイルからPath aliasを除外しなければ、Astroは正常に動作しません。次項に続きます。

Support Typescript paths/aliases in astro.config.ts #9789
https://github.com/withastro/astro/pull/9789

article-classesパッケージの削除と代替案

Astro Sarkara v1では、Astro ConfigのRehypeプラグインでPandaのスタイルを適用するためのパッケージを同梱していました。下記のようにrehype-class-namesというRehypeプラグインと併用することで、Markdown/MDXのページにAstro Sarkaraのスタイルを適用することが可能でした。

// astro.config.ts
import { defineConfig } from "astro/config";
import rehypeClassNames from "rehype-class-names";
import articleClasses from "@cieloazul310/astro-sarakara/article-classes";

console.log(articleClasses);
// => Object { h1, h2, h3, ... }

export default defineConfig({
  markdown: {
    rehypePlugins: [[rehypeClassNames, articleClasses]],
  },
});

Astro Sarkara v2では前述の通り、Panda CSSのemitPackage廃止に伴い、代替としてTSConfigのPath aliasをパッケージ内で用いる方法を採っています。しかしながら、Astroの設定ファイルはPath aliasを感知しないため、v1の方法でRehypeプラグインでクラス名を与えることはできません。困りました。

解決策としてHTML要素にクラス名を与えるSlot RecipeをAstro Sarkaraのプリセットに組み込むことにしました。

プロジェクトのsrc傘下にmdx-classes.tsを作成します。スタイルシステムを相対パスから参照し、articleClassesというレシピをインポートします。レシピは関数なので、その返り値をデフォルトエクスポートします。

// src/mdx-classes.ts
import { articleClasses } from "../../styled-ststem/recipes";

export default articleClasses();
// => Object { h1, h2, h3, ... }

Astroの設定ファイルから先のファイルを読み込み、rehype-class-namesのオプションに渡すことで、結構強引な方法ではありますが、v1と同様の動作を実装することができました。

// astro.config.ts
import { defineConfig } from "astro/config";
import rehypeClassNames from "rehype-class-names";
import articleClasses from "./src/mdx-classes";

console.log(articleClasses);
// => Object { h1, h2, h3, ... }

export default defineConfig({
  markdown: {
    rehypePlugins: [[rehypeClassNames, articleClasses]],
  },
});

Changesetsでプレリリース

Astro SarkaraはChangesetsを用いてバージョン管理とNPMへの公開を行なっています。v2のプレリリースをChangesetsで行う場合、通常のリリースフローと異なる手順が必要になったので、メモとして書き残しておきます。

Changesetsでプレリリースバージョンを扱う場合は、メインブランチ以外のブランチで作業することが推奨されています。

1. プレリリース専用のブランチを切る

ローカル環境でdevelopブランチからprereleaseブランチを切ります。

2. プレリリースモードに切り替える

changeset pre enter <tag>コマンドを打ち、プレリリースモードに切り替えます 。<tag>はバージョンの後に付くタグのことです。例えばchangeset pre enter nextというコマンドで入ったプレリリースモードでは、バージョン名は1.0.0-next.0となります。

npm run changeset pre enter next

3. プレリリースのためのワークフローを作成

既存のリリースワークフローを複製してプレリリース用のワークフローを作成します。既存のリリースワークフローと内容は同じなので、既存のワークフローのトリガー条件、on.push.branchesにprereleaseブランチを追加する方法を採ってもよかったかもしれません。

# release.yml
name: Release

on:
  push:
    branches:
      - main
      - prerelease

4. プレリリースモードを終了する

npm run changeset pre exit

プレリリースを続けて行う場合はプレリリースモードを終了する必要はありません。通常のリリースに戻るには上記コマンドを打ってプレリリースモードを終了する必要があります。

プレリリースモードを終了し、通常のリリースを行うと、.changeset傘下に生成されるプレリリース関連のファイルが消去されます。

まとめ

Panda CSSでAstroのコンポーネントライブラリを作成している例がほとんど見当たらず、試行錯誤しながらになりましたが、Astro Sarkaraは一つの作成例として提示できるものになっていると思います。

反省点としては、Panda CSSにおいてemitPackageが非推奨となったことを早々に把握してながら、半年近く対策を怠ったことが挙げられます。

ひとまずAstro Sarkara v2の作成によって、このサイトで用いているPanda CSSのバージョンを最新版にアップデートすることができました。自分が作成したパッケージが原因で他のパッケージをアップデートできない状態になるのは心地悪いので、今後は早急に対処できるように心がけます。

Traces of You (featuring Norah Jones) / Anoushka Shankar (2013)