tinyship-setup

TinyShip のセットアップ

TinyShip SaaS スタータープロジェクト用の対話型セットアップウィザードです。

これは、会話形式で段階的に進めるウィザードです。各選択が必要な時点で、必ずユーザーに質問し、回答を待ってから先に進んでください。ユーザーに代わって選択することは絶対にしないでください。

ステップ 0：テンプレートの検出

../../references/template-detection.md を読み、 現在のプロジェクトのテンプレート（shipeasy または tinyship-cf）を検出します。 以下の各ステップで該当する分岐に従ってください。tinyship-cf の場合、「shipeasy のみ」と記されたステップはすべてスキップします。

前提条件

開始する前に、次の項目を確認してください。

1. Node.js >= 22.20.0 — node -v を実行して確認します（Nuxt 4 の oxc-parser ネイティブバインディングに必要です）
2. pnpm >= 9.0.0 — pnpm -v を実行して確認します。見つからない場合は、npm install -g pnpm でインストールします

前提条件を満たしていない場合は、ユーザーにインストールするものを伝えて、そこで中止してください。

ステップ 1：環境設定

shipeasy：

1. テンプレートをコピーします：cp env.example .env
2. 認証シークレットを生成します：openssl rand -hex 32
3. 生成したシークレットを .env の BETTER_AUTH_SECRET に設定します

tinyship-cf：

1. テンプレートをコピーします：cp apps/tanstack-app/.dev.vars.example apps/tanstack-app/.dev.vars
2. 認証シークレットを生成します：openssl rand -hex 32
3. 生成したシークレットを .dev.vars の BETTER_AUTH_SECRET に設定します

データベースの方言はまだ設定しないでください。ステップ 2 でのユーザーの選択に応じて決まります。

ステップ 2：データベースの選択

⛔ 停止 — 先に進む前に、必ずユーザーに質問してください。

tinyship-cf： デフォルトかつ推奨のデータベースは Cloudflare D1 です。すでに wrangler.jsonc でバインドされており、接続文字列は必要ありません。次を実行するだけです。

cd apps/tanstack-app
npx wrangler d1 migrations apply tinyship-db --local

その後、ステップ 3 に進みます。ユーザーが特に PostgreSQL（Hyperdrive）を希望する場合は、tinyship-cloudflare スキルの Hyperdrive パスに引き継いでください。

shipeasy： 次の選択肢を提示し、ユーザーの回答を待ってください。

選択肢	データベース	最適な用途
A	SQLite	最速で開始でき、セットアップ不要、ローカル開発向け
B	PostgreSQL	本番環境での利用、チームでの共同作業

ユーザーが SQLite を選択した場合：

.env に設定します：

DB_DIALECT="sqlite"

次に実行します：

mkdir -p data
pnpm install
pnpm db:push:sqlite
pnpm db:seed:sqlite

重要： mkdir -p data の手順は必須です。データベースファイルを作成する前に、SQLite 用の data/ ディレクトリが存在している必要があります。

ユーザーが PostgreSQL を選択した場合：

接続情報を尋ねる前に、ローカルの PostgreSQL 環境を自動検出します：

1. pg_isready を実行して、PostgreSQL がローカルで実行中かどうかを確認します。
2. PostgreSQL が実行中の場合：
   • ユーザーに「PostgreSQL はすでにこのマシンで実行されています」と伝えます。
   • tinyship データベースの自動作成を試みます：

     # データベースを作成するため、一般的なスーパーユーザーアカウントを試します
     createdb tinyship 2>/dev/null || \
       createdb -U postgres tinyship 2>/dev/null || \
       createdb -U $(whoami) tinyship 2>/dev/null
     

   • データベースの作成に成功した場合、接続文字列を検出します：

     # pg_isready の出力またはデフォルト値から PostgreSQL のユーザーとポートを特定します
     # 一般的なパターン：
     #   macOS Homebrew/Postgres.app：ユーザー = 現在の OS ユーザー、ポート = 5432
     #   Linux のシステムインストール：ユーザー = postgres、ポート = 5432
     

   • DATABASE_URL を自動的に組み立てます。一般的なローカル環境のパターン：
     • postgresql://localhost:5432/tinyship（macOS Postgres.app / Homebrew、ピア認証）
     • postgresql://postgres:postgres@localhost:5432/tinyship（パスワードを使用する Linux）
     • postgresql://<os-username>@localhost:5432/tinyship（ユーザー名を使用する macOS）
   • 検出した接続文字列をユーザーに提示し、使用する前に確認を求めます。
   • データベースの作成に失敗した場合はユーザーに伝え、手動入力を求めます。
3. PostgreSQL が実行されていない場合：
   • このマシンでは PostgreSQL が検出されなかったことをユーザーに伝えます。
   • 次の選択肢を提示します：
     • Docker：コンテナ化された PostgreSQL を起動します（Docker が実行中である必要があります）
     • 手動：ユーザーが独自の接続文字列を入力します

自動検出に成功 — .env に設定：

DB_DIALECT="pg"
DATABASE_URL="<the auto-detected or confirmed connection string>"

Docker での代替方法 — 実行：

docker run --name tinyship-db \
  -e POSTGRES_USER=tinyship \
  -e POSTGRES_PASSWORD=tinyship123 \
  -e POSTGRES_DB=tinyship \
  -p 5432:5432 \
  -d postgres:15

.env に設定：

DB_DIALECT="pg"
DATABASE_URL="postgresql://tinyship:tinyship123@localhost:5432/tinyship"

データベースの設定後（どの方法でも）、実行：

pnpm install
pnpm db:push
pnpm db:seed

シードデータで 2 人のテストユーザーを作成します

• 管理者：[email protected] / admin123（ロール：管理者）
• ユーザー：[email protected] / user123456（ロール：ユーザー）

ステップ 3：フレームワークを選択（shipeasy のみ）

⛔ 停止 — 続行する前に、必ずユーザーに確認してください。

次の選択肢を提示し、ユーザーの回答を待ちます：

選択肢	フレームワーク	おすすめの対象	開発コマンド
A	Next.js	React 開発者、Vercel へのデプロイ、最大規模のエコシステム	pnpm dev:next
B	Nuxt.js	Vue 開発者、設定より規約を重視する開発	pnpm dev:nuxt
C	TanStack Start	軽量な React、Cloudflare Workers のエッジデプロイ	pnpm dev:tanstack

注： Cloudflare Workers にデプロイする場合は、ハックなしで Workers 用に事前設定されている tinyship-cf テンプレートから始めることをおすすめします。

tinyship-cf： 選択をスキップします — 使用できるフレームワークは TanStack Start のみです。開発コマンドは pnpm dev です。

ユーザーの選択後（または tinyship-cf の場合）、アプリを起動して確認します：

1. 開発コマンドを実行します（例：pnpm dev:next / pnpm dev）
2. http://localhost:7001 を開きます — ホームページが読み込まれることを確認します
3. http://localhost:7001/api/health を確認します — レスポンスが返ることを確認します
4. [email protected] / admin123 でログインを試します

各確認手順の結果をユーザーに伝えます。

ステップ 4：料金モードを選択（任意）

⛔ 停止 — 続行する前に、必ずユーザーに確認してください。

TinyShip は 2 つの料金モードに対応しています。次の選択肢を提示します：

選択肢	モード	おすすめの対象
A	静的（デフォルト）	シンプルな設定、コード内でプランを定義、更新時にデプロイ
B	動的	管理 UI での管理、再デプロイなしでプランを更新

ユーザーが静的を選択した場合（またはスキップした場合）：

追加の設定は不要です。プランは config/payment.ts で定義され、料金ページに直接表示されます。これがデフォルトの動作です。

ユーザーが Dynamic を選択した場合：

.env（shipeasy）または apps/tanstack-app/.dev.vars（tinyship-cf）に設定します：

PRICING_MODE="dynamic"

Dynamic pricing ではプランをデータベースに保存し、コードを変更せずにプランを作成、編集、管理できる管理 UI を /admin/pricing に用意しています。機能は次のとおりです。

• 多言語のプラン名／説明（拡張可能な i18n タブ）
• Markdown に対応した機能リスト
• 取り消し線付き価格（元の価格を表示）
• ロケールに基づくプランのフィルタリング
• プロバイダーごとの決済 ID（Stripe Price ID、PayPal Plan ID など）
• 既存の静的プランをワンクリックでデータベースにインポート

注： pricing_plan テーブルのデータベースマイグレーションはすでに含まれています。 セットアップ後は、管理パネルの /admin/pricing からすべてのプランを管理できます。 tinyship-cf では、デプロイされた Worker 用に wrangler.jsonc の vars にも PRICING_MODE を設定する必要があります。

ユーザーには次のように伝えてください：「環境ファイルの PRICING_MODE を変更すれば、いつでもモードを切り替えられます。config/payment.ts の静的プランはフォールバックとして引き続き利用できます。」

ステップ 5：フレームワークの整理（任意、shipeasy のみ）

⛔ STOP — 続行する前に、必ずユーザーに確認してください。明示的な確認なしに削除してはいけません。

アプリが動作することを確認した後、ユーザーに次のように尋ねてください。

現在のプロジェクトには、3 つのフレームワーク（Next.js、Nuxt.js、TanStack Start）がすべて含まれています。 プロジェクトをシンプルにするため、使用していない 2 つを削除しますか？

• はい — 使用していないフレームワークを削除し、関連する設定をすべて整理します
• いいえ — 3 つすべてを残します（後からいつでも削除できます）

ユーザーが明示的に「はい」と答えた場合にのみ、整理を実行してください。

はいの場合は、references/framework-cleanup.md に記載された詳細な整理手順を読み、従ってください。

この整理では、次の作業を行います。

• 使用していない apps/ ディレクトリを削除する
• ワークスペース設定、ビルドスクリプト、Docker、CI を整理する
• Nuxt だけを残す場合は、libs/react-shared を削除する（React 専用のため）
• 残したアプリが引き続き正しくビルドできることを確認する

ステップ 6：次のステップ

セットアップが完了したら、ユーザーに次にできることを伝えてください。

1. ブランディングをカスタマイズする — アプリ名、ロゴ、テーマを変更します（tinyship-brand スキルを使用）
2. 認証を追加する — OAuth プロバイダーを設定します（tinyship-auth スキルを使用）
3. 決済を設定する — 決済プロバイダーを統合します（tinyship-payment スキルを使用）
4. AI を設定する — AI チャット／画像／動画機能をセットアップします（tinyship-ai スキルを使用）
5. デプロイする — Vercel、Docker、または Cloudflare にデプロイします（tinyship-deploy スキルを使用。 Cloudflare Workers の場合は、すべての設定をまとめて行う tinyship-cloudflare を使用します）

TinyShip リポジトリ内の参照ファイル

このスキルを実行する際は、コンテキストを把握するため、ユーザーの TinyShip プロジェクトから次のファイルを読み取ってください。

• env.example（shipeasy）／apps/tanstack-app/.dev.vars.example（tinyship-cf） — 環境変数
• docs/user-guide/get-started.md — 詳細なスタートガイド
• docs/user-guide/database.md — データベース設定の詳細
• docs/user-guide/payment/dynamic-pricing.md — 動的価格設定機能のガイド
• pnpm-workspace.yaml — ワークスペースの構成
• package.json — 利用可能なスクリプト