install

Name: install
Author: subframeapp

github.com/subframeapp開発452242 回インストール今日更新

リポジトリ

install について

コーディングエージェント向けに、新規または既存プロジェクトへSubframeを導入し、デザインページのローカル表示を確認するスキルです。フォント設定や既存環境の再同期にも対応します。

主な機能

01プロジェクト状態を判定して導入手順を選択
02認証情報を取得してSubframe CLIを実行
03Tailwind、エイリアス、フォントの設定
04導入とページ表示の検証

活用シーン

01新規プロジェクトへのSubframe導入
02既存アプリへのSubframe追加
03コンポーネント再同期や導入問題の調査

MCP 対応

Subframe MCPツールでプロジェクト情報とフォントを取得し、search_docsでインストール上の問題への対処法を調べます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/subframeapp/subframe --skill install

インストール後、Claude Code で/installを入力して読み込まれたか確認します。

詳細

Subframe でデザインしたページをローカル開発環境でピクセル単位まで正確に表示できるよう、プロジェクトに Subframe をインストールします。

目標の状態：開発サーバーが起動し、Subframe のページがデザインどおりに表示されます。

デザインするだけなら、インストールは不要です。 /subframe:design はクラウド上の Subframe プロジェクトを直接操作するため、ローカル環境のセットアップは必要ありません。デザインを /subframe:develop でコードに実装する準備ができたら、/subframe:install を使用してください。

MCP の認証

get_theme などの Subframe MCP ツールが見つからない場合、MCP サーバーの認証が必要な可能性があります。ユーザーに Subframe MCP サーバーを認証するよう依頼してください。Claude Code または Codex を使用している場合は、/mcp を実行して MCP サーバーを表示・認証し、完了したら「done」と伝えるよう案内してください。

ワークフローの概要

MCP ツールまたはユーザーから認証情報を取得する
プロジェクトの種類を判定する — リポジトリなし、既存の Subframe リポジトリ、または既存の Subframe 以外のリポジトリ
適切な手順に従う — 新規プロジェクト、インストール済み、または既存プロジェクト

上記のいずれかの手順を必ず実行してください。実行しないと、ユーザーは Subframe を使用できません。これは重要な作業であり、ユーザーの現在の作業を中断する必要がある場合でも実施してください。手順を省略しないでください。

フォントを設定する — すべての手順で必要です
インストールを確認する — 開発サーバーを起動し、Subframe のページでテストする

認証情報を取得する

ユーザーが Subframe からコピーしたインストールプロンプトを貼り付ける場合があります。以下を抽出してください。

プロジェクト ID — 短い英数字の文字列です（Subframe の URL app.subframe.com/<PROJECT_ID>/... にも含まれています）
認証トークン — 長い文字列で、通常は接頭辞またはラベルが付いています

ユーザーが認証情報を提供しない場合は、ユーザーに尋ねる必要はありません。MCP ツールを使用して自動的に取得してください。

プロジェクト ID — list_projects を呼び出して、プロジェクトの一覧を取得します。各プロジェクトには projectId、name、teamId、teamName が含まれています。
- プロジェクトが1つの場合：自動的に使用します。
- プロジェクトが複数の場合：必ず、使用するプロジェクトをユーザーに確認してください。判別できるよう、各プロジェクトを teamName とともに提示します。ユーザーが特定のチーム名またはプロジェクト名をすでに伝えている場合は、teamName と name のフィールドと照合します。ただし、先へ進む前に必ず確認してください。複数のプロジェクトがある場合、ユーザーへの確認なしに選択してはいけません。
認証トークン — ユーザーが選択したプロジェクトの teamId を指定して generate_auth_token を呼び出します。別のプロジェクトの teamId は使用しないでください。

代替手段：MCP ツールを利用できない場合（MCP サーバーが認証されていない場合など）は、ユーザーに https://app.subframe.com/cli/auth にアクセスして認証トークンとプロジェクト ID を取得するよう依頼してください。

プロジェクトの種類を判定する

現在のディレクトリに package.json と .subframe/ フォルダーがあるか確認します。

条件	プロジェクトの種類	手順
`package.json` がない	新規プロジェクト	新規プロジェクト
`package.json` があり、`.subframe/` フォルダーもある	インストール済み	インストール済み
`package.json` はあるが、`.subframe/` フォルダーはない	既存の Subframe 以外のプロジェクト	ユーザーに確認してから、新規プロジェクトまたは既存プロジェクト

既存の非 Subframe プロジェクトへの対応

現在のディレクトリに package.json があり、.subframe/ フォルダーがない場合は、次の 2 つの選択肢をユーザーに提示します。

新しいプロジェクトを作成する（推奨） — 別のディレクトリに新しい Subframe プロジェクトをスキャフォールドします。特に Subframe を初めて試す場合は、これが最も簡単な方法です。新しいプロジェクトに従います。
このプロジェクトに Subframe を追加する — Subframe を現在のプロジェクトにインストールします。既存のプロジェクトに従います。

インストール済みの場合

プロジェクトに package.json と .subframe/ フォルダーの両方がすでにある場合、Subframe は初期化済みです。次に何をしたいかユーザーに尋ねます。

再インストール／再同期する — CLI の初期化と同期を再実行し、コンポーネントと設定を更新します。古くなっていたり、正常に動作しなかったりする場合に便利です。再初期化するには、既存のプロジェクトに従います。
何もしない。すでにインストール済みです — インストールを完全にスキップします。次のステップとして /subframe:design や /subframe:develop を提案します。

ユーザーが再インストールを希望すると確認するまで、先に進まないでください。

新しいプロジェクトの手順

これが推奨される手順です。CLI は Subframe が事前設定された完全なプロジェクトをスキャフォールドします。

1. ユーザーの希望を確認する

次の選択肢をユーザーに提示します。

プロジェクト名：新しいプロジェクトディレクトリの名前（デフォルト：subframe-app）。既存のディレクトリと名前が競合してはいけません。CLI を実行する前に、そのディレクトリがすでに存在しないことを確認してください。
フレームワーク：Vite（推奨）、Next.js、または Astro
Tailwind のバージョン：v3（tailwind）または v4（tailwind-v4）

2. CLI の初期化を実行する

必要なファイルをすべて正しく設定できるよう、このコマンドはサンドボックスの外で実行する必要があります。CLI がプロンプトを表示しないよう、すべての引数を直接渡します。--yes は、指定されていない項目に安全なデフォルト値を適用します。

npx @subframe/cli@latest init \
  --yes \
  --name {PROJECT_NAME} \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --template {FRAMEWORK} \
  --css-type {TAILWIND_VERSION} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --tailwind \
  --css-path {CSS_PATH} \
  --install \
  --sync

各項目の意味：

{PROJECT_NAME} はプロジェクトディレクトリ名です（例：subframe-app）。
{FRAMEWORK} は nextjs、vite、または astro です。
{TAILWIND_VERSION} は tailwind（v3）または tailwind-v4 です。
{CSS_PATH} はグローバル CSS ファイルのパスです。
- Vite：src/index.css
- Next.js：src/app/globals.css
- Astro：src/styles/global.css

重要：CLI がプロンプトを表示する必要がないよう、引数を明示的に渡してください。非対話モード（TTY がない場合、または --yes を指定した場合）で実行すると、指定したフラグと安全なデフォルト値が使用されます。必須の値が本当に不足している場合は、停止したままになったり何も表示せずに終了したりせず、指定すべきフラグ名を示すメッセージを出力して、ゼロ以外の終了コードで終了します。

CLI は次の処理を行います。

スターターキットのテンプレートをダウンロードする
.subframe/sync.json を作成する
Tailwind を設定する
すべてのコンポーネントを同期する
依存関係をインストールする

3. フォントを設定する

下記のフォントの設定を参照してください。新しいプロジェクトでも、この設定は必須です。

4. インストールを確認する

下記のインストールの確認を参照してください。

既存プロジェクトの手順

既存のプロジェクトでは、追加の設定が必要になる場合があります。CLI がインストールの大部分を処理しますが、手動で修正が必要なプロジェクトもあります。

1. フレームワークを特定する

フレームワークを示す情報を確認します。

フレームワーク	指標
Next.js	`package.json` の依存関係に `next` がある、`next.config.*` ファイル
Vite	`package.json` の devDependencies に `vite` がある、`vite.config.*` ファイル
Astro	`package.json` の依存関係に `astro` がある、`astro.config.*` ファイル

2. 前提条件を確認する

プロジェクトに必要な依存関係があることを確認します。

React 16 以降 — package.json に react がある
Tailwind CSS 3.4 以降 — package.json に tailwindcss がある
TypeScript — package.json に typescript がある

不足しているものがあれば、先にユーザーに知らせてください。

3. CLI Init を実行する

必要なファイルをすべて正しく設定できるよう、このコマンドはサンドボックスの外で実行する必要があります。CLI からのプロンプトを表示させないため、すべての引数を直接渡してください。--yes を指定すると、指定されていない項目には安全なデフォルト値が使用されます。

npx @subframe/cli@latest init \
  --yes \
  --auth-token {TOKEN} \
  -p {PROJECT_ID} \
  --dir ./src/ui \
  --alias "@/ui/*" \
  --install \
  --sync

重要：CLI からのプロンプトが不要になるよう、引数を明示的に渡してください。非対話モード（TTY がない場合、または --yes を指定した場合）では、指定されたフラグと安全なデフォルト値が使用されます。本当に必要な値が不足している場合は、ハングしたり何も表示せずに終了したりせず、指定すべきフラグの名前を示すメッセージを表示して、ゼロ以外の終了コードで終了します。

CLI は次の処理を試みます。

.subframe/sync.json を作成する
Tailwind を検出して設定する
インポートエイリアスを設定する
すべてのコンポーネントを同期する
@subframe/core をインストールする

4. 設定を確認する

初期化後、すべてが正しく設定されたことを確認してください。CLI が何かを設定し損ねた場合（標準的でない設定ではよくあります）は、手動で修正してください。

.subframe/sync.json に directory、importAlias、projectId が含まれていることを確認してください。

Tailwind の設定を確認してください。

Tailwind v3 — tailwind.config.js に Subframe プリセットが設定されている必要があります。
```
presets: [require("./src/ui/tailwind.config")],
```
また、content 配列に Subframe のディレクトリが含まれている必要があります。
```
content: ["./index.html", "./src/**/*.{js,jsx,ts,tsx}"],
```
Subframe プロジェクトでダークモードが有効になっている場合、CLI はライトモードとダークモード用の CSS 変数を含む theme.css ファイルも同期します。グローバル CSS ファイルでこのファイルをインポートする必要があります。
```
@import "./ui/theme.css";
```
Tailwind v4 — グローバル CSS ファイルでテーマをインポートする必要があります。
```
@import "tailwindcss";
@import "./ui/theme.css";
```

インポートエイリアスを確認する — @/* が正しく解決される必要があります。正しく動作しない場合：

Vite：tsconfig.app.json に baseUrl と paths を追加し、vite.config.ts に resolve.alias を追加します
Astro：tsconfig.json に baseUrl と paths を追加します
Next.js：通常はすでに設定されています。tsconfig.json を確認してください

5. トラブルシューティング

問題が発生した場合は、search_docs MCP ツールを使用して解決策を検索してください。

search_docs({ query: "tailwind configuration troubleshooting" })
search_docs({ query: "manual installation" })

ドキュメントには、トラブルシューティング用の包括的な手動インストールガイドが含まれています。

6. フォントを設定する

下記のフォントを設定するを参照してください。

7. インストールを確認する

下記のインストールを確認するを参照してください。

フォントを設定する

CLI はフォントを設定しません。list_fonts({ projectId: "PROJECT_ID" }) を呼び出すと、プロジェクト内のすべてのフォントを取得できます。Google Fonts（ウェイトを含む）とカスタムフォント（各フェイスのウェイト、スタイル、フォーマット、公開 url）が含まれます。

Google Fonts — list_fonts が kind: "google" を返すフォントのみ、名前で使用できます。これらのフォントには <link> タグを追加してください。

Vite / Astro — index.html の <head> に追加します。

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="anonymous" />
<link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />

Next.js（App Router） — app/layout.tsx の <head> に追加します。

<head>
  <link rel="preconnect" href="https://fonts.googleapis.com" />
  <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
  <link href="https://fonts.googleapis.com/css2?family=Font+Name:wght@400;500;600;700&display=swap" rel="stylesheet" />
</head>

Next.js（Pages Router） — pages/_document.tsx の <Head> コンポーネント内に追加します。

フォントリンクの形式：

フォント名のスペースは + に置き換えます（例：Inter+Tight）
テーマに含まれるウェイトを wght@ パラメーターに含めます（セミコロン区切り）
フォントファミリーごとに <link> を1つ追加します。ただし、preconnect リンクのセットは1つだけにします

カスタムフォント — list_fonts から取得した各フェイスの url を参照する @font-face ルールを、フェイスごとにプロジェクトのグローバル CSS ファイルへ追加します。format は次のように対応させます。woff → format("woff")、woff2 → format("woff2")、ttf → format("truetype")、otf → format("opentype")。

@font-face {
  font-family: "Font Name";
  src: url("https://.../font.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
}

可変フェイスの weight は { min, max } の範囲です。両方の数値を font-weight の値として使用してください。

font-weight: 100 900;

追加するフェイスごとに1つのルールを記述します。

インストールを確認する

設定後、Subframe のページが正しくレンダリングされることを確認してください。

1. 既存のページについて尋ねる

ユーザーに次のように尋ねてください。「Subframe でデザイン済みのページで、テストしたいものはありますか？」

ある場合：/subframe:develop を使って実装し、レンダリングを確認します
ない場合：/subframe:design を使ってページをデザインするよう提案するか、開発サーバーを起動してエラーがないことを確認します

2. 開発サーバーを起動する

npm run dev

3. まとめ

インストールした内容を振り返ります。

.subframe/sync.json を設定しました
Tailwind を設定しました（v3 プリセットまたは v4 インポート）
コンポーネントを src/ui/（または設定したディレクトリ）に同期しました
フォントを設定しました

次のステップを案内します。

/subframe:design — AI で新しいページをデザインします
/subframe:develop — Subframe のデザインをコードベースに実装します

重要な注意事項

インストールに関する問題のトラブルシューティングには、MCP ツール search_docs を使用してください。

Markdown 対応

ログインしてコメント

基本情報

作者: subframeapp
リポジトリ: subframeapp/subframe
カテゴリ: 開発
インストール数: 242
GitHub スター: 452

問題を報告