blink-full-stack

前提条件

ビルドする前に、Blink CLI がインストールされ、認証済みであることを確認してください。

npm install -g @blinkdotnew/cli
blink login

blink がインストールされていない場合は、最初にインストールコマンドを実行してください。blink login を実行するとブラウザーが開き、ワークスペース API キーを作成できます。画面の指示に従うと、認証情報がローカルに保存されます。

概要

これは、ゼロから本番環境までフルスタック Blink アプリを構築するためのマスターガイドです。各セクションから、より詳しいスキルにアクセスできます。

ステップ 1 — プロジェクトのセットアップ

# Install SDK in your app directory
bun add @blinkdotnew/sdk

または、MCP ツールを使用します。

1. blink_project_create — プロジェクトを作成し、id を返します
2. blink_project_keys — publishableKey（blnk_pk_...）を返します — 作成後に呼び出してください

ステップ 2 — SDK の初期化

import { createClient } from '@blinkdotnew/sdk'

export const blink = createClient({
  projectId: process.env.NEXT_PUBLIC_BLINK_PROJECT_ID || 'your-project-id',
  publishableKey: process.env.NEXT_PUBLIC_BLINK_PUBLISHABLE_KEY || 'blnk_pk_xxx',
  auth: { mode: 'managed' },
})

フレームワークごとの環境変数プレフィックス：NEXT_PUBLIC_（Next.js）、VITE_（Vite）、EXPO_PUBLIC_（Expo）。

フォールバックが必要な理由：環境変数が未定義の場合、SDK はエラーを通知せずに失敗し、アプリがハングします。

ステップ 3 — 認証

blink.auth.login()  // managed mode — redirects to hosted auth
// OR headless mode for custom UI:
await blink.auth.signInWithEmail(email, password)

→ 詳細については、blink-auth スキルを参照してください

ステップ 4 — データベース

# Create tables via CLI
blink db query "CREATE TABLE todos (id TEXT PRIMARY KEY, title TEXT NOT NULL, user_id TEXT, is_completed INTEGER DEFAULT 0, created_at TEXT DEFAULT (datetime('now')))"

const todos = await blink.db.todos.list({
  where: { userId: user.id },
  orderBy: { createdAt: 'desc' },
})

→ 詳細については、blink-database スキルを参照してください

ステップ 5 — バックエンド（Pro+）

Webhook、シークレット、サーバーロジック用に、Hono サーバーを含む backend/index.ts を記述します。

blink backend deploy

→ 詳細については、blink-backend スキルを参照してください

ステップ 6 — デプロイ

npm run build
# Always pass project ID explicitly
blink deploy <project_id> ./dist --prod
# → site is live immediately at https://{project_slug}.blinkpowered.com
# The CLI prints the URL. Do NOT call blink_hosting_activate after this.

blink_hosting_activate は呼び出さないでください — 外部でビルドされたアプリの場合、Blink AI テンプレートでファイルが上書きされます。

→ 詳細については、blink-deploy スキルを参照してください

ステップ 7 — プロジェクトのコンテキストを保存

デプロイ後、このセッションの実際の値（実際のプロジェクト ID、実際の公開可能キー、実際のライブ URL、実際の SQL）を使って、プロジェクトのルートに AGENTS.md を記述します。{project_id} のようなプレースホルダーは使用しないでください。

# Blink Project

## Project
- **ID**: `actual-project-id-here`
- **Live URL**: `https://actual-project-id.blinkpowered.com`
- **Publishable Key**: `blnk_pk_actualKeyHere`

## Deploy
npm run build && blink deploy actual-project-id ./dist --prod

## Database
CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL, ...)

## Auth: headless (or managed)

また、CLAUDE.md も記述します。

# Claude Context
@AGENTS.md

→ これらのファイルを用意しておけば、このディレクトリを開いたエージェントは Blink のセットアップ（プロジェクト ID、キー、スキーマ、デプロイコマンド）をすぐに把握でき、再度プロンプトで尋ねる必要はありません。

ステップ 8 — カスタムドメイン

blink domains add myapp.com
# Follow DNS instructions from output
blink domains verify myapp.com

→ 詳細については、blink-domains スキルを参照してください

重要なルール

1. SDK コードではすべて camelCase を使用します — userId、createdAt（自動的に snake_case に変換されます）
2. SQLite の ブール値 は "0"／"1" 文字列です — Number(val) > 0 を使用してください
3. ID は文字列であり、数値ではありません — "todo_abc123" 形式です
4. ほとんどの SDK モジュールで 認証が必要です — DB／ストレージの呼び出し前に認証をセットアップしてください

スキル一覧

スキル	使用する場面
blink-auth	ログイン、サインアップ、ソーシャルプロバイダー、RBAC
blink-database	CRUD 操作、フィルタリング、生 SQL
blink-storage	ファイルのアップロード、ダウンロード、管理
blink-backend	Webhook、サーバーシークレット、カスタム API
blink-queue	バックグラウンドタスク、cron ジョブ
blink-deploy	本番環境へのビルドとデプロイ
blink-domains	カスタムドメイン、DNS、SSL
blink-ai	テキスト／画像／動画の生成、TTS、文字起こし、AI 呼び出し
blink-agents	マネージド AI エージェントのホスティング（Blink Claw）
blink-connectors	OAuth 連携（Slack、Google、Notion、38 以上のサービス）
blink-rag	ナレッジベース、ベクトル検索、引用付き AI Q&A
blink-realtime	WebSocket pub/sub、プレゼンス、メッセージ履歴
blink-notifications	メール、SMS、電話番号

サポート対象のフレームワーク

フロントエンド：React（Vite）、Next.js（静的エクスポート）、Vue、Svelte、Astro、Expo React Native、プレーンな HTML/CSS/JS

バックエンド：TypeScript／JavaScript のみ（CF Workers 上の Hono）