Understanding Vite, npm, package.json, and Composer: A Guide for PHP Developers

If you’ve worked with modern PHP frameworks like Leaf or Laravel, you might have come across messages like:

Vite detected → starting Vite server concurrently

Vite detected → starting Vite server concurrently

Or seen files like package.json alongside your familiar composer.json. This can be confusing if you’re used to Composer and PHP but are new to the modern frontend ecosystem. Let’s break it down.

What is npm?

npm stands for Node Package Manager. It’s the standard package manager for JavaScript and frontend assets like JS frameworks and CSS tools.

Key points:

• Manages JS and CSS packages (react, vue, tailwindcss, vite, etc.)
• Uses package.json to list required packages and versions
• Works independently from PHP / Composer
• Comes bundled with Node.js, so you need Node installed to use npm

Think of npm as the Composer of the JavaScript world.

What is package.json?

package.json is the configuration file for npm. It serves a role similar to composer.json in PHP.

It tells npm:

• What packages your project needs (dependencies)
• What dev tools your project uses (devDependencies)
• Scripts you can run (npm run dev, npm run build)
• Metadata like project name and version

Example:

{
  "name": "my-custom-mvc",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  },
  "dependencies": {
    "react": "^18.2.0"
  },
  "devDependencies": {
    "vite": "^4.0.0",
    "tailwindcss": "^3.3.0"
  }
}

{
  "name": "my-custom-mvc",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  },
  "dependencies": {
    "react": "^18.2.0"
  },
  "devDependencies": {
    "vite": "^4.0.0",
    "tailwindcss": "^3.3.0"
  }
}

• dependencies → required at runtime (like PHP packages in composer.json)
• devDependencies → only used during development or build (like PHPUnit in PHP)

What is Vite?

Vite (pronounced “veet”) is a modern frontend build tool and dev server.

Its main features:

• Fast development server with hot module replacement (HMR)
• Compiles and serves modern JS, TypeScript, JSX, Vue, or Svelte files
• Production build → minifies and optimizes assets
• Installed and managed via npm (npm install --save-dev vite)

Think of it as both a npm package and a server that helps your frontend development be faster and more efficient.

Composer vs npm: Key Differences

In modern PHP apps, both Composer and npm coexist:

• Composer → handles backend PHP packages
• npm → handles frontend JS/CSS packages and build tools like Vite

Development vs Production

Development

npm run dev

npm run dev

• Starts Vite dev server
• JS/CSS are not minified
• Supports HMR (instant updates in the browser)
• Fast and debug-friendly

Production

npm run build
composer install --no-dev
npm install --production

npm run build
composer install --no-dev
npm install --production

• Compiles and minifies JS/CSS
• Generates /dist folder (static assets)
• PHP serves built files, not the dev server
• No npm run dev in production — it’s slow and unsafe

Summary

• npm = Node.js package manager for frontend assets
• package.json = like composer.json for JS, lists packages and versions
• Vite = npm package + dev server/build tool for frontend
• Composer → backend packages; npm → frontend packages
• Development: npm run dev (fast, HMR, uncompressed)
• Production: npm run build (optimized, minified assets)

Diagram (How it fits together)

Browser
  ├── Dev: http://localhost:5500 → Leaf PHP server (backend)
  └── Dev: http://localhost:5173 → Vite server (frontend, HMR)

Production
  ├── Browser → PHP server serves built assets (/dist)
  └── No Vite server running

Browser
  ├── Dev: http://localhost:5500 → Leaf PHP server (backend)
  └── Dev: http://localhost:5173 → Vite server (frontend, HMR)

Production
  ├── Browser → PHP server serves built assets (/dist)
  └── No Vite server running

Take away

Modern PHP projects have two ecosystems:

1. Backend → PHP + Composer
2. Frontend → JS/CSS + npm + Vite

• composer.json = backend dependencies
• package.json = frontend dependencies
• npm run dev = development server (fast)
• npm run build = production build (optimized)

This setup gives you fast development and optimized production assets without mixing PHP and JS responsibilities.