技術資料

今回は、Windows 11のPowerShellからViteを使ったVue.jsプロジェクトを作成し、生成されたファイルの構成を確認します。作成した画面を変更し、開発サーバーで動作を確認した後、プロダクションビルドと静的ホスティングへの配置まで進めます。

この記事ではJavaScript構成の最小限のプロジェクトを対象にします。

前提環境

今回の前提環境は以下の通りです。

• OS: Windows 11
• ターミナル: PowerShell
• Node.js: 20.19以上、または22.12以上
• npm
• Webブラウザ

Vue.jsの公式クイックスタートでは、Node.jsのバージョンとして^20.19.0 || >=22.12.0が案内されています。Viteやテンプレートの更新によって必要なバージョンが変わる可能性があるため、記事を試す前にVue.js公式のクイックスタートも確認してください。

PowerShellでNode.jsとnpmのバージョンを確認します。

node --version
npm --version

今回は、Node.jsはv20.20.2、npmは10.8.2の環境で解説します。バージョンが古い場合や、コマンドが見つからない場合は、Node.jsのインストール状態とPATHの設定を確認します。

Vue.jsとViteの役割

Vue.jsは、画面をコンポーネントとして分割し、データの変化に応じて画面を更新するためのJavaScriptフレームワークです。

Viteは、開発サーバーとプロダクションビルドを担当するビルドツールです。開発中はファイルの変更をブラウザへ反映し、本番用にはJavaScriptやCSSなどを最適化したファイルへ変換します。詳しくはVite公式のGetting Startedを参照してください。

Vue.jsとViteの役割を簡単に分けると、次のようになります。

Vue.js
  └─ コンポーネント、リアクティブなデータ、画面の構成

Vite
  ├─ 開発サーバーとHMR
  └─ プロダクション用ファイルのビルド

Vue.js公式のプロジェクト作成ツールであるcreate-vueを使うと、Viteを使った構成と、VueのSingle-File Components（SFC）を利用できるプロジェクトが作成されます。

Viteを使ったVue.jsプロジェクトを作成する

create-vueを実行する

作成したプロジェクトを保存する場所へ移動し、Vue公式のプロジェクト作成コマンドを実行します。

npm create vue@latest

プロジェクト名や、追加する機能を質問されます。今回は、次のようにJavaScriptの最小構成を選択します。

Project name: vue-vite-sample
Add TypeScript? No
Add JSX Support? No
Add Vue Router for Single Page Application development? No
Add Pinia for state management? No
Add Vitest for Unit testing? No
Add an End-to-End Testing Solution? No
Add ESLint for code quality? No
Add Prettier for code formatting? No
Add Vue DevTools 7 extension for debugging? No

表示される質問項目は、create-vueのバージョンによって変わる可能性があります。RouterやPiniaなどが必要なプロジェクトでは、作成時にYesを選択して構いません。

プロジェクトのディレクトリへ移動し、依存パッケージをインストールします。

cd .\vue-vite-sample
npm install

npm installを実行すると、package.jsonに定義された依存パッケージがnode_modulesへインストールされます。npmを使った場合は、依存関係の解決結果がpackage-lock.jsonへ保存されます。

Viteのテンプレートを直接使う場合

Viteには、Vue.jsを含む複数のテンプレートを作成するコマンドもあります。

npm create vite@latest vue-vite-sample -- --template vue

今回はVue公式のcreate-vueを使いました。Vueの追加機能を質問形式で選びながら始めたい場合はcreate-vue、Viteのテンプレートを直接指定したい場合はcreate vite、というように使い分けるとよいかと思います。

生成されたファイル構成

JavaScript構成で作成したプロジェクトには、例えば次のようなファイルが作られます。初期設定や選択した機能によって、ファイル名や内容は変わる可能性があります。

vue-vite-sample/
├─ node_modules/
├─ public/
├─ src/
│  ├─ assets/
│  ├─ components/
│  │  └─ HelloWorld.vue
│  ├─ App.vue
│  └─ main.js
├─ .gitignore
├─ index.html
├─ package.json
├─ package-lock.json
├─ vite.config.js
└─ README.md

まず覚えておきたいファイルやディレクトリの役割を整理します。

ファイル・ディレクトリ	役割
src/	VueコンポーネントやJavaScript、CSSなど、主に開発するファイルを置く場所
src/main.js	Vueアプリケーションを作成し、HTMLの要素へマウントするエントリーポイント
src/App.vue	アプリケーションのルートコンポーネント
src/components/	画面の一部として再利用するコンポーネントを置く場所
public/	変換せずに公開する静的ファイルを置く場所
index.html	Viteが開発時とビルド時に扱うHTMLの入口
package.json	依存パッケージとnpm scriptsを定義するファイル
vite.config.js	Viteの設定とVue用プラグインなどを定義するファイル
dist/	npm run buildで作成される本番用ファイルの出力先

index.htmlとsrc/main.js

Viteのプロジェクトでは、index.htmlがプロジェクトの入口になります。publicの中に入口のHTMLを作る構成ではない点が、従来の構成と異なるところです。

index.htmlには、Vueアプリケーションを表示するための要素が用意されています。

<div id="app"></div>
<script type="module" src="/src/main.js"></script>

src/main.jsでは、createAppでVueアプリケーションを作成し、App.vueを#appへマウントします。

import './assets/main.css';
import { createApp } from 'vue';
import App from './App.vue';

createApp(App).mount('#app');

この処理によって、App.vueの内容がindex.htmlのdiv#appへ表示されます。Vue公式のアプリケーション作成に関するドキュメントでも、createAppとmountを使った構成が説明されています。

App.vueとSingle-File Component

App.vueのように、拡張子が.vueのファイルはVueのSingle-File Component（SFC）です。テンプレート、JavaScript、CSSを1つのファイルへまとめられます。

例えば、次のような構成です。

<script setup>
const message = 'Vue.jsの画面です';
</script>

<template>
    <h1>{{ message }}</h1>
</template>

<style scoped>
h1 {
    color: #42b883;
}
</style>

<script setup>は、Composition APIを使うための記法です。ここで定義した変数や関数を、同じコンポーネントのテンプレートから利用できます。

package.jsonとvite.config.js

package.jsonには、依存パッケージとコマンドが定義されています。初期構成では、次のようなnpm scriptsが用意されています。

{
    "scripts": {
        "dev": "vite",
        "build": "vite build",
        "preview": "vite preview"
    }
}

vite.config.jsには、Viteの設定とVue用プラグインが定義されています。.vueファイルを扱えるのは、ViteへVue用のプラグインが設定されているためです。

設定ファイルは、エイリアス、開発サーバーのポート、公開先のパスなどを変更するときに編集します。最初からすべての設定を変更する必要はありません。

開発サーバーを起動する

プロジェクトのルートディレクトリで、開発サーバーを起動します。

npm run dev

実行すると、Viteがローカルの開発サーバーを起動し、アクセス用のURLを表示します。通常はhttp://localhost:5173/が使われますが、ポートが使用中の場合などは別のURLになることがあります。

表示されたURLをブラウザで開き、Vueの初期画面が表示されることを確認します。

開発サーバーを停止する場合は、PowerShellでCtrlキーを押しながらCキーを押します。

Vueコンポーネントを変更する

次に、src/App.vueを編集して、ボタンを押した回数を表示する画面へ変更します。

<script setup>
import { ref } from 'vue';

const count = ref(0);
</script>

<template>
    <main>
        <h1>Vite + Vue.js</h1>
        <p>ボタンを押した回数: {{ count }}</p>
        <button type="button" @click="count++">
            カウント
        </button>
    </main>
</template>

<style scoped>
main {
    max-width: 640px;
    margin: 40px auto;
    padding: 0 16px;
}

button {
    padding: 8px 16px;
}
</style>

ref(0)は、値が変化したときに画面を更新できるリアクティブな値を作ります。テンプレート内では、refが持つ値を自動的に展開して表示できます。

@clickは、ボタンのクリックイベントを処理するVueの記法です。ファイルを保存すると、ViteのHMR（Hot Module Replacement）によって、開発サーバーを停止せずにブラウザの表示が更新されます。

コンポーネントを分割する

画面が大きくなったら、処理や表示単位に応じてコンポーネントを分けます。例えば、src/components/MessageCard.vueを作成します。

<template>
    <section>
        <h2>メッセージ</h2>
        <p>コンポーネントを分けて管理しています。</p>
    </section>
</template>

App.vueから読み込んで表示します。

<script setup>
import MessageCard from './components/MessageCard.vue';
</script>

<template>
    <main>
        <h1>Vite + Vue.js</h1>
        <MessageCard />
    </main>
</template>

このように、App.vueをルートとして、その下に複数のコンポーネントを配置していくのが基本的な構成です。Vueの公式ドキュメントでも、実際のアプリケーションは再利用可能なコンポーネントのツリーとして構成すると説明されています。

プロダクション用にビルドする

開発サーバーでの確認が終わったら、プロダクション用のファイルを作成します。

npm run build

ビルドが成功すると、プロジェクトのルートにdistディレクトリが作成されます。JavaScriptやCSS、画像などが、Webサーバーへ配置できる形式で出力されます。Viteのプロダクションビルドに関する公式ドキュメントでも、vite buildを使って本番用ファイルを作成する流れが説明されています。

ビルド結果をローカルで確認する場合は、次のコマンドを実行します。

npm run preview

npm run previewは、ビルド済みのdistをローカルで確認するためのコマンドです。本番用のWebサーバーとして使うためのコマンドではありません。Vite公式の静的サイトのデプロイガイドでも、vite previewは本番サーバーとして使用しないよう説明されています。

静的ホスティングへデプロイする

今回のJavaScript構成では、ビルドした静的ファイルをWebサーバーや静的ホスティングへ配置できます。ホスティングサービスを指定しない場合の基本的な手順は次の通りです。

1. ローカルでnpm installを実行する。
2. npm run buildを実行する。
3. 生成されたdistディレクトリの中身を確認する。
4. 静的ホスティングの公開ディレクトリへ、distの中身を配置する。
5. 公開URLへアクセスし、画面とCSS、画像の表示を確認する。

例えば、ホスティング先の公開ディレクトリがpublic_htmlであれば、概念的には次のような対応になります。

ローカルの dist/
  ├─ index.html
  ├─ assets/
  └─ その他の生成ファイル

        ↓ 配置

公開ディレクトリ/
  ├─ index.html
  ├─ assets/
  └─ その他の生成ファイル

アップロード方法は、利用するホスティングサービスやサーバーによって異なります。FTP、管理画面のファイルアップロード、デプロイ用CLIなど、サービスの公式手順に合わせてください。

サブディレクトリへ配置する場合

サイトのルートではなく、https://example.com/vue-app/のようなサブディレクトリへ配置する場合は、生成されるアセットのURLに注意が必要です。

例えば、Viteの設定でbaseを指定します。

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [vue()],
    base: '/vue-app/',
});

設定を変更したら、もう一度ビルドします。

npm run build

baseの値は、実際に公開するURLのパスと合わせます。ルートへ配置する場合は、初期設定のままで問題ありません。

Vue Routerを後から使う場合の注意

今回はVue Routerを導入していないため、1つのindex.htmlを入口とする静的サイトとして配置できます。

後からVue Routerを使ったSPAへ変更する場合は、/users/1のようなURLへ直接アクセスしたときにも、サーバーがindex.htmlを返す設定が必要になることがあります。静的ホスティングへデプロイする前に、利用するサービスのSPA向けフォールバック設定を確認してください。

Gitへ登録しないファイル

プロジェクトをGitで管理する場合は、依存関係のインストール先や環境固有のファイルをそのまま登録しないようにします。

• node_modules/: npm installで再作成できるため、通常は登録しない。
• dist/: デプロイ方法によって扱いが異なるため、プロジェクトの方針を確認する。
• .env: APIキーやパスワードなどの秘密情報を含めない。
• package-lock.json: npmの依存関係を再現するため、通常は登録する。

初期プロジェクトには.gitignoreが用意されているため、内容を確認してからGitへ登録します。公開用の環境変数を使う場合でも、秘密情報をフロントエンドへ埋め込んでよいとは限りません。Viteでクライアントへ公開される値の扱いは、用途と公開範囲を確認して決めます。

うまく動かない場合の確認

nodeやnpmが見つからない

コマンドが見つからない場合は、Node.jsがインストールされているか、PATHが設定されているかを確認します。Node.jsをインストールした直後は、PowerShellを開き直すと環境変数が反映される場合があります。

npm run devで画面が表示されない

PowerShellに表示されたURLを確認し、開発サーバーが終了していないかを確認します。ポートが使用中の場合は、Viteが別のポートを表示していないかも確認してください。

ソースコードを変更した後にエラーが表示された場合は、ブラウザの画面だけでなく、開発サーバーを起動したPowerShellのエラーも確認します。

デプロイ後にCSSや画像が表示されない

サイトをサブディレクトリへ配置している場合は、Viteのbase設定と公開URLが一致しているか確認します。また、distディレクトリそのものではなく、その中身を公開ディレクトリへ配置する必要があるサービスもあります。

まとめ

Vue.jsをViteのプロジェクトとして始める場合は、Vue公式のcreate-vueでJavaScript構成を作成し、まずはsrc/App.vueとsrc/main.jsの関係を確認すると理解しやすくなります。

開発中はnpm run devでViteの開発サーバーを起動し、ファイルを変更しながらHMRで表示を確認します。公開前にはnpm run buildでdistを作成し、npm run previewでビルド結果を確認します。

静的ホスティングへ配置する場合は、distの内容を公開ディレクトリへ配置し、公開URLのパスに応じてViteのbaseを設定します。Vue Routerなどを追加する場合は、SPAのフォールバック設定もデプロイ先で確認するとよいかと思います。