Web3 SDK公式チュートリアル10本を実行、そのまま動いたのは4本

Web3 開発の SDK やツールの公式チュートリアル（Getting Started / Quickstart）は、書かれたとおりに実行すれば動くのでしょうか。主要な 10 本を 2026年9月24日にまっさらな環境で実行したところ、最後までそのまま動いたのは 4 本でした。止まった 6 本のうち 5 本は 1〜3 手の修正で動きました。原因で最も多かったのは、ドキュメントの誤りではなく、「ページが書かれた後にツールの側が変わった」ことでした。

公式チュートリアルが止まる一番の理由は、「最新版を入れる」手順と「書かれた当時の説明」のずれでした。

TypeScript 7 の登場、インストーラーの仕様変更、テンプレートの変更。どれもこの数か月の変化です。本記事では、止まった箇所のエラー文をそのまま載せ、何を直せば動いたかを SDK ごとに示します。

1. 結果の一覧：10 本中 4 本がそのまま動いた

web3.py は、1 回目は依存パッケージの解決が終わらず中断しましたが、2 回目は普通に入りました。同じ時間に PyPI への接続のタイムアウトが出ていたため、回線の一時的な問題と見て「そのまま動いた」に数えています。

2. 止まった原因の内訳

チュートリアルの多くは、「最新版を入れる」コマンドで始まります（npm add typescript、npm create wagmi@latest、インストーラーの curl … | bash など）。入る版は日々変わるのに、ページの説明は書かれた時点のままです。この「ずれ」が、今回止まった 6 本のうち 3 本の原因でした。

3. Aptos：TypeScript 7 で ts-node が起動しない

Aptos の TypeScript SDK のクイックスタートは、最初に npm add -D typescript @types/node ts-node でプロジェクトを作ります。2026年7月に TypeScript 7 が出たため、この手順では TypeScript 7.0.2 が入ります。その直後の「正しく作れたか確かめる」手順で、もう止まりました。

$ npx ts-node src/quickstart.ts
/root/aptos-qs/node_modules/ts-node/dist/configuration.js:91
    const { fileExists = ts.sys.fileExists, readFile = ts.sys.readFile, ...
                                ^

TypeError: Cannot read properties of undefined (reading 'fileExists')
    at readConfig (/root/aptos-qs/node_modules/ts-node/dist/configuration.js:91:33)

原因：TypeScript 7 は Go によるネイティブ移植版で、7.0 はこれまでの JavaScript の API を同梱していません。ts-node 10.9.2 はその API（ts.sys など）に頼っているため起動できません。ts-node の側では同じ報告の issue（#2174）が未解決のままです。

直し方（1 手目）：TypeScript 6 に戻します。

npm add -D typescript@6

これで確認用のコードは動きます。ところが本体のコードに差し替えると、次のエラーで止まりました。

TSError: ⨯ Unable to compile TypeScript:
src/quickstart.ts(5,10): error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. Adjust the 'type' field in the nearest 'package.json' to make this file an ECMAScript module, or adjust your 'verbatimModuleSyntax', 'module', and 'moduleResolution' settings in TypeScript.

原因：今の npm init は package.json に "type": "commonjs" を書き、今の tsc --init は tsconfig.json に "verbatimModuleSyntax": true を書きます。この組み合わせでは import 文が書けません。

直し方（2 手目）：tsconfig.json の "verbatimModuleSyntax" を false にします。これで devnet での送金まで動きました。

別の直し方：TypeScript 7 のままでも、npm pkg set type=module をしたうえで、ts-node ではなく node src/quickstart.ts で実行すれば動きます。Node 24 は TypeScript をそのまま実行できるためです。

4. Foundry：「ターミナルを開き直せば使える」が成り立たない

Foundry のインストール手順は、「インストーラーを実行 → ターミナルを開き直す（または source ~/.bashrc）→ foundryup」です。インストーラーの出力は次のとおりでした。

$ curl -L https://getfoundry.sh/install | bash
foundryup-init: foundryup was installed successfully!
foundryup-init:
foundryup-init: To get started, add foundryup to your PATH:
foundryup-init:
foundryup-init:   export PATH="$PATH:/root/.foundry/bin"
foundryup-init:
foundryup-init: Then run 'foundryup' to install Foundry.

ページのとおりにターミナルを開き直すと、次のように止まります。

$ foundryup
bash: foundryup: command not found

原因：以前のインストーラーは ~/.bashrc などに PATH を書き足していましたが、2026年8月末に新しいインストーラー（foundryup-init）に切り替わり、今は PATH を書き足さず、表示するだけになりました。ページの「開き直せば使える」は、以前の動きのままの説明です。

直し方（1 手）：インストーラーが表示するとおり PATH を通します。残したい場合は ~/.bashrc などにも書きます。

export PATH="$PATH:$HOME/.foundry/bin"

その後は foundryup、forge init、forge build、forge test、forge script まで、すべてそのまま通りました。Linux の arm64 向けの配布物もあり、問題はありませんでした。

5. wagmi：依存が入らず「vite: not found」

wagmi のページは、npm create wagmi@latest の後に「プロジェクトを作り、必要な依存パッケージを入れる」と書いています。しかし実際の CLI は依存を入れず、最後に次の案内を出して終わりました。

Done. Now run:
  cd wagmi-project
  npm install
  npm run dev

ページを信じてそのまま起動すると、次のエラーになります。

$ npm run dev
> vite
sh: 1: vite: not found

直し方（1 手）：npm install を実行します。その後、開発サーバーは起動し、本番用のビルドも通りました。テンプレートの依存はすべて「最新版」指定のため、この日は TypeScript 7.0.2 と Vite 8.3.0 が入りましたが、ビルドは通りました。

6. ethers v6：Node に貼ると 3 か所で止まる

ethers v6 の Getting Started には、コードの実行方法が書かれていません。ページのコード片を順につなげて Node で実行すると、3 か所で止まりました。

1. ReferenceError: window is not defined：最初の接続例が、ブラウザの MetaMask があるかを window.ethereum で確かめる書き方です。Node には window がないため、分岐を外して ethers.getDefaultProvider() だけにします。
2. ReferenceError: balance is not defined：コード片が balance = await … のように宣言なしで代入しています。ブラウザのコンソールや対話モードで打つ前提の書き方で、ファイルとして実行すると止まります。let を付けます。
3. ReferenceError: formatEther is not defined：ページは「すべて import 済みと仮定する」と書いていますが、直前の import 例には formatEther などが含まれていません。formatEther、formatUnits、Contract を import に足します。

3 か所を直すと、ページの例と同じ値が表示されました。ただし、ethers.getDefaultProvider() が使う既定の接続先（無料の共用キー）は不安定で、同じコードでも実行ごとに quorum not met や request timeout で失敗しました。同じ時間帯に、new ethers.JsonRpcProvider("…") で鍵の要らない公開 RPC を指定すると、3 回とも成功しました。

7. Solana Kit と Anchor：Linux の arm64 では始めにくい

Solana 系の 2 本は、Apple Silicon の Mac の Docker（Linux の arm64）で試したことで、壁が重なりました。

Solana Kit：テスト用 SOL の配布で止まる

鍵の作成までは動きました。ページの「Full example」は最初に devnet でテスト用の SOL を受け取りますが、ここで止まります。

SolanaError: JSON-RPC error: Internal JSON-RPC error (Internal error)
  context: { __code: -32603, __serverMessage: 'Internal error' }

同じ RPC に直接問い合わせると、理由が分かりました。

HTTP/2 429
retry-after: 86400
x-ratelimit-airdrop-limit: 1

{"jsonrpc":"2.0","error":{"code": 429,"message":"You've either reached your airdrop limit today or the airdrop faucet has run dry. ..."}}

実測では、配布の上限は 1 日 1 回で、その 1 回目が意味の分かりにくい Internal error で消費されていました。以後は 24 時間、429 が返ります。ページは Web の配布サイト（faucet.solana.com）も案内していますが、ブラウザでの操作が要るため今回は試していません。手元でテスト用のチェーンを立てる方法も試しましたが、次の Anchor と同じ理由で動きませんでした。

Anchor：arm64 向けの配布物がなく、それでも「Installation complete」

Anchor の Quick Installation を Linux の arm64 で実行すると、Solana の CLI のダウンロードが 404 で失敗し、Anchor の出来合いの版も見つかりません。それでもインストーラーは最後に次のように表示し、正常終了します。

Solana CLI: Not installed
Anchor CLI: Not installed
...
Installation complete. Please restart your terminal to apply all changes.

その後の anchor init は Error: Anchor version not set. で止まります。

直し方（1 手）：コンテナを amd64 のエミュレーション（--platform linux/amd64）で動かすと、インストールから anchor build、anchor test まで通りました。

なお、Solana のバリデーター（Agave）は、3.1 系以降、io_uring というカーネル機能が使えない環境では起動時に止まります。amd64 のエミュレーションでは io_uring が使えないため、手元でテスト用のバリデーターを動かす方法も通りませんでした。Anchor 1.x の既定のテストは LiteSVM を使う Rust のテストなので、バリデーターが無くても anchor test 自体は通ります。

ここでの話は Linux の arm64（Docker など）の場合です。macOS（Apple Silicon）向けの配布物は用意されています。

8. そのまま動いた 4 本の小さな注意点

• viem：終了コード 0 で終わりますが、画面には何も出ません。ページのコードはブロック番号を変数に入れるだけで表示しないためです。console.log(blockNumber) を足すと確認できます。
• Hardhat 3：npx hardhat --init は対話式で、CI やスクリプトからは Error HHE11: You are trying to initialize a project but you are not in an interactive shell. で止まります。ページにある --template 付きのコマンドを使えば質問なしで作れます。Linux の arm64 ではコンパイラ（solc）が WASM 版になりますが、テストは通りました。
• web3.py：pip install "web3[tester]" は一部の依存を手元でコンパイルします。コンパイラの入っていない軽量イメージでは、別の問題が出る可能性があります。
• Sui：送金まで動きましたが、送金の例の最後で残高の変化が Balance changes: undefined と表示されました（送金自体は成功）。

9. この結果の読み方

• 2026年9月24日の 1 回の結果です。「最新版」を入れる手順は、数日後には別の版が入り、結果が変わりえます。ドキュメントが直れば、ここで挙げた問題は解消します。
• 環境は Linux の arm64（Apple Silicon の Mac 上の Docker）です。x86_64 の Linux、macOS、Windows では結果が違いえます。
• 「ターミナルを開き直す」「Enter を押す」は再現した操作です。シェルの設定ファイルの読まれ方は、端末アプリや OS によって変わります。
• 外部サービスの状態はその日、その回線次第です。テスト用 SOL の配布の制限は送信元ごとなので、別の回線なら通った可能性があります。

10. よくある質問

「foundryup: command not found」と出たときは？

今のインストーラーは PATH を設定ファイルに書き足さないため、ターミナルを開き直しても foundryup は見つかりません。今回は export PATH="$PATH:$HOME/.foundry/bin" を実行したあと、foundryup から forge test まで通りました。

ts-node で「Cannot read properties of undefined (reading 'fileExists')」と出たときは？

今回は TypeScript 7 が入ったことが原因でした。npm add -D typescript@6 で TypeScript 6 に戻すか、ts-node を使わずに Node で直接実行する（npm pkg set type=module の後に node ファイル名.ts）と動きました。

「error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file」と出たときは？

package.json の "type": "commonjs" と、tsconfig.json の "verbatimModuleSyntax": true の組み合わせで起きました。今回は tsconfig.json の verbatimModuleSyntax を false にして動きました。package.json の type を module にする方法でも動きました。

Solana の airdrop で「Internal error」や 429 が返るときは？

今回の実測では、RPC から直接 airdrop を受け取れるのは 1 日 1 回で、その 1 回目が Internal error で消費されていました。以後の 429 の応答には retry-after: 86400（24 時間）が付いていました。

11. まとめ

主要な Web3 SDK・ツール 10 本の公式チュートリアルのうち、書かれたとおりに最後まで動いたのは 4 本でした。止まった原因で最も多かったのは、ドキュメントの誤りではなく、ページが書かれた後にツールの側が変わったことです。TypeScript 7、インストーラーの仕様変更、テンプレートの変更は、どれもこの数か月の出来事でした。

止まった 6 本のうち 5 本は、1〜3 手の修正で動きました。Solana Kit は、登録なしの範囲では最後まで動かせませんでした。

12. 著者：XTELAについて

本記事の本文は、各 SDK の公式チュートリアルの現状を中立的に示すことを目的としています。ここからは、検証を行った XTELA 自身について共有します。