go-blueprintの使い方｜createの全フラグとGo雛形の生成手順、本番前に直す設定【v0.10.11】

go-blueprintは、Goのプロジェクト構成をコマンド一本で用意するCLIツールです。フレームワークとデータベースドライバを選ぶと、cmd/internalに分かれたディレクトリ、ビルド用のMakefile、テスト、必要ならDocker Composeの定義までまとめて書き出します。利用する版とコマンド仕様を明確にするため、この記事は2026年11月1日にv0.10.11をgo1.27.2で実行し、得られた出力と生成物、上流のソースだけを根拠に整理しています。後半では、生成されたコードをそのまま本番へ出すと困る箇所も扱います。

まとめ

• サブコマンドはcreate・version・completion・helpの4つだけです。init・new・build・runは存在しません。
• 導入はgo install github.com/melkeydev/go-blueprint@latestが基本で、npmとHomebrewでも入ります。どの経路でも、生成時にGo本体が必要です。
• createのフラグは--name・--framework・--driver・--advanced・--feature・--gitの6つ。フラグを全部渡しても端末は必要で、CIでは擬似端末を割り当てます。
• ビルドと実行は生成物のMakefileが担います。ターゲット数は選んだドライバと追加機能で6〜11本と変わり、SQLite以外のDBドライバを選ぶと、生成される統合テストを含むmake testにDockerが要ります。
• chiとechoの雛形は、どのオリジンにも認証情報付きのCORSを許可します。DB接続のsslmode無効化、ヘルスチェック失敗でプロセスが終了する作りと合わせ、本番前に書き換えが必要です。PostgreSQLのdocker-compose.ymlは、latestが18系になった今はマウント先を直さないと起動しません。
• 最新版はv0.10.11（2025年7月10日公開）で、2026年11月1日時点でそれ以降のリリースはありません。

go-blueprintのインストール方法と導入経路の選び方

go installでの導入とPATH設定

本体はGoで書かれており、公式リポジトリのREADMEが最初に挙げる導入方法はgo installです。

go install github.com/melkeydev/go-blueprint@latest

導入できたかはversionサブコマンドで確かめます。go install版の出力は次の通りでした。

$ go-blueprint version
Go Blueprint CLI version: v0.10.11

インストールが正常終了したのにcommand not foundになる場合は、まずバイナリの配置先とPATHを確認します。go installはバイナリを$GOBIN、未設定なら$GOPATH/bin（既定は$HOME/go/bin）へ置くだけで、シェルのPATHには追加しません。go env GOBINとgo env GOPATHで場所を確認し、シェルの起動ファイルに次を追記します（GOBINが空ならGOPATHの先頭エントリ配下のbinを足します）。

gobin=$(go env GOBIN)
[ -z "$gobin" ] && gobin="$(go env GOPATH | cut -d: -f1)/bin"
export PATH="$PATH:$gobin"

npm・Homebrewでの導入とGo本体の要否

READMEにはnpmとHomebrewの手順も載っています。npm版は@melkeydev/go-blueprint（0.10.11・2025年7月19日公開）で、本体のJavaScriptはprocess.platformとprocess.archから対応するビルド済みバイナリのパッケージを選んで実行するだけの薄いラッパーです。対応はmacOS・Linux・Windowsのx64とarm64の6種類です。

npm install -g @melkeydev/go-blueprint
brew install go-blueprint

注意したいのは、npmで入れてもGo本体は要る点です。createは内部でgo mod initやgo mod tidyを呼ぶため、PATHにgoが無い環境でnpm版を実行すると次のエラーで止まり、プロジェクト名の空ディレクトリだけが残りました。

Problem creating files for project.
Error: exec: "go": executable file not found in $PATH

Homebrewはformulaの定義がdepends_on "go"なので、Goごと入ります。Goを入れていないmacOSで試すだけならHomebrew、Goの版を自分で管理しているならgo install、Node.jsのツールと同じ手順で配りたいチームならnpm、という選び方になります。なおversionの表示はnpm版が0.10.11と先頭のvが付かず、go install版のv0.10.11と形が違います。版の文字列でスクリプトを分岐させているなら両方を受けてください。

大文字のMelkeydevを指定したときのインストール失敗

GitHubの表示名はMelkeydev/go-blueprintですが、go.modの1行目はmodule github.com/melkeydev/go-blueprintと全て小文字です。Goのモジュールパスは大文字小文字を区別するので、表示名どおり大文字で指定するとモジュールパスの検証で弾かれます。

$ go install github.com/Melkeydev/go-blueprint@latest
go: github.com/Melkeydev/go-blueprint@latest: version constraints conflict:
	github.com/Melkeydev/[email protected]: parsing go.mod:
	module declares its path as: github.com/melkeydev/go-blueprint
	        but was required as: github.com/Melkeydev/go-blueprint

エラー文が「version constraints conflict」で始まるので版指定の問題に見えますが、直すのはURLの大文字です。

v0.10.11のコマンド体系

createとversionを中心とした4サブコマンド

go-blueprint --helpが列挙するサブコマンドは4つです。

実作業で使うのは事実上createだけです。生成後のビルドやテストを担うサブコマンドは無く、その役割は生成物のMakefileへ渡されています。ルートコマンドのフラグは-h, --helpと-t, --toggleの2つです。

createで指定できる6フラグと許可値

go-blueprint create --helpの出力から、生成設定用の6フラグをまとめた一覧です。このほかに、ヘルプ表示用の-h, --helpがあります。許可値はリポジトリのcmd/flags/配下の定義と一致します。

許可値以外を渡すとその場でエラーになり、有効な値の一覧が返ります。--featureだけは短縮形が無く、複数指定するときはフラグを繰り返します。そして--featureは--advancedと併用しないと読まれません。上流のcmd/create.goでは--featureの値を取り出す処理が--advancedが真のときだけ走るブロックにあり、単独で渡すとエラーも警告も出ないまま無視されます。

英語の解説記事には--frontend reactという指定を載せたものがありますが、v0.10.11ではError: unknown flag: --frontendで止まります。Reactのフロントエンドは--advanced --feature reactで付けます。フラグの組み合わせを画面で選んでコマンド文字列を作るなら、公式のWeb UI（Blueprint UI）が使えます。

Goプロジェクト作成の手順と端末要件

プロンプト消去と端末要件の切り分け

go-blueprint createをフラグ無しで実行すると、フレームワークやドライバを矢印キーで選ぶ対話画面が立ち上がります。全項目をフラグで埋めれば選択画面は出ません。次はEchoとPostgreSQLの組み合わせで、Gitの初期化はしない指定です。

go-blueprint create --name my-api --framework echo --driver postgres --git skip

ただし「プロンプトが出ない」と「端末が要らない」は別の話です。v0.10.11のcmd/create.goは、フラグが揃っているかに関係なく生成中のスピナーをBubble Teaで起動し、このスピナーが/dev/ttyを直接開きます。端末の無い環境では上のコマンドでも失敗します。

$ go-blueprint create --name my-api --framework echo --driver postgres --git skip < /dev/null
Error: open /dev/tty: device not configured

失敗後に空ディレクトリだけが残った場合は、そのまま再実行できます。ファイルが残っている場合は内容を確認し、別のプロジェクト名を使うか、不要な生成物を整理してから再実行します。CIジョブやコンテナで生成するなら擬似端末を割り当ててください。docker runなら-t、シェルスクリプトからならscriptで包みます。次の例はmacOS用です。Linuxのutil-linux版ではscript -q -e -c 'go-blueprint create --name my-api --framework echo --driver postgres --git skip' /dev/nullの形を使うと、子コマンドの終了コードもCIへ返せます。

script -q /dev/null go-blueprint create --name my-api --framework echo --driver postgres --git skip

生成されるディレクトリ構成とドライバによる差分

--framework standard-library --driver noneで生成した最小構成のファイル一覧です。

minimal-api/
├── .air.toml
├── .env
├── .gitignore
├── Makefile
├── README.md
├── cmd/
│   └── api/
│       └── main.go
├── go.mod
├── go.sum
└── internal/
    └── server/
        ├── routes.go
        ├── routes_test.go
        └── server.go

エントリポイントはcmd/api/main.goの1本で、HTTPサーバの組み立てとルーティングはinternal/server/に分かれます。テストの雛形（routes_test.go）とホットリロード用の.air.tomlが最初から入っている点が、手書きの雛形との差です。ドライバ無しでも.envは作られますが、中身はPORT=8080とAPP_ENV=localの2行だけです。

ドライバを付けると差分が出ます。--driver postgresを指定したmy-apiでは、上の構成に次の3ファイルが増えました。

• internal/database/database.go：接続と疎通確認の実装
• internal/database/database_test.go：testcontainers-goで実DBを立てる統合テスト
• docker-compose.yml：postgres:latestイメージの定義（マウント先がPostgreSQL 17以前向けで、18系では書き換えが必要。後述）

依存の版は生成した時点の最新が入ります。2026年11月1日に生成したEcho＋PostgreSQLのgo.modはgithub.com/labstack/echo/v4 v4.16.3、github.com/jackc/pgx/v5 v5.12.0、github.com/joho/godotenv v1.5.1、github.com/testcontainers/testcontainers-go v0.44.0でした。go-blueprintのEchoテンプレートはv4系のままで、Echoはすでにv5が出ています。v5へ移るかどうかはEchoとは？Go製Webフレームワークの使い方・Gin比較・v5移行を実測で解説【v5.4.0】を見てから決めてください。ORMは含まれず、構造体へのマッピングが欲しければGORMのGenerics APIとは？従来APIとの違いと基本の実装パターンのような層を自分で足します。

go.modのgoディレクティブは、最初に実行されるgo mod initのGoバージョンで初期化されます。ただし、続く依存解決で必要なGoバージョンが引き上げられる場合があります。go1.27.2の環境ではgo 1.27.2でした。チームで版を揃える場合は、依存モジュールが要求する最低Goバージョンを確認したうえでgo.modと開発・CI環境を揃えます。各版の差分はGo 1.27の新機能・変更点まとめ｜Goの最新バージョンは1.27、確認・更新方法と移行の注意点で確認できます。

生成後のビルド・実行・テストを担うMakefile

Makefileのターゲットと選択による増減

ターゲットの本数は固定ではなく、ドライバと追加機能で変わります。下表は--driver postgresを指定したときの9ターゲットです。

追加機能なしでドライバをnoneにするとdocker-run・docker-down・itestが消えて6ターゲットです。--driver noneでも--feature dockerを付ければdocker系の2つは残り、8ターゲットになります。tailwindを足すとtempl-installとtailwind-installが加わり、buildがこの2つに依存する形へ書き換わります。

最小構成でmake buildを実行すると10,386,672バイト（約10.4MB）のmainが出力され、make testでは雛形のTestHandlerがPASSしました。一方、SQLite以外のDBドライバを選んだ構成ではmake testが./...を対象にするため、統合テストまで走ります。Dockerを起動していないマシンでは次のようにinternal/databaseがFAILします。

could not start postgres container: run postgres: generic container: get provider: rootless Docker not found, failed to create Docker provider
FAIL	my-api/internal/database

単体テストだけ回したい場面ではgo test ./internal/server/...のように対象を絞るか、Makefileのtestを書き換えます。watchは開発中の常駐監視向けです。airが導入済みなら確認なしで起動するため、CIの通常のビルド・テストジョブでは終了するbuildやtestを使います。

.envのBLUEPRINT_DB_接頭辞とdocker-composeの連動

ドライバを指定すると.envに接続情報が書き出されます。PostgreSQLの場合は次の内容です。

PORT=8080
APP_ENV=local
BLUEPRINT_DB_HOST=localhost
BLUEPRINT_DB_PORT=5432
BLUEPRINT_DB_DATABASE=blueprint
BLUEPRINT_DB_USERNAME=melkey
BLUEPRINT_DB_PASSWORD=password1234
BLUEPRINT_DB_SCHEMA=public

環境変数名はプロジェクト名ではなくBLUEPRINT_接頭辞で固定されます。internal/database/database.goがこの名前を直接読むので、名前を変えるなら両方の修正が必要です。この.envはdocker-compose.ymlからも読まれ、make docker-runで立ち上がるコンテナの初期ユーザーとデータベース名になります。Compose側の記法はdocker-composeとは？複数コンテナをymlで定義し一括管理する仕組みを解説で整理しています。

生成されたdocker-compose.ymlはそのままでは起動しない点に注意してください。イメージがpostgres:latest、ボリュームのマウント先が/var/lib/postgresql/dataという組み合わせですが、2026年11月1日時点のlatestは18系（18.6）です。18系の公式イメージの起動スクリプトは、/var/lib/postgresql/dataにマウントがあると旧形式のデータ置き場とみなし、「Error: in 18+, these Docker images are configured to store database data in a format which is compatible with pg_ctlcluster」を出して終了します。新規に使うなら、マウント先を/var/lib/postgresqlへ変えるか、イメージをpostgres:17のように版で固定します。

advancedモードで追加できる6機能と生成物の差分

featureフラグによる非対話での機能指定

--advancedを付けると追加機能の選択に進みます。選択画面を出さずに回すなら--featureで明示します。前述のとおり--featureは--advancedとセットで渡します。

# macOS用。Linuxでは上記のscript -q -e -c形式でコマンド全体を渡す
script -q /dev/null go-blueprint create --name adv-api --framework chi --driver sqlite --advanced \
  --feature docker --feature githubaction --feature tailwind --feature htmx --git skip

tailwind・htmx・reactの組み合わせ規則

この3つは独立に選べるように見えて、上流のcmd/program/program.goで組み合わせが決め打ちされています。

tailwindだけを指定した実行では、cmd/web/hello.templやcmd/web/assets/js/htmx.min.jsまで生成されました。TailwindをGoのサーバ描画と組み合わせる前提の作りなので、「CSSだけ欲しい」という使い方はできません。htmx側の書き方はhtmxの使い方：hx-属性の実装手順からFastAPI連携まで解説【2026年版】が参考になります。

reactを選ぶと、go-blueprintは生成の途中でnpm create vite@latest frontend -- --template react-tsを実行します。事前にnpm --versionで存在を確かめるため、Node.jsが無い環境ではこの機能は使えません。2026年11月1日の実行ではcreate-vite v9.3.3が呼ばれ、package.jsonはreact ^19.3.1、vite ^8.3.5でした。@latestを引くので、生成した日によってフロントエンドの版は変わります。tailwindを併せて指定するとtailwindcss@^4と@tailwindcss/viteがfrontend側に入り、Go側のMakefileは追加機能なしと同じ6ターゲットのままでした。

websocketとgithubactionが置くファイル

--feature websocketは新しいファイルを作らず、internal/server/routes.goに/websocketのハンドラを足します。中身はgithub.com/coder/websocket（生成時点でv1.8.15）で接続を受け、2秒ごとにサーバのタイムスタンプを送り続ける見本です。認証やメッセージの受信処理は含まれません。

--feature githubactionは.github/workflows/go-test.yml・.github/workflows/release.yml・.goreleaser.ymlの3つを置きます。.goreleaser.ymlはdocker機能ではなくこちらの由来です。ワークフローを置くだけで実行時間の課金設計までは面倒を見ないので、無料枠と単価はGitHub Actionsの料金｜2026年10月のドル建て利用枠・分単価とコスト削減の判断基準で先に確かめておくと、生成直後にワークフローを絞る判断がしやすくなります。

tailwind-install・templ-installのOS依存とCI設定

Reactを使わずtailwindを有効にすると、Makefileにtailwind-installとtempl-installの2ターゲットが加わります（htmxだけならtempl-installのみ）。CIへ載せる前に確かめたいのは、生成した環境と実行する環境の違いです。

tailwind-installのダウンロードURLは生成時のOSで決まり、Linuxで生成すればtailwindcss-linux-x64、macOSで生成すればtailwindcss-macos-x64が書き込まれます。Macで作ったプロジェクトをそのままコミットすると、LinuxのランナーはmacOS用バイナリを取得してmake buildに失敗します。arm64のランナーでもx64版を取りに行く点は同じです。ランナーに合うTailwindのバイナリを取得する行へ書き換えておきます。

templ-installはtemplが未導入だとread -pで導入の可否を尋ねますが、回答がnかN以外ならインストールへ進む作りです。標準入力が空のCIでは回答が空になって導入まで進むので、止まりはしません。ただし毎回@latestを取りに行くため、版を固定したいならCIの手順でtemplを先に入れておくほうが確実です。

生成コードを本番に出す前に直す箇所

フレームワーク別のCORS既定値

生成されるroutes.goにはCORSの設定が最初から入っていますが、既定値はフレームワークごとにばらばらです。v0.10.11のテンプレートを7種類すべて確認した結果が次の表です。

危ないのはchiとechoです。生成したサーバへOrigin: https://evil.exampleを付けてリクエストすると、どちらもAccess-Control-Allow-Origin: https://evil.exampleとAccess-Control-Allow-Credentials: trueを返しました。Cookie認証を追加すると、CookieのSameSite属性やブラウザの制限が送信を許す条件では、外部サイトが認証情報を含むリクエストを送り、そのレスポンスを読める危険があります。Cookie認証を載せる前に、許可オリジンを自社のフロントエンドのURLへ絞ってください。ginはViteの開発サーバのポートだけが許可されているので、本番のURLを足さないとブラウザから呼べません。仕組みと設定の考え方はCORSとは？仕組み・プリフライト・サーバー設定例・エラー解決を実装目線で解説で詳しく扱っています。

DB接続とヘルスチェックの既定動作

PostgreSQLの接続文字列はsslmode=disableで組み立てられます。ローカルのdocker-composeでは問題になりませんが、マネージドDBへ接続する場合はサービスの接続仕様に従い、可能ならverify-fullと適切なCA証明書を設定します。requireは暗号化を要求しますが、接続先ホスト名の検証までは行いません。

もう一つは/healthの作りです。database.goのHealth()はPingに失敗するとlog.Fatalfを呼びます。DBを止めた状態で/healthへアクセスしたところ、db down: failed to connectを出力してサーバのプロセスごと終了しました。ロードバランサやKubernetesのヘルスチェックをこのエンドポイントに向けると、DBの一時的な瞬断でアプリが落ち、再起動を繰り返す原因になります。log.Fatalfを外し、ステータスを返すだけの実装へ直してから使ってください。

マイグレーションの仕組みも生成されません。スキーマはgolang-migrateなどを別途組み込んで管理します。.envのユーザー名とパスワードは作者由来の既定値が入っているので、リポジトリへ上げる前に差し替えます。

go-blueprintを採用しないほうがよい場面

まず、開発の止まり具合を織り込んでください。最後のリリースはv0.10.11（2025年7月10日）で、mainへの最終コミットも2025年7月19日です。2026年11月1日時点で未解決のIssueは25件、未マージのオープンPRは15件です。生成物は普通のGoプロジェクトなので一度作れば以後はgo-blueprintに依存しませんが、更新が再開される時期は確認できないため、上で挙げたCORSやMakefileの設定は上流の修正を待たず、自分で直す前提で採用を判断します。

社内標準のディレクトリ規約がある組織にも向きません。構成はcmd/apiとinternal/serverに固定で、出力先を変えるフラグも、独自テンプレートを読み込ませるフラグもありません。規約に寄せるには生成後に手で移すことになり、それなら自社のテンプレートリポジトリをcloneするほうが早く済みます。

CLIツールそのものを作りたい人の道具でもありません。生成されるのはHTTPサーバのプロジェクトで、サブコマンドや引数解析の雛形は出てきません。CLIを自作するなら、go-blueprint自身も使っているCobraを直接使うのが素直です。

逆に、Goを触り始めた段階でフレームワークとドライバの組み合わせを短時間で動く形にしたい、検証用のAPIサーバを何本も立てたい、といった用途では有効です。フレームワークは7つの選択肢、DBは6種類と接続なしを選べます。依存は生成時点の最新版が入るので、生成後に一度make buildとmake testを通してから使い始めてください。業務のAPI基盤として設計から任せたい場合は、API開発・システム連携の支援も相談先の一つです。

よくある質問

go-blueprintでCLIツールそのものを自作できますか？

できません。生成されるのはHTTPサーバのプロジェクトで、サブコマンドやフラグ解析の雛形は含まれません。CLIを自作する場合はCobraを直接導入してください。

go-blueprint newやgo-blueprint initは使えますか？

使えません。v0.10.11のサブコマンドはcreate・version・completion・helpの4つだけで、new・init・build・run・testを実行するとunknown commandになります。プロジェクト生成はcreate、ビルドと実行は生成物のMakefileという分担です。

go installしたgo-blueprintコマンドが見つからないのはなぜですか？

まずgo installの成功を確認し、成功していれば配置先とPATHを調べます。go installはバイナリを$GOBIN、未設定なら$GOPATH/binへ置きます。go env GOBINが設定されていればそのディレクトリを、空ならgo env GOPATHの先頭エントリ配下のbinをPATHに追加してください。モジュールパスを大文字のMelkeydevで指定していた場合はインストール自体が失敗しているので、小文字で入れ直します。

生成したプロジェクトのGoバージョンはどこで決まりますか？

go mod initを実行したGoのバージョンが初期値になりますが、その後の依存解決でgo.modのgoディレクティブが引き上げられる場合があります。go1.27.2の環境ではgo 1.27.2でした。CIと開発機で版を揃える場合は、依存関係の最低要求バージョンを確認し、go.modだけでなくCIと開発機で使うGoも合わせて設定してください。

npmで入れればGoをインストールしなくても使えますか？

使えません。npm版はビルド済みのgo-blueprint本体を配るだけで、createは内部でgoコマンドを呼びます。Goが無いとexec: "go": executable file not found in $PATHで止まります。Goを別に入れたくないmacOSの環境なら、Goを依存として一緒に入れるHomebrewが手軽です。

関連記事

• Go 1.27の新機能・変更点まとめ｜Goの最新バージョンは1.27、確認・更新方法と移行の注意点
• Echoとは？Go製Webフレームワークの使い方・Gin比較・v5移行を実測で解説【v5.4.0】
• CORSとは？仕組み・プリフライト・サーバー設定例・エラー解決を実装目線で解説
• docker-composeとは？複数コンテナをymlで定義し一括管理する仕組みを解説
• htmxの使い方：hx-属性の実装手順からFastAPI連携まで解説【2026年版】