お問い合わせ

Topics

npmを使わずにプライベートなAstroコンポーネントを共有する方法

  • column

コンポーネントの共有管理

Web開発において、複数のWebサイトで同じUIコンポーネントを再利用したいケースは稀に発生しますよね？

Astroのようなモダンなフレームワークを使用して、複数サイトの開発を効率化したい場合、コンポーネントライブラリ共有はとても有効です。ただ、コンポーネントをnpmパッケージとして共有する場合、プライベートパッケージの公開には有料プランが必要になってしまいますよね。

今回はnpmでパッケージ化せずにGitHubリポジトリとCloudflare Pagesを使って、効率的にコンポーネントを共有・管理する方法をご紹介します！

コンポーネント共有の課題は!?

  • 複数のAstroサイトで同じUIコンポーネントを使用したい！
  • Cloudflare Pagesでホスティングしたい！
  • GitHubのプライベートリポジトリでコンポーネント管理したい！
  • コンポーネントをnpmパッケージ化したいが、公開はしたくない！

こんな感じですね。ではどうするといいのでしょうか。

GitHubリポジトリとカスタムビルドスクリプトで解決する

これらの課題を解決するため、こんな感じで対処してみるのはいかがかと思います。

  1. コンポーネント用のGitHubリポジトリを作成
  2. ローカル開発ではファイル参照を使用
  3. Cloudflare Pages環境ではビルド時にコンポーネントリポジトリをクローン

npmプライベートパッケージを使わずに、コンポーネントの共有と管理が可能になります。

実装はこんな感じ

1. GitHub Personal Access Tokenを作成

プライベートリポジトリにアクセスするためのGitHub Personal Access Tokenを作成します。

  1. GitHubにログイン
  2. 右上のプロフィールアイコンをクリック → Settings
  3. 左側のサイドバーから「Developer settings」→「Personal access tokens」→「Tokens (classic)」を選択
  4. 「Generate new token」→「Generate new token (classic)」をクリック
  5. トークンに以下の権限を付与：
    • repo - プライベートリポジトリへのフルアクセス
  6. トークンを生成し、安全な場所に保存（表示されるのは一度だけ）

2. コンポーネントライブラリの構築

コンポーネント用のGitHubリポジトリを作成します （例：github.com/your-username/ui-components）。

コンポーネントライブラリのpackage.json

{
  "name": "@your-org/components",
  "private": true,
  "type": "module",
  "main": "src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  },
  "files": [
    "src"
  ],
  "peerDependencies": {
    "astro": "^5.7.12"
  }
}

3. メインプロジェクトを設定

コンポーネントを使用するメインプロジェクトのpackage.jsonを設定します。

メインプロジェクトのpackage.json

{
  "name": "your-astro-project",
  "type": "module",
  "private": true,
  "config": {
    "componentVersion": "v1.0.0",
    "orgName": "your-username",
    "repoName": "ui-components",
    "namespace": "your-org",
    "packageName": "components"
  },
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro",
    "setup-components": "set -e; ORG_NAME=\\\\"$npm_package_config_orgName\\\\"; REPO_NAME=\\\\"$npm_package_config_repoName\\\\"; NAMESPACE=\\\\"$npm_package_config_namespace\\\\"; PACKAGE_NAME=\\\\"$npm_package_config_packageName\\\\"; VERSION=\\\\"$npm_package_config_componentVersion\\\\"; mkdir -p temp; git clone -b $VERSION <https://$GITHUB_TOKEN@github.com/$ORG_NAME/$REPO_NAME.git> temp/$REPO_NAME; mkdir -p node_modules/@$NAMESPACE; ln -sf $(pwd)/temp/$REPO_NAME node_modules/@$NAMESPACE/$PACKAGE_NAME",
    "build-with-components": "npm run setup-components && npm run build"
  },
  "dependencies": {
    "@your-org/components": "file:../ui-components"
  },
  "devDependencies": {
    // Astroなどの開発依存関係
  }
}

以下4点が肝です。

  1. config セクション：コンポーネントライブラリの情報を一元管理
  2. setup-components スクリプト：ビルド時にGitHubからコンポーネントをクローン
  3. build-with-components スクリプト：コンポーネントのセットアップとビルドを組み合わせたコマンド
  4. dependencies：ローカル開発用のファイル参照

4. ローカル開発環境を設定

コンポーネントライブラリをプロジェクトと同階層にクローンして、ファイル参照で使用しましょう。

projects/
  ├── ui-components/         # コンポーネントライブラリ
  └── your-astro-project/     # メインプロジェクト

ローカルでの開発中にコンポーネントを変更すると、メインプロジェクトにすぐに反映されます。

5. Cloudflare Pagesの設定

Cloudflare Pagesでの設定はこちらです。

  1. 環境変数の設定:
    • Pagesダッシュボード → your-project → Settings → Environment variables
    • 変数名: GITHUB_TOKEN
    • 値: 作成したGitHub Personal Access Token
  2. ビルドコマンドの設定:
    • Pagesダッシュボード → your-project → Settings → Build & deployments
    • Build command: npm run build-with-components
    • Build output directory: dist（デフォルト）

ビルド時に指定バージョンのコンポーネントライブラリが自動的にクローンされて組み込まれます。

設定完了でコンポーネントをお手軽利用

設定完了したら、コンポーネントを使用するのはとても簡単です。

コンポーネントライブラリにsrc/index.tsを作成し、コンポーネントをエクスポートします。

export { default as Button } from './components/base/Button.astro';
export { default as Heading } from './components/base/Heading.astro';
// 他のコンポーネントもここでエクスポート

メインプロジェクト側で使用したいコンポーネントをインポートします。

---
import { Button, Heading } from '@your-org/components';
---

<div>
  <Heading>Hello World</Heading>
  <Button>Click me</Button>
</div>

バージョン管理は？

コンポーネントライブラリの新しいバージョンをリリースしたい時は、

  1. コンポーネントライブラリに変更を加えコミット
  2. 新しいタグを作成（例：v1.1.0）
  3. メインプロジェクトのpackage.jsonを更新
    "config": {
  "componentVersion": "v1.1.0",
  // 他の設定...
}

各プロジェクトが必要なバージョンのコンポーネントを使用できます。

開発フローも安全

安全で効率的な開発フローは、気にする部分も少なくて嬉しいですね。

  1. コンポーネントライブラリで新機能の開発や改修を行う（例: feature/new-buttonブランチ）
  2. ローカル環境でその変更を即座にメインプロジェクトでテスト・確認できる
  3. 開発が一定段階まで進んだら、テスト用のタグを作成（例: v1.1.0-test）
  4. メインプロジェクトのテスト環境用ブランチでcomponentVersionをテスト用タグに更新し、テスト環境にデプロイ
  5. テスト環境で問題ないことを確認したらコンポーネントライブラリのmainブランチにマージ
  6. 新しいバージョンタグを作成し、メインプロジェクトのバージョンを更新することで本番に反映される（例: v1.1.0）

本番環境への影響なくコンポーネントの変更をテストできるのがポイント！

Cloudflare Pagesの本番環境はconfig.componentVersionで指定されたタグのバージョンを利用するので、新しいタグを作成してconfigを更新しない限り、変更が本番環境に影響することがないので安心です！

■ npmのプライベートパッケージを使わずに、GitHubプライベートリポジトリとカスタムビルドスクリプトを組み合わせる！

■ GitHub Tokenの適切な管理と、ローカル開発環境の正しい設定によりチーム全体でシームレスなコンポーネント共有！

いかがでしょうか？

小〜中規模のチームや、コスト効率を重視するプロジェクトに最適ではないでしょうか？

将来的にチームやプロジェクトが成長した場合、npmプライベートパッケージへの移行も検討できますが、当面はこの方法で十分に効率的なコンポーネント共有が実現できると思います！

補足: Astro以外のフレームワーク（React, Vue, Svelteなど）でも応用可能です。設定の詳細は異なる場合がありますが、基本的なアプローチは同じです！Cloudflare Pages以外のホスティングサービスでも、同様の方法でビルドプロセスをカスタマイズできますよ。

この記事を書いた人

Web黎明期にグラフィックデザインからWebの世界へ飛び込み、気づけばマークアップもフロントエンドもディレクションもアクセシビリティもこなす"技の仙人"。リベロジック創業期からマルチに活躍し、今や社内の生き字引的存在。最近は「アクセシビリティ対応、もっとAIに頼れないかな？」と、プロンプトを駆使した効率化の探究にハマり中。技術も思考も、まだまだ進化中

フタさん

マークアップエンジニア／フロントエンドエンジニア／ウェブアクセシビリティエンジニア／ウェブディレクター

安心のチーム体制とスピードのある対応力が自慢

リベロジックでは、ベテランスタッフが積極的にプロジェクトを推進するため、お客様から高く評価されています。
プロジェクトマネージャー、ディレクターをきちんとアサインし、プロジェクト全体をスムーズに進行することを心掛けています。 不必要なフルコミットでのコスト増加を防ぎ、適材適所にリソースを配分するスタイルで、業務内容の把握から見積作成/提出の速さにも定評があります。

※ 当社はSES的な常駐業務等は積極的に行っておりませんので予めご了承ください。

Slack、Teams、Redmine、Backlog、Asana、Jira、Notion、Google Workspace、Zoom、Webexなど、ほぼすべての主要なプロジェクト管理ツールやチャットツールをご利用いただけます。

SESやオフショアを利用する大規模案件において、技術的な課題や取り組み方にお悩みはございませんか？

フロントエンド実装のお問い合わせはこちら

ケーススタディ