pixijs-create

create pixi.js は、新しい PixiJS v8 プロジェクトをスキャフォールディングする公式 CLI です。任意のパッケージマネージャー（npm、yarn、pnpm、bun）で実行し、対話型メニューからテンプレートを選ぶか、--template を渡してプロンプトをスキップできます。自己完結型のプロジェクトフォルダーが作成されるので、その後 cd で移動し、依存関係をインストールして開発用スクリプトを実行します。

クイックスタート

対話型プロンプトを使って新しいプロジェクトをスキャフォールディングします。

npm create pixi.js@latest

または、プロジェクト名とテンプレートを渡してプロンプトをスキップします。

npm create pixi.js@latest my-game -- --template bundler-vite

続いて、次を実行します。

cd my-game
npm install
npm run dev

Node.js 18+ または 20+ が必要です。一部のテンプレート（特に creation-web と framework-react）では、より新しい Node.js バージョンが必要になる場合があります。その場合はパッケージマネージャーが警告します。

既存のプロジェクトへの PixiJS の追加

すでにバンドラー、フレームワーク、またはプロジェクトをセットアップ済みの場合は、CLI を使わず、パッケージを直接インストールしてください。

npm install pixi.js

その後、pixi.js からインポートし、pixijs-application に示すように Application を構築します。CLI テンプレートは新規プロジェクト向けの便利な機能です。npm install pixi.js で利用できる内容に、ライブラリ機能を追加するものではありません。

関連スキル： pixijs-application（スキャフォールディングされた new Application() + app.init() のエントリーポイントの仕組み）、pixijs-core-concepts（レンダラーとレンダーループ）、pixijs-scene-core-concepts（ステージに最初に追加する要素に必要なシーングラフの基礎）、pixijs-assets（テンプレートで public/ または src/assets/ に配置するテクスチャ、フォント、バンドルの読み込み）。

基本パターン

パッケージマネージャーを選ぶ

どのパッケージマネージャーでもコマンドの形式は同じです。

npm create pixi.js@latest
yarn create pixi.js
pnpm create pixi.js
bun create pixi.js

npm 7+ では、npm が CLI フラグを処理しないように、CLI フラグの前に -- を渡す必要があります。

npm create pixi.js@latest my-game -- --template bundler-vite

Yarn、pnpm、bun では追加の区切り文字は不要です。

yarn create pixi.js my-game --template bundler-vite
pnpm create pixi.js my-game --template bundler-vite
bun create pixi.js my-game --template bundler-vite

現在のディレクトリにスキャフォールディングするには、プロジェクト名として . を使います。

対話型の流れ

引数を指定せずに実行すると、プロンプトが順に表示されます。

1. プロジェクト名（デフォルトは pixi-project）。
2. フレームワーク／テンプレートのカテゴリ。
3. バリアント（該当する場合は TypeScript または JavaScript）。
4. 依存関係をすぐにインストールするかどうか（ランナーによって異なります）。

最後に、CLI は実行に使ったパッケージマネージャーに応じた cd、インストール、開発用コマンドを表示します。

非対話型の流れ

プロジェクト名と --template を渡すと、すべてのプロンプトをスキップできます。スクリプト、CI、クイックスタートのドキュメントでは、この形式を使います。

npm create pixi.js@latest my-game -- --template bundler-vite

利用可能なテンプレートプリセット

テンプレートは次の 4 つのカテゴリに分かれています。

• バンドラーテンプレート（bundler-*）：好みのバンドラーと連携する、汎用的な PixiJS のセットアップです。独自の構成を選びたい場合に使用してください。
• Creation テンプレート（creation-*）：プラットフォームに合わせたスターターで、AssetPack、サウンド、UI、シーンルーティングがあらかじめ組み込まれています。必要なものがそろった状態から始めたい場合に使用してください。
• フレームワークテンプレート（framework-*）：React などのホストフレームワークに PixiJS を組み込んだものです。
• 拡張機能テンプレート（extension-*）：再利用可能な PixiJS パッケージを構築するためのひな形です。

ほとんどの新規プロジェクトでは、bundler-vite から始めることをおすすめします。

テンプレート	含まれるもの
bundler-vite	Vite + TypeScript の PixiJS プロジェクトです。最初に選ぶテンプレートとしておすすめです。
bundler-vite-js	Vite + プレーン JavaScript です。
bundler-webpack	Webpack + TypeScript です。
bundler-webpack-js	Webpack + プレーン JavaScript です。
bundler-esbuild	esbuild + TypeScript です。
bundler-esbuild-js	esbuild + プレーン JavaScript です。
bundler-import-map	ブラウザーのインポートマップを使用する、バンドラー不要のセットアップです（学習やデモに適しています）。
creation-web	PixiJS Creation Engine の Web テンプレートです。シーンベースのゲームのひな形に、AssetPack、サウンド、UI の統合が含まれています。
framework-react	@pixi/react パッケージを使用する、React + TypeScript + PixiJS です。
framework-react-js	React + プレーン JavaScript + PixiJS です。
extension-default	再利用可能な PixiJS 拡張機能／パッケージを構築するためのスターターです。

最新の一覧は create-pixi リポジトリで管理されています。最新のメニューを確認する場合は、引数なしで npm create pixi.js@latest を実行してください。

ひな形作成後の流れ

すべてのテンプレートで、同じ 3 ステップのオンボーディングを行います。

cd my-game
npm install
npm run dev

npm run dev を実行すると、デフォルトのポート（Vite は 5173、webpack は 8080 など）でローカル開発サーバーが起動します。正確なポート番号は各テンプレートの README を確認してください。src/ の変更は、ページ全体を再読み込みすることなくホットリロードされます。

すべてのテンプレートで利用できるその他のスクリプト（プリセットによって名前が多少異なる場合があります）：

• npm run build：dist/ に本番用ビルドを生成します。
• npm run preview / npm run serve：本番用ビルドをローカルで配信します。
• npm run lint：テンプレートに設定済みのリンターが含まれている場合、それを実行します。

既存のディレクトリへのひな形作成

プロジェクト名に . を指定すると、現在の作業ディレクトリにファイルを作成できます。空でないディレクトリに競合するファイルがある場合、プロンプトで確認しない限り CLI は実行されません。

mkdir my-game
cd my-game
npm create pixi.js@latest . -- --template bundler-vite

TypeScript のセットアップ

PixiJS は WebGPU をサポートしているため、その型宣言は WebGPU の型に依存します。型の提供元は TypeScript のバージョンによって異なります。

• TypeScript 5： WebGPU の型は組み込まれていないため、PixiJS が @webgpu/types を追加します。追加のセットアップは不要です。
• TypeScript 6 および 7： WebGPU の型は "dom" ライブラリに組み込まれていますが、GPUTextureUsage など、一部の定義が含まれていないリリースもあります。"dom" の代わりに、すべての定義を含む @types/web を使用してください。競合するため、types に @webgpu/types が含まれている場合は削除してください。

npm install --save-dev @types/web

{
  "compilerOptions": {
    "lib": ["esnext"],
    "types": ["@types/web"]
  }
}

次のステップ

npm run dev の実行後、テンプレートは空のシーン、またはバニースプライトのシーンで開きます。一般的には、次の順に進めます。

1. pixijs-application を読んで、テンプレートのエントリーポイントで new Application() を作成し、await app.init(...) を呼び出す方法、app.stage / app.renderer / app.canvas の関係、ResizePlugin と TickerPlugin のデフォルトの動作を理解します。
2. pixijs-core-concepts を読んで、レンダラーとレンダーループの基本的な考え方を把握します。
3. 最初の本格的なシーンを追加する前に pixijs-scene-core-concepts を読んで、コンテナーとリーフのルールをあらかじめ把握します。
4. 実際のアートを読み込む準備ができたら、pixijs-assets を使ってテクスチャを追加します。

よくある間違い

[HIGH] npm 7 以降で -- 区切り文字を指定しない

誤り：

npm create pixi.js@latest my-game --template bundler-vite

正しい例：

npm create pixi.js@latest my-game -- --template bundler-vite

npm 7 以降では、引数を転送するために -- を指定しないと、パッケージ指定の後のフラグが消費されます。区切り文字を指定しないと、CLI は --template を無視し、対話型プロンプトに戻ります。Yarn、pnpm、bun では区切り文字は不要です。

[MEDIUM] 古い Node バージョンで実行する

PixiJS には Node 18 以降または 20 以降が必要です。一部のテンプレート（framework-react、creation-web）では、ツールの実行にさらに新しい Node が必要です。パッケージマネージャーから「engines」警告が表示された場合は、CLI を再実行する前に Node をアップグレードしてください。

[MEDIUM] Vite の本番ビルドでトップレベルの await app.init() が機能しない

Vite のバージョンが <=6.0.6 の場合、トップレベルの await は開発時には機能しますが、本番ビルドでは失敗します。そのため、モジュールスコープでこの処理を行う bundler-vite プロジェクトは、npm run build の実行後に失敗します。

const app = new Application();
await app.init({ resizeTo: window }); // broken at module top level in prod

代わりに、初期化処理を非同期 IIFE で囲みます。

(async () => {
  const app = new Application();
  await app.init({ resizeTo: window });
  document.body.appendChild(app.canvas);
})();

Vite を 6.0.6 より新しいバージョンにアップグレードしても解決しますが、IIFE のパターンはすべてのバージョンで安全に使え、PixiJS のクイックスタートガイドにも沿っています。

[HIGH] TypeScript 6 または 7 で @webgpu/types を types に残す

誤り：

{
  "compilerOptions": {
    "types": ["@webgpu/types"]
  }
}

正しい例：「@webgpu/types」のエントリを削除し、ほかのエントリはそのまま残します。

TypeScript 6 および 7 では、組み込みの "dom" ライブラリで WebGPU の型が宣言されるため、@webgpu/types はそれらを二重に宣言します。skipLibCheck: false の場合、lib.dom.d.ts と @webgpu/types 内で数十件の宣言の競合エラーが発生します。TypeScript 5 でのみ残してください。TypeScript 5 では、いずれにせよ PixiJS が自動的に読み込みます。

[MEDIUM] TypeScript 6 または 7 で Cannot find name 'GPUTextureUsage' が発生する

TypeScript 6.0.3 および 7.0.2 までのバージョンでは、組み込みの "dom" ライブラリに WebGPU のフラグ定数（GPUBufferUsage、GPUColorWrite、GPUMapMode、GPUShaderStage、GPUTextureUsage）が含まれていないため、これらを使う WebGPU のコードで TS2552 が発生します。@webgpu/types を再度追加すると、組み込みの型と競合するため、skipLibCheck: true の場合にしかコンパイルできません。@types/web 0.0.352 以降をインストールし、lib から "dom" を削除して、既存のエントリとともに "@types/web" を types に追加してください。詳しくは TypeScript のセットアップ を参照してください。

[MEDIUM] moduleResolution: "node" によってサブパスのインポートが機能しない

誤り：

{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

正しい例：

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler"
  }
}

"node"（"node10" とも呼ばれます）は、PixiJS の package.json にある exports フィールドを無視するため、import 'pixi.js/advanced-blend-modes' などのサブパスのインポートが解決されません。TypeScript 6 では TS2882 が報告され、この設定は非推奨になります（TS5107）。TypeScript 7 ではこの設定が削除されます（TS5108）。バンドラーを使用する場合は "bundler" を、それ以外の場合は "nodenext" を使用してください。

API リファレンス

• GitHub の create-pixi
• create-pixi のドキュメントサイト
• Application：生成されたエントリーポイントでインスタンス化されるクラスです。
• TypeScript ガイド：TypeScript 5、6、7 のセットアップ方法です。