Vue環境構築｜create-vueでプロジェクト作成とディレクトリ構成

Vueの環境構築は、Node.jsを入れたうえで npm create vue@latest を実行し、npm install と npm run dev を続けるだけで完了します。 create-vueはVue公式のプロジェクト作成ツールで、Vite（開発サーバーとビルドを担当するツール）を土台に、TypeScript・ルーター・状態管理・テスト・リンターを質問に答える形で組み込めます。

この記事では、create-vue 3.24.0 を実際に実行して得た画面と出力をもとに、対話項目とコマンドラインフラグの対応、質問なしで一発生成するコマンド、生成される全ファイルの役割、npm scripts、そしてつまずきやすい3つの場面（Nodeのバージョン不足・ポートの競合・ほかの端末からつながらない）のエラー文と対処を順に説明します。

確認環境：Ubuntu 24.04 / Node.js 22.22.2 / npm 10.9.7（一部 npm 11.21.0） / create-vue 3.24.0 / Vite 8.3.2 / Vue 3.5.43 / TypeScript 6.0.3 / Chromium 141（Playwright 1.56.0）。バージョン不足の再現には Node.js 18.20.8 と 20.18.3 を使いました。開発サーバーのポートは、この環境で使える 8951 番を --port で指定しています（既定の 5173 番を使う場合は数字を読み替えてください）。出力中のパスとプロジェクト名は、/home/taro/ と my-app に置き換えています。

Vue環境構築の早見表

準備：Node.jsのバージョンを確かめる

最初に確かめるのはNode.jsのバージョンです。Vue公式のクイックスタートには、前提として Node.js ^22.18.0 || >=24.12.0 と書かれています。create-vue 3.24.0 のパッケージ情報（engines）と、生成される package.json の engines も同じ値でした。

node -v
npm -v

v22.22.2
10.9.7

22.18以上（または24.12以上）にしておけば、3つとも満たせます。 満たしていないときに何が起きるかは、後半の「エラー文と対処」で実際の出力を載せています。

create-vueでプロジェクトを作る（対話形式）

npm create vue@latest

初回は create-vue 本体が npm から取得されます。その後、次の順に質問が出ます。create-vue 3.24.0 の画面をそのまま写したものです。

┌  Vue.js - The Progressive JavaScript Framework
│
◆  Project name (target directory):
│  vue-project
└

◆  Use TypeScript?
│  ● Yes / ○ No

◆  Select features to include in your project: (↑/↓ to navigate, space to select, a to toggle all,
│  enter to confirm)
│  ◻ JSX Support
│  ◻ Router (SPA development)
│  ◻ Pinia (state management)
│  ◻ Vitest (unit testing)
│  ◻ End-to-End Testing
│  ◻ Linter (error prevention)
│  ◻ Prettier (code formatting)

◆  Select experimental features to include in your project: (↑/↓ to navigate, space to select, a to
│  toggle all, enter to confirm)
│  ◻ Replace Prettier with Oxfmt
│  ◻ Vue 3.6 (Release Candidate)
│  ◻ Replace TypeScript with typescript-native-bridge (tsgo)

◆  Skip all example code and start with a blank Vue project?
│  ○ Yes / ● No

機能の一覧で End-to-End Testing を選ぶと、続けてツールを選ぶ質問が出ます。

◆  Select an End-to-End testing framework: (↑/↓ to navigate, enter to confirm)
│  ● Playwright (https://playwright.dev/)
│  ○ Cypress

最後まで答えると、次の案内が出て完了です。

└  Done. Now run:
   cd my-app
   npm install
   npm run dev
| Optional: Initialize Git in your project directory with:
   git init && git add -A && git commit -m "initial commit"

操作キー

迷ったら、TypeScriptはYes、機能はRouter・Pinia・Linter・Prettierを選んでおくと、あとから足す手間が減ります。学習用に最小で始めたい場合は、何も選ばずEnterで進めて構いません。

対話項目とコマンドラインフラグの対応表

対話の質問は、すべてコマンドラインのフラグでも指定できます。npm create vue@latest -- --help の出力と、実際の対話画面を突き合わせた対応表です。

質問とは別に使えるオプションもあります。

ヘルプには、「機能フラグを1つでも付けると対話なしで進む。フォルダ名が無い、またはパッケージ名として使えない場合は対話になる」という説明があります。また、--eslint を付けると Oxlint も一緒に入ります（ヘルプには、以前の --oxlint は ESLint 選択時に常に含まれるようになったと書かれています）。

質問なしで一発生成するコマンド

よく使う構成をまとめて作る

npm create vue@latest my-app -- --ts --router --pinia --vitest --eslint --prettier

-- は「ここから後ろは create-vue に渡す」という区切りです。npm 経由で実行するときに必要になります。実行すると質問は出ず、次の案内で終わりました。

—  Done. Now run:

   cd my-app
   npm install
   npm run format
   npm run dev

Prettier を入れたので、案内に npm run format が1行増えています。

目的別のコマンド

create-vue 3.24.0 では、--default で作ったプロジェクトも TypeScript 構成（main.ts と tsconfig 一式）でした。 --default と --ts で生成されるファイルは同じ25個です。

--bare を付けると、サンプルのコンポーネントやCSSが省かれ、App.vue は次の内容だけになります。

<script setup lang="ts"></script>

<template>
  <h1>You did it!</h1>
  <p>
    Visit <a href="https://vuejs.org/" target="_blank" rel="noopener">vuejs.org</a> to read the
    documentation
  </p>
</template>

<style scoped></style>

同じ名前のフォルダがあるとき

すでに中身のあるフォルダ名を指定すると、フラグ付きでも確認の質問が出ます。

*  Target directory "my-app" is not empty. Remove all existing files and
|  continue?
|    Yes / > No

--force を付けると、この確認なしで作り直します。実際に試すと、もとのフォルダにあった node_modules やルーターのファイルは残らず、新しく生成されたファイルだけになりました。大事なファイルがあるフォルダには使わないようにします。

インストールして起動する

cd my-app
npm install
npm run dev

  VITE v8.3.2  ready in 569 ms

  ➜  Local:   http://localhost:8951/
  ➜  Network: use --host to expose
  ➜  Vue DevTools: Open http://localhost:8951/__devtools__/ as a separate window
  ➜  Vue DevTools: Press Alt(⌥)+Shift(⇧)+D in App to toggle the Vue DevTools

（この出力は npm run dev -- --port 8951 で起動したものです。ポートを指定しない場合、Viteの既定のポートは 5173 です。）

Local に表示されたURLをブラウザで開けば、Vueの画面が表示されます。 Chromium で開いて、ページのタイトルと見出しを取得した結果です。

http://localhost:8951/ | title = Vite App | h1 = ['You did it!']
http://localhost:8951/about | title = Vite App | h1 = ['You did it!', 'This is an about page']

ルーターを入れた構成なので、/about でも見出しが表示されています。止めるときは、ターミナルで Ctrl + C を押します。

ディレクトリ構成と全ファイルの役割

ここからは、生成されたファイルを1つずつ見ていきます。

最小構成（--ts）の25ファイル

my-app/
├── .gitignore
├── .vscode/
│   ├── extensions.json
│   └── settings.json
├── README.md
├── env.d.ts
├── index.html
├── package.json
├── public/
│   └── favicon.ico
├── src/
│   ├── App.vue
│   ├── main.ts
│   ├── assets/
│   │   ├── base.css
│   │   ├── logo.svg
│   │   └── main.css
│   └── components/
│       ├── HelloWorld.vue
│       ├── TheWelcome.vue
│       ├── WelcomeItem.vue
│       └── icons/（Icon〜.vue が5個）
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
└── vite.config.ts

生成された index.html と main.ts、vite.config.ts は次のとおりです。

<!DOCTYPE html>
<html lang="">
  <head>
    <meta charset="UTF-8">
    <link rel="icon" href="/favicon.ico">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Vite App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

// vite.config.ts
import { fileURLToPath, URL } from 'node:url'

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

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    vueDevTools(),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

生成直後の index.html は lang が空、title が Vite App です。日本語のアプリなら lang="ja" と自分のタイトルに書き換えておくと、検索エンジンや読み上げソフトに正しく伝わります。

画面が表示されるまでの流れ

flowchart LR
  A[index.html] -->|script type=module| B[src/main.ts]
  B -->|createApp| C[src/App.vue]
  C --> D[src/components の部品]
  B -->|app.use| E[router と pinia]
  E --> F[src/views の画面]

フラグで増えるファイル

--ts --router --pinia --vitest --eslint --prettier で作ると、ファイルは37個になりました。増えた12個の役割です。

main.ts も、ルーターと Pinia を登録する形に変わります。

import './assets/main.css'

import { createApp } from 'vue'
import { createPinia } from 'pinia'

import App from './App.vue'
import router from './router'

const app = createApp(App)

app.use(createPinia())
app.use(router)

app.mount('#app')

置き場所に迷ったときの目安

npm scripts早見表

package.json の scripts に入っているコマンドの一覧です。上の5つは最小構成にもあり、下の5つはフラグで増えます。

build の実行結果

> my-app@0.0.0 build
> run-p type-check "build-only {@}" --

> my-app@0.0.0 type-check
> vue-tsc --build

> my-app@0.0.0 build-only
> vite build

vite v8.3.2 building client environment for production...
transforming...
✓ 44 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html                       0.42 kB │ gzip:  0.28 kB
dist/assets/AboutView-CXtZgaLf.css    0.08 kB │ gzip:  0.10 kB
dist/assets/index-DEm2-gV0.css        4.05 kB │ gzip:  1.27 kB
dist/assets/AboutView--eSdL59e.js     0.22 kB │ gzip:  0.19 kB
dist/assets/index-C-ponb03.js       100.41 kB │ gzip: 38.83 kB

✓ built in 316ms

dist フォルダに index.html・assets・favicon.ico が出力されます。 AboutView が別ファイルになっているのは、サンプルのルーターが /about の画面を必要になった時点で読み込む書き方になっているためです。

テストと preview の実行結果

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Duration  981ms (transform 63ms, setup 0ms, import 187ms, tests 16ms, environment 628ms)

（npx vitest run の出力です。npm run test:unit は変更を監視し続けるモードで起動するので、1回だけ実行したいときは npx vitest run が便利です。）

  ➜  Local:   http://localhost:8953/
  ➜  Network: use --host to expose

（npm run preview -- --port 8953 の出力です。Chromium で開くと、開発サーバーと同じ見出し You did it! が表示されました。）

scripts に引数を渡す書き方

npm run dev -- --port 8951 のように、-- のあとに書いたものが vite に渡ります。

エラー文と対処：Nodeのバージョンが足りないとき

ここからは、つまずきやすい場面を実際に再現した結果です。

Node.js 18 で create-vue を実行した場合

file:///home/taro/.npm/_npx/2f7e7bff16d1c534/node_modules/create-vue/bundle.js:8
import { parseArgs, styleText } from "node:util";
                    ^^^^^^^^^
SyntaxError: The requested module 'node:util' does not provide an export named 'styleText'

Node.js v18.20.8

「styleText が無い」という構文エラーで止まります。 バージョン不足とは書かれていませんが、最後の行の Node.js v18.20.8 が手がかりです。Node.js を上げると解消します。

Node.js 18 で Vite を実行した場合

すでにあるプロジェクトで vite build を実行したときも、同じ形のエラーになりました。

file:///home/taro/my-app/node_modules/rolldown/dist/shared/create-bundler-option-DLv8UpsD.mjs:8
import { formatWithOptions, styleText } from "node:util";
                            ^^^^^^^^^
SyntaxError: The requested module 'node:util' does not provide an export named 'styleText'

Node.js v18.20.8

Node.js 20.18 の場合：動くが案内が出る

20.18.3 では、create-vue もビルドも最後まで進みました。ただし、Vite は最初に次の案内を出します。

You are using Node.js 20.18.3. Vite requires Node.js version 20.19+ or 22.12+. Please upgrade your Node.js version.

npm install では、条件に合わないパッケージごとに EBADENGINE の警告が出ます。

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'my-app@0.0.0',
npm warn EBADENGINE   required: { node: '^22.18.0 || >=24.12.0' },
npm warn EBADENGINE   current: { node: 'v20.18.3', npm: '10.9.7' }
npm warn EBADENGINE }
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@vitejs/plugin-vue@6.0.9',
npm warn EBADENGINE   required: { node: '^20.19.0 || >=22.12.0' },
npm warn EBADENGINE   current: { node: 'v20.18.3', npm: '10.9.7' }
npm warn EBADENGINE }

required と current を見比べれば、どこまで上げればよいかがわかります。 警告のうちに 22.18 以上（または 24.12 以上）へ上げておくと、あとの作業が安定します。

npm install が edgesOut のエラーで止まる場合

確認環境の npm 10.9.7 では、フラグを多く付けた構成（--ts --router --pinia --vitest --eslint --prettier）の npm install が次のエラーで止まりました。最小構成（--ts）は同じ npm で問題なく入りました。

npm error Cannot read properties of null (reading 'edgesOut')

npm 11.21.0 で実行し直すと、同じプロジェクトがそのままインストールできました。

npx npm@11 install

同じエラーに出会ったら、npm -v で npm のバージョンを確かめ、新しい npm で試してみてください。

エラー文と対処：ポートが競合するとき

開発サーバーを起動したまま、別のターミナルでもう一度同じポートで起動した結果です。

Port 8951 is in use, trying another one...

  VITE v8.3.2  ready in 1741 ms

  ➜  Local:   http://localhost:8952/
  ➜  Network: use --host to expose

Viteは、使用中なら自動で次の番号（8952）に移って起動します。 エラーにはならないので、「いつものURLを開いたのに別のアプリが表示される」ときは、起動時の Local の行を見直します。既定の 5173 番でも同じ動きで、Viteの公式ドキュメント（サーバーオプション）にも「ポートがすでに使われている場合、次に使えるポートを自動的に試す」と書かれています。

必ず同じポートで起動したい場合（--strictPort）

npm run dev -- --port 8951 --strictPort

error when starting dev server:
Error: Port 8951 is already in use
    at httpServerStart (file:///home/taro/my-app/node_modules/vite/dist/node/chunks/node.js:14540:10)

--strictPort を付けると、別の番号に移らずエラーで止まります。ほかのツールがそのポート番号を前提にしている場合に向いています。

どのプロセスがポートを使っているか調べる

ss -ltnp | grep :8951

LISTEN 0      511        127.0.0.1:8951       0.0.0.0:*    users:(("node",pid=12357,fd=21))

pid= の数字がプロセス番号です。止め忘れた開発サーバーなら、その番号を指定して止めます。

kill 12357

エラー文と対処：ほかの端末からつながらないとき（--host）

スマートフォンでの表示確認や、仮想マシン・コンテナの外からのアクセスで出会う場面です。

既定の状態

起動時の表示に Network: use --host to expose とあります。この状態では、開発サーバーは自分自身（127.0.0.1）からの接続だけを受け付けます。

ss -ltn | grep 8951
curl -o /dev/null -w "%{http_code}\n" http://localhost:8951/
curl -o /dev/null -w "%{http_code}\n" http://192.0.2.2:8951/

LISTEN 0      511        127.0.0.1:8951       0.0.0.0:*
200
curl: (7) Failed to connect to 192.0.2.2 port 8951 after 0 ms: Couldn't connect to server

localhost では 200 が返り、マシンのIPアドレス（この環境では 192.0.2.2）を指定すると接続できません。ほかの端末から開けないときは、まずこの待ち受けアドレスを確かめます。

--host を付けた場合

npm run dev -- --host

  VITE v8.3.2  ready in 842 ms

  ➜  Local:   http://localhost:8951/
  ➜  Network: http://192.0.2.2:8951/  eth0

LISTEN 0      511          0.0.0.0:8951       0.0.0.0:*
200

待ち受けが 127.0.0.1 から 0.0.0.0（すべてのアドレス）に変わり、Network の行にURLが表示されます。 同じIPアドレスへの curl も 200 になりました。ほかの端末からは、この Network のURLを開きます。

設定ファイルに書いておく

毎回フラグを付ける代わりに、vite.config.ts の server に書いておけます。

// vite.config.ts
import { fileURLToPath, URL } from 'node:url'

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

export default defineConfig({
  plugins: [vue(), vueDevTools()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
  server: {
    port: 8951,        // 開発サーバーのポート（既定は 5173）
    strictPort: true,  // 使用中なら別のポートに移らず、エラーで止まる
    host: true,        // ほかの端末からもつながるようにする（--host と同じ）
  },
})

この設定で npm run dev を実行すると、フラグなしで Network の行が表示され、2つ目を起動すると Error: Port 8951 is already in use で止まることを確かめました。

--host は、同じネットワークにいるほかの端末からも開発中の画面が見える状態です。作業が終わったら外す、信頼できるネットワークで使う、という使い方が安心です。

環境構築のチェック表

よくある質問

Q. Vue CLI（vue create）との違いは何ですか？ A. Vue公式のクイックスタートが案内しているのは create-vue（npm create vue@latest）で、土台に Vite を使います。これから新しく作る場合は、この記事の手順で始めるのが素直です。

Q. あとからルーターや Pinia を足せますか？ A. 足せます。手本として、同じフラグを付けた別のフォルダを生成して見比べる方法がわかりやすいです。増えるのは package.json の依存パッケージ、main.ts の app.use(createPinia()) と app.use(router)、src/router・src/views・src/stores の3フォルダなので、この差分を自分のプロジェクトに写します。

Q. --default と --ts は何が違いますか？ A. create-vue 3.24.0 で試した範囲では、どちらも同じ25ファイルの TypeScript 構成になりました。ルーターなどを足したい場合は、--ts --router のように必要なフラグを並べます。

Q. npm 以外のパッケージマネージャーでも作れますか？ A. Vue公式のクイックスタートには、pnpm create vue@latest、yarn create vue@latest、bun create vue@latest も載っています。この記事の出力はすべて npm で実行したものです。

まとめ

• Vueの環境構築は npm create vue@latest → npm install → npm run dev の3手順。Node.js は 22.18 以上（または 24.12 以上）を用意する
• 対話の質問はすべてフラグで指定できる。npm create vue@latest my-app -- --ts --router --pinia --vitest --eslint --prettier で、質問なしの一発生成ができる
• 最小構成は25ファイル、フラグを付けた構成は37ファイル。index.html → main.ts → App.vue の順に読み込まれ、部品は components、画面は views、状態は stores に置く
• npm scripts は dev・build・preview が基本。build は型チェックとビルドを並行して行い、dist に出力する
• Nodeが足りないと、18 では styleText の構文エラーで止まり、20.18 では Vite の案内と EBADENGINE の警告が出る
• ポートが使用中なら Vite は自動で次の番号に移る。固定したいときは --strictPort、使っているプロセスは ss -ltnp で調べる
• ほかの端末からつなぐには --host。待ち受けが 127.0.0.1 から 0.0.0.0 に変わり、Network のURLが表示される

参考

• Vue.js 公式ドキュメント「クイックスタート」 https://ja.vuejs.org/guide/quick-start
• Vite 公式ドキュメント「サーバーオプション」 https://ja.vite.dev/config/server-options.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。