Vite連携

******

<div class=perex>

最新のJavaScriptアプリケーションには、洗練されたビルドツールが必要です。Nette Assetsは、次世代のフロントエンドビルドツールである[Vite|https://vitejs.dev/]とのファーストクラスの連携を提供します。設定の手間なしで、ホットモジュールリプレイスメント（HMR）による超高速開発と最適化された本番ビルドを実現します。

- **ゼロ設定** - ViteとPHPテンプレート間の自動ブリッジ

- **完全な依存関係管理** - 1つのタグですべてのアセットを処理

- **ホットモジュールリプレイスメント** - JavaScriptとCSSの即時更新

- **最適化された本番ビルド** - コード分割とツリーシェイキング

</div>

Nette AssetsはViteとシームレスに連携するため、テンプレートを通常通り記述しながら、これらすべての恩恵を受けることができます。

Viteのセットアップ

===========

Viteをステップバイステップでセットアップしましょう。ビルドツールに慣れていなくても心配ありません。すべて説明します！

ステップ1: Viteをインストールする

--------------------

まず、プロジェクトにViteとNetteプラグインをインストールします。

```shell

npm install -D vite @nette/vite-plugin

```

これにより、Viteと、ViteがNetteと完全に連携するのに役立つ特別なプラグインがインストールされます。

ステップ2: プロジェクト構造

---------------

標準的なアプローチは、ソースアセットファイルをプロジェクトルートの`assets/`フォルダーに配置し、コンパイルされたバージョンを`www/assets/`に配置することです。

/--pre

<b>web-project/</b>

├── <b>assets/</b> ← ソースファイル (SCSS, TypeScript, ソース画像)

│ ├── <b>public/</b> ← 静的ファイル (そのままコピーされる)

│ │ └── <b>favicon.ico</b>

│ ├── <b>images/</b>

│ │ └── <b>logo.png</b>

│ ├── <b>app.js</b> ← メインエントリポイント

│ └── <b>style.css</b> ← スタイル

└── <b>www/</b> ← public ディレクトリ (ドキュメントルート)

├── <b>assets/</b> ← コンパイルされたファイルがここに入る

└── <b>index.php</b>

\--

`assets/`フォルダーにはソースファイル、つまり記述するコードが含まれています。Viteはこれらのファイルを処理し、コンパイルされたバージョンを`www/assets/`に配置します。

ステップ3: Viteを設定する

----------------

プロジェクトルートに`vite.config.ts`ファイルを作成します。このファイルは、Viteにソースファイルの場所とコンパイルされたファイルの出力先を指示します。

Nette Viteプラグインには、設定を簡素化するスマートなデフォルトが付属しています。フロントエンドのソースファイルは`assets/`ディレクトリ（`root`オプション）にあり、コンパイルされたファイルは`www/assets/`（`outDir`オプション）に配置されると想定しています。必要なのは[エントリポイント|#Entry Points]を指定することだけです。

```js

import { defineConfig } from 'vite';

import nette from '@nette/vite-plugin';

export default defineConfig({

plugins: [

nette({

entry: 'app.js',

}),

],

});

```

アセットをビルドするために別のディレクトリ名を指定したい場合は、いくつかのオプションを変更する必要があります。

```js

export default defineConfig({

root: 'assets', // ソースアセットのルートディレクトリ

build: {

outDir: '../www/assets', // コンパイルされたファイルの出力先

},

// ... その他の設定 ...

});

```

.[note]

`outDir`パスは`root`からの相対パスと見なされるため、先頭に`../`があります。

ステップ4: Netteを設定する

-----------------

`common.neon`でNette AssetsにViteについて伝えます。

```neon

assets:

mapping:

default:

type: vite # NetteにViteMapperを使用するよう指示

path: assets

```

ステップ5: スクリプトを追加する

-----------------

これらのスクリプトを`package.json`に追加します。

```json

{

"scripts": {

"dev": "vite",

"build": "vite build"

}

}

```

これで次のことができます。

- `npm run dev` - ホットリロード付き開発サーバーを開始

- `npm run build` - 最適化された本番ファイルを作成

エントリポイント

========

**エントリポイント**は、アプリケーションが開始するメインファイルです。このファイルから、他のファイル（CSS、JavaScriptモジュール、画像）をインポートし、依存関係ツリーを作成します。Viteはこれらのインポートを追跡し、すべてをバンドルします。

エントリポイント`assets/app.js`の例：

```js

// スタイルをインポート

import './style.css'

// JavaScriptモジュールをインポート

import netteForms from 'nette-forms';

import naja from 'naja';

// アプリケーションを初期化

netteForms.initOnLoad();

naja.initialize();

```

テンプレートでは、エントリポイントを次のように挿入できます。

```latte

{asset 'app.js'}

```

Nette Assetsは、必要なすべてのHTMLタグ（JavaScript、CSS、およびその他の依存関係）を自動的に生成します。

複数のエントリポイント

-----------

大規模なアプリケーションでは、個別のエントリポイントが必要になることがよくあります。

```js

export default defineConfig({

plugins: [

nette({

entry: [

'app.js', // public ページ

'admin.js', // 管理パネル

],

}),

],

});

```

異なるテンプレートで使用します。

```latte

{* public ページで *}

{asset 'app.js'}

{* 管理パネルで *}

{asset 'admin.js'}

```

重要: ソースファイルとコンパイル済みファイル

-----------------------

本番環境では、次のもののみをロードできることを理解することが重要です。

1. `entry`で定義された**エントリポイント**

2. `assets/public/`ディレクトリの**ファイル**

`{asset}`を使用して`assets/`から任意のファイルをロードすることは**できません**。JavaScriptまたはCSSファイルによって参照されているアセットのみです。ファイルがどこからも参照されていない場合、コンパイルされません。Viteに他のアセットを認識させたい場合は、[public フォルダー|#public folder]に移動できます。

デフォルトでは、Viteは4KB未満のすべてのアセットをインライン化するため、これらのファイルを直接参照できないことに注意してください。（[Vite ドキュメント|https://vitejs.dev/guide/assets.html]を参照）。

```latte

{* ✓ これは動作します - エントリポイントです *}

{asset 'app.js'}

{* ✓ これは動作します - assets/public/ にあります *}

{asset 'favicon.ico'}

{* ✗ これは動作しません - assets/ 内のランダムなファイルです *}

{asset 'components/button.js'}

```

開発モード

=====

開発モードは完全にオプションですが、有効にすると大きなメリットがあります。主な利点は**ホットモジュールリプレイスメント (HMR)**です。アプリケーションの状態を失うことなく変更を即座に確認できるため、開発エクスペリエンスがはるかにスムーズで高速になります。

Viteは、開発を信じられないほど高速にする最新のビルドツールです。従来のバンドラーとは異なり、Viteは開発中にコードをブラウザに直接提供するため、プロジェクトの規模に関係なくサーバーの起動が瞬時に行われ、更新も超高速です。

開発サーバーの起動

---------

開発サーバーを実行します。

```shell

npm run dev

```

次のように表示されます。

```

➜ Local: http://localhost:5173/

➜ Network: use --host to expose

```

開発中は、このターミナルを開いたままにしてください。

Nette Viteプラグインは、次の条件が満たされたときに自動的に検出します。

1. Vite開発サーバーが実行中である

2. Netteアプリケーションがデバッグモードである

両方の条件が満たされると、Nette Assetsはコンパイルされたディレクトリからではなく、Vite開発サーバーからファイルをロードします。

```latte

{asset 'app.js'}

{* 開発時: <script src="http://localhost:5173/app.js" type="module"></script> *}

{* 本番時: <script src="/assets/app-4a8f9c7.js" type="module"></script> *}

```

設定は不要です。ただ動作します！

異なるドメインでの作業

-----------

開発サーバーが`localhost`以外のもの（例: `myapp.local`）で実行されている場合、CORS（Cross-Origin Resource Sharing）の問題が発生する可能性があります。CORSは、ウェブブラウザのセキュリティ機能であり、デフォルトでは異なるドメイン間のリクエストをブロックします。PHPアプリケーションが`myapp.local`で実行されているが、Viteが`localhost:5173`で実行されている場合、ブラウザはこれらを異なるドメインと見なし、リクエストをブロックします。

これを解決するには2つのオプションがあります。

**オプション1: CORSを設定する**

最も簡単な解決策は、PHPアプリケーションからのクロスオリジンリクエストを許可することです。

```js

export default defineConfig({

// ... その他の設定 ...

server: {

cors: {

origin: 'http://myapp.local', // PHPアプリのURL

},

},

});

```

**オプション2: Viteを同じドメインで実行する**

もう1つの解決策は、ViteをPHPアプリケーションと同じドメインで実行することです。

```js

export default defineConfig({

// ... その他の設定 ...

server: {

host: 'myapp.local', // PHPアプリと同じ

},

});

```

実際、この場合でも、開発サーバーは同じホスト名ですが異なるポートで実行されるため、CORSを設定する必要があります。ただし、この場合、CORSはNette Viteプラグインによって自動的に設定されます。

HTTPS開発

-------

HTTPSで開発する場合、Vite開発サーバーには証明書が必要です。最も簡単な方法は、証明書を自動的に生成するプラグインを使用することです。

```shell

npm install -D vite-plugin-mkcert

```

`vite.config.ts`での設定方法は次のとおりです。

```js

import mkcert from 'vite-plugin-mkcert';

export default defineConfig({

// ... その他の設定 ...

plugins: [

mkcert(), // 証明書を自動生成し、httpsを有効にする

nette(),

],

});

```

CORS設定（上記のオプション1）を使用している場合、オリジンURLを`http://`ではなく`https://`を使用するように更新する必要があることに注意してください。

本番ビルド

=====

最適化された本番ファイルを作成します。

```shell

npm run build

```

Viteは次のことを行います。

- すべてのJavaScriptとCSSをミニファイします

- コードを最適なチャンクに分割します

- キャッシュバストのためにハッシュ化されたファイル名を生成します

- Nette Assets用のマニフェストファイルを作成します

出力例：

```

www/assets/

├── app-4f3a2b1c.js # メインJavaScript (ミニファイ済み)

├── app-7d8e9f2a.css # 抽出されたCSS (ミニファイ済み)

├── vendor-8c4b5e6d.js # 共有依存関係

└── .vite/

└── manifest.json # Nette Assetsのマッピング

```

ハッシュ化されたファイル名により、ブラウザは常に最新バージョンをロードします。

Public フォルダー

============

`assets/public/`ディレクトリ内のファイルは、処理されずにそのまま出力にコピーされます。

```

assets/

├── public/

│ ├── favicon.ico

│ ├── robots.txt

│ └── images/

│ └── og-image.jpg

├── app.js

└── style.css

```

通常通り参照します。

```latte

{* これらのファイルはそのままコピーされます *}

<link rel="icon" href={asset 'favicon.ico'}>

<meta property="og:image" content={asset 'images/og-image.jpg'}>

```

publicファイルの場合、FilesystemMapperの機能を使用できます。

```neon

assets:

mapping:

default:

type: vite

path: assets

extension: [webp, jpg, png] # 最初にWebPを試す

versioning: true # キャッシュバストを追加

```

`vite.config.ts`設定では、`publicDir`オプションを使用してpublicフォルダーを変更できます。

動的インポート

=======

Viteは最適なロードのためにコードを自動的に分割します。動的インポートを使用すると、実際に必要なときにのみコードをロードできるため、初期バンドルサイズを削減できます。

```js

// 重いコンポーネントをオンデマンドでロード

button.addEventListener('click', async () => {

let { Chart } = await import('./components/chart.js')

new Chart(data)

})

```

動的インポートは、必要なときにのみロードされる個別のチャンクを作成します。これは「コード分割」と呼ばれ、Viteの最も強力な機能の1つです。動的インポートを使用すると、Viteは動的にインポートされたモジュールごとに個別のJavaScriptファイルを自動的に作成します。

`{asset 'app.js'}`タグは、これらの動的チャンクを自動的にプリロード**しません**。これは意図的な動作です。使用されない可能性のあるコードをダウンロードしたくありません。チャンクは、動的インポートが実行されたときにのみダウンロードされます。

ただし、特定の動的インポートが重要であり、すぐに必要になることがわかっている場合は、それらをプリロードできます。

```latte

{* メインエントリポイント *}

{asset 'app.js'}

{* 重要な動的インポートをプリロード *}

{preload 'components/chart.js'}

```

これにより、ブラウザはチャートコンポーネントをバックグラウンドでダウンロードし、必要になったときにすぐに使用できるようにします。

TypeScriptサポート

==============

TypeScriptはそのまま動作します。

```ts

// assets/main.ts

interface User {

name: string

email: string

}

export function greetUser(user: User): void {

console.log(`Hello, ${user.name}!`)

}

```

TypeScriptファイルを通常通り参照します。

```latte

{asset 'main.ts'}

```

完全なTypeScriptサポートには、インストールが必要です。

```shell

npm install -D typescript

```

追加のVite設定

=========

以下に、詳細な説明付きの便利なVite設定オプションをいくつか示します。

```js

export default defineConfig({

// ソースアセットを含むルートディレクトリ

root: 'assets',

// 内容がそのまま出力ディレクトリにコピーされるフォルダー

// デフォルト: 'public' ('root'からの相対パス)

publicDir: 'public',

build: {

// コンパイルされたファイルの出力先 ('root'からの相対パス)

outDir: '../www/assets',

// ビルド前に出力ディレクトリを空にするか？

// 以前のビルドからの古いファイルを削除するのに便利

emptyOutDir: true,

// outDir内の生成されたチャンクとアセットのサブディレクトリ

// 出力構造を整理するのに役立つ

assetsDir: 'static',

rollupOptions: {

// エントリポイント - 単一のファイルまたはファイルの配列

// 各エントリポイントは個別のバンドルになる

input: [

'app.js', // メインアプリケーション

'admin.js', // 管理パネル

],

},

},

server: {

// 開発サーバーをバインドするホスト

// ネットワークに公開するには '0.0.0.0' を使用

host: 'localhost',

// 開発サーバーのポート

port: 5173,

// クロスオリジンリクエストのCORS設定

cors: {

origin: 'http://myapp.local',

},

},

css: {

// 開発時にCSSソースマップを有効にする

devSourcemap: true,

},

plugins: [

nette(),

],

});

```

これで完了です！Nette Assetsと連携した最新のビルドシステムが手に入りました。