Blume 2 へのアップグレード

1 つのコマンドで Blume 1 のサイトを Blume 2 に移行し、設定の変更ごとにこのガイドを参照してください。アップグレード全体を Codex や Claude Code に任せることもできます。

Blume 2 で変わるのは設定だけで、コンテンツは変わりません。Markdown や MDX のページを編集する必要はありません（ただし、効果を持つようになったフィールドが 1 つあります。フロントマターを参照してください）。以前は名前付きの文字列やキー付きのブロックで指定していた設定は、blume/* サブパスからインポートして呼び出すアダプターになりました。対象は検索プロバイダー、デプロイ先、コンテンツソース、API リファレンス、アナリティクス、アシスタントのモデルバックエンドです。Ask AI はアシスタントに名称が変わったため、ai.ask は ai.assistant になります。機械可読な設定は ai から新しい agents キーに移動しました。また、components.ts のオーバーライドはビルド前にチェックされるようになりました。ゼロコンフィグのサイトや、これらの設定をどれも使っていないサイトでは、バージョンを上げるだけで済みます。

1 つのコマンドでアップグレードする

プロジェクト（blume.config.ts があるフォルダー）でアップグレードを実行します：

npx blume@latest upgrade

pnpm dlx blume@latest upgrade

yarn dlx blume@latest upgrade

bunx blume@latest upgrade

nubx blume@latest upgrade

aube dlx blume@latest upgrade

このコマンドは package.json 内の blume を 2 に上げ、プロジェクトで使っているパッケージマネージャーでインストールします。その後、設定と components.ts が Blume 2 に対応しているかをチェックします。まだ必要な変更はすべて、ファイル、行、置き換え内容とともに一覧表示されます。削除された blume build フラグをまだ渡している package.json のスクリプトもここに含まれます。変更が残っている間は、コマンドは 0 以外の終了コードで終了します。設定も blume の依存関係もないフォルダーで実行した場合は、エラーで停止します。blume ではなく npx blume@latest で実行してください。このコマンドは Blume 2 に含まれているため、まだ 1 を使っているプロジェクトにはありません。pnpm 12 では、pnpm dlx の後に --allow-build=esbuild を追加してください。pnpm 12 は、承認されていない esbuild のインストールスクリプトを実行しないためです。

変更をコーディングエージェントに任せる場合は、--codex または --claude を追加します：

npx blume@latest upgrade --codex

pnpm dlx blume@latest upgrade --codex

yarn dlx blume@latest upgrade --codex

bunx blume@latest upgrade --codex

nubx blume@latest upgrade --codex

aube dlx blume@latest upgrade --codex

エージェントは、検出結果とこのガイドを読み込んだ状態で対話モードで起動します。各変更を適用し、blume doctor と blume build の両方が成功するまで実行を繰り返します。すべての編集はエージェント自身の権限フローを通るため、1 つずつ確認できます。インストールせずに package.json のバージョンだけを上げるには、--no-install を渡します。

以下のセクションでは、変更点を 1 つずつ説明します。手動でアップグレードするときや、エージェントが行った変更を確認するときに参照してください。

検索

search には、provider 文字列と認証情報のブロックの代わりに、blume/search のアダプターを渡します。デフォルトのローカル検索は変更不要です。

export default defineConfig({
  search: {
    provider: "algolia",
    algolia: { appId: "APP_ID", indexName: "docs", searchApiKey: "SEARCH_KEY" },
  },
});

import { defineConfig } from "blume";
import { algolia } from "blume/search";

export default defineConfig({
  search: algolia({ appId: "APP_ID", indexName: "docs", apiKey: "SEARCH_KEY" }),
});

Orama Cloud、Typesense、Mixedbread も同じように、それぞれ oramaCloud()、typesense()、mixedbread() に置き換えます。キーを受け取るアダプターでは、検索専用キーの名前はすべて apiKey です。mixedbread() はクエリをドキュメントサーバー上で実行するため、キーではなく storeId を受け取ります。それ以外のオプションはストア検索の呼び出しにそのまま渡され、top_k のデフォルトは 8 です。管理者キーはこれまでどおり環境変数（ALGOLIA_ADMIN_API_KEY、ORAMA_PRIVATE_API_KEY、TYPESENSE_ADMIN_API_KEY、MIXEDBREAD_API_KEY）に設定します。
provider: "pagefind" は pagefind() に、provider: "none" は search: false になります。
popular リンクや indexing オプションを残すには、アダプターを次のようにラップします: search: { provider: algolia({ … }), popular: […] }。

デプロイ

deployment には、adapter と output フィールドの代わりに、blume/deploy のホストアダプターを渡します。site と base はアダプターのオプションに移動します。

export default defineConfig({
  deployment: {
    adapter: "vercel",
    output: "server",
    site: "https://docs.example.com",
  },
});

import { defineConfig } from "blume";
import { vercel } from "blume/deploy";

export default defineConfig({
  deployment: vercel({ site: "https://docs.example.com" }),
});

netlify()、cloudflare()、node() も同じように使います。ホストアダプターを指定すると、サーバー出力に切り替わります。静的ビルドのまま、そのホスト向けのプラットフォームファイルも出力したい場合は、output: "static" を渡します。
site または base だけを設定している場合は、変更不要です。deployment: { site, base } は今後も静的ビルドの書き方です。
redirects は :name セグメントと末尾の * をパターンとして解釈し、どのホストでも同じ方法でマッチさせるようになりました（パターンリダイレクトを参照）。Blume 1 はパターンをサポートしておらず、記述どおりに各ホストへ渡していたため、パターンを含む from や to があれば確認してください。
blume build の --adapter、--output、--base フラグは廃止されました。いずれかを渡すとビルドはエラーで停止し、代わりに使う deployment の設定が表示されます。アダプターは blume.config.ts で明示的に指定してください。サーバー出力をプラットフォームの環境から推測する動作はなくなりました。デプロイごとに異なる --base を渡していた CI のステップでは、代わりに設定内で環境変数から読み込むことができます。

各アダプターのオプションについては、デプロイを参照してください。

コンテンツソース

content.sources の各エントリーは、{ type } オブジェクトではなく blume/sources のアダプターで指定します。

export default defineConfig({
  content: {
    sources: [
      { type: "filesystem", root: "content" },
      {
        type: "github-releases",
        owner: "acme",
        repo: "sdk",
        prefix: "changelog",
      },
    ],
  },
});

import { defineConfig } from "blume";
import { filesystem, githubReleases } from "blume/sources";

export default defineConfig({
  content: {
    sources: [
      filesystem({ root: "content" }),
      githubReleases({ owner: "acme", repo: "sdk", prefix: "changelog" }),
    ],
  },
});

mdx-remote、sanity、notion、obsidian は、それぞれ mdxRemote()、sanity()、notion()、obsidian() になります。その他のフィールドは、そのまま呼び出しの引数に移します。{ type: "custom", source } は custom(source) になります。
content.root、content.include、content.exclude は、フォルダーが 1 つだけの場合の省略形として引き続き使えます。ただし、sources と一緒には使えなくなりました。併用している場合は、filesystem() エントリーに移してください。
githubReleases() のリリースページは、1 つの言語でのみ公開されるようになりました。そのため多言語サイトでも、他のロケールの URL（/de/changelog/…）にはコピーされません。外部サイトがそれらのコピーにリンクしている場合は、デフォルトロケールのページへのリダイレクトを追加してください。
Notion で入力したテキストは、入力したとおりに表示されるようになりました。notion() のページ内のコンポーネント、{、Markdown の文字は、MDX として解釈されず、入力どおりに表示されます。Notion のページにテキストとして入力したコンポーネントや Markdown がある場合は、ソースに mdx: true を設定してください。

API リファレンス

トップレベルの openapi、asyncapi、graphql ブロックは、blume/reference のアダプターを並べた 1 つの reference リストにまとめられます。enabled は削除してください。

export default defineConfig({
  openapi: { enabled: true, spec: "./openapi.yaml" },
  graphql: {
    enabled: true,
    spec: "./schema.graphql",
    endpoint: "https://api.example.com/graphql",
  },
});

import { defineConfig } from "blume";
import { graphql, openapi } from "blume/reference";

export default defineConfig({
  reference: [
    openapi({ spec: "./openapi.yaml" }),
    graphql({
      spec: "./schema.graphql",
      endpoint: "https://api.example.com/graphql",
    }),
  ],
});

asyncapi: { … } は、オプションはそのままで asyncapi({ … }) になります。
AsyncAPI 1.x または 2.x の仕様は、これまでどおり自動的に 3.0 に変換されます。ただし、コンバーターはオプションのピア依存関係になったため、プロジェクトに @asyncapi/converter をインストールしてください。インストールしていない場合、ビルドはインストールコマンドを表示して失敗します。3.x の仕様では何もする必要はありません。
renderer: "scalar" は、リスト内で独立した scalar({ spec, theme, … }) エントリーになります。ブロックの route と sources はそのまま引き継ぎます。
enabled: false のブロックは、リストに含めないだけで構いません。

アナリティクス

analytics オブジェクトは、blume/analytics のアダプターを並べたリストになります。

export default defineConfig({
  analytics: {
    posthog: { key: "phc_…" },
    vercel: true,
  },
});

import { defineConfig } from "blume";
import { posthog, vercel } from "blume/analytics";

export default defineConfig({
  analytics: [posthog({ key: "phc_…" }), vercel()],
});

cloudflare: { token } は cloudflare({ token }) になり、scripts[] の各エントリーは script({ … }) になります。

アシスタント

Ask AI はアシスタントという名前になり、設定もその名前に合わせて移動します: ai.ask は ai.assistant になります。provider には blume/ai のアダプターを渡します。モデルと、それに関連するフィールドはアダプター側で指定します。

export default defineConfig({
  ai: {
    ask: {
      enabled: true,
      provider: "openrouter",
      model: "anthropic/claude-sonnet-4-5",
      reasoning: "none",
    },
  },
});

import { defineConfig } from "blume";
import { openrouter } from "blume/ai";

export default defineConfig({
  ai: {
    assistant: {
      enabled: true,
      provider: openrouter({
        model: "anthropic/claude-sonnet-4-5",
        reasoning: "none",
      }),
    },
  },
});

1.x の provider 名は gateway()、openrouter()、llmgateway()、inkeep() のいずれかに対応し、openai-compatible は openai({ baseUrl, name, model, apiKeyEnv }) に対応します。その他のアダプターについてはアダプター一覧を参照してください。model、apiKeyEnv、baseUrl、headers、reasoning はアダプターに移動します。enabled、instructions、retrieval、suggestions、cors、endpoint は、そのまま ai.assistant に移動します。provider を指定しない場合は、これまでどおり AI Gateway が使われます。

この名前の変更は、Ask AI を指していたすべての名前に及びます：

i18n.ui のオーバーライド: ask グループは assistant になり、search.askAi と search.askAiHint はそれぞれ search.assistant と search.assistantHint になります。
blume/hooks の useAskAI は useAssistant になり、型も UseAssistant と UseAssistantOptions になります。
PageLayout、RootLayout、Header、および Search のオーバーライドの askEnabled プロパティは assistantEnabled になります。
blume:data モジュールでは、config.ask は config.assistant に、ui.ask は ui.assistant になります。blume の UIStrings 型もこれに合わせて変わります。
blume/ai のアダプター型は、接頭辞が Ask から Assistant に変わります（AskAdapter は AssistantAdapter に、AskGatewayOptions は AssistantGatewayOptions になります）。また、blume/schema の askReasoningLevels と AskReasoning は、それぞれ assistantReasoningLevels と AssistantReasoning になります。
window イベント blume:open-ask-ai は blume:open-assistant に、<body> の data-blume-ask 属性は data-blume-assistant になります。

生成される /api/ask ルートと、ask、ask_answer、ask_error のアナリティクスイベントは名前が変わらないため、呼び出し側やダッシュボードを変更する必要はありません。blume upgrade と blume doctor は、見つかった古い設定キーを、ai.ask か i18n.ui のキーかにかかわらず、置き換え先とともに表示します。

すでに Blume 2.0.0 にアップグレードしていますか？ 2.0.0 はまだ ai.ask を読み込んでいたため、通常どおり blume を更新し、同じ名前の変更を行ってください。

エージェントとその他の設定の移動

機械可読な設定は ai から新しい agents キーに移動します。また、3 つの小さなフィールドの形式が変わります。

export default defineConfig({
  ai: { mcp: { enabled: true }, skills: "./skills" },
  lastModified: true,
  markdown: {
    codeBlocks: { theme: { light: "github-light", dark: "github-dark" } },
  },
  theme: { layout: "sidebar" },
});

export default defineConfig({
  agents: { mcp: { enabled: true }, skills: "./skills" },
  lastModified: "git",
  markdown: {
    code: { theme: { light: "github-light", dark: "github-dark" } },
  },
});

ai.api、ai.catalog、ai.llmsTxt、ai.markdownComponents、ai.mcp、ai.skills、ai.webBotAuth、ai.webmcp は agents.* に移動します。seo.agentReadability と seo.contentSignals も同様です。ai に残るのは assistant（旧 ask）と openInChat だけです。
lastModified には単純な値を指定します。true は "git" になり、{ type: "git" } や { type: "frontmatter" } はその文字列だけを指定します。
markdown.codeBlocks は markdown.code に統合されます。
theme.layout は廃止されました。もともと参照されていなかったため、削除してください。

フロントマター

ページのフロントマターはそのまま使えます。動作が変わるフィールドが 1 つあります: search.boost です。Blume 1 では指定できましたが、検索では一度も使われておらず、指定してもページの順位は変わりませんでした。今後は、この値がページの検索での関連度に掛け合わされます（ランキングを参照）。このフィールドを設定しているページを確認してください。追加したまま忘れていた boost があると、そのページの順位が上がります。

コンポーネントのオーバーライド

Blume 2 では、components.ts のすべてのエントリーを、実行時にフォールバックするのではなくビルド前にチェックします。mdx と layout の各エントリーには、インポートしたコンポーネント、パス文字列、{ component, client, media } オブジェクトのいずれかを指定する必要があります。また、islands グループは廃止されました。client モードを指定した mdx エントリーがアイランドになります。

import { defineComponents } from "blume";
import Counter from "./islands/Counter.tsx";

export default defineComponents({
  islands: { Counter },
});

import { defineComponents } from "blume";
import Counter from "./islands/Counter.tsx";

export default defineComponents({
  mdx: { Counter: { component: Counter, client: "visible" } },
});

インライン関数、components.ts 内で宣言したコンポーネント、スプレッド構文、計算されたキーは、BLUME_COMPONENTS_INVALID エラーになり、該当するエントリーが表示されます。コンポーネントを別のファイルに移し、そこからインポートしてください。islands/ フォルダーの規約はこれまでどおり使えます。指定できる形式については、カスタマイズを参照してください。

イジェクトしたアプリ

Blume 1 でイジェクトしたアプリは Blume CLI では実行されなくなりますが、blume パッケージには引き続き依存しています。ページは Blume のコンポーネントをインポートしています。src/generated/ には、Blume 1 のジェネレーターが出力したサイトのスナップショットが入っています。さらに astro build は、検索インデックス、llms.txt、サイトマップを出力するために blume.config.ts を読み込み直します。この状態で blume だけを 2 に上げると、Blume 1 のスナップショットが、新しい形式を前提とする Blume 2 のコンポーネントと組み合わさってしまいます。そのため、以下の手順でイジェクトし直してください：

Copy the project out

astro.config.mjs、src/、.blume/、dist/、node_modules/ 以外のすべてを空のフォルダーにコピーします。コンテンツ、blume.config.ts、components.ts、islands/、public/、リファレンスが読み込む仕様ファイル、package.json が対象です。イジェクトしたアプリには手を加えないでください。

Upgrade the copy

コピー先で npx blume@latest upgrade を実行し、一覧表示された変更を適用して、blume.config.ts と components.ts を Blume 2 の形式にします。その後、npx blume build を実行し、イジェクトする前にサイトをビルドできることを確認します。

Eject a fresh copy

コピー先で npx blume eject --yes を実行し、追加されたパッケージをインストールしてから、npm run build でビルドします。

Carry your edits across

新しく生成された astro.config.mjs と src/ を、イジェクト済みのアプリと差分比較し、自分で加えた変更を新しいファイルに移します。

新しいコピーの準備ができるまでは、イジェクト済みのアプリは Blume 1（"blume": "^1"）のままにしておき、そこで blume upgrade を実行しないでください。バージョンを上げない限り、何も変わりません。

コマンドラインフラグ

Blume 1 では、コマンドが受け付けないフラグは無視されていましたが、今後はすべての blume コマンドがエラーにします。不要なフラグやスペルミスのあるフラグを渡しているスクリプトや CI のステップは失敗し、認識されなかったフラグと、そのコマンドで使えるフラグが表示されます。blume upgrade が検出するのは、削除された 3 つの blume build フラグ（--adapter、--output、--base）だけです。他の blume スクリプトも確認してください。

作業を確認する

blume upgrade が変更の必要な箇所はもうないと報告したら、サイトのチェックを実行します：

npx blume doctor
npx blume build

すべての変更点と、それぞれの変更理由は変更履歴に掲載しています。