Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

CLI Commands and npm Scripts

Learn the Vite command line - vite, vite build, vite preview, optimize - plus useful flags such as --port, --host, --mode and --config, and how npm scripts wrap them.

Vite ships one executable, vite, with a handful of commands. You rarely type them directly. They live behind npm scripts such as npm run dev. Knowing what each command and flag does makes it much easier to read other people's package.json, to debug, and to deploy.

Vite is not installed on this site, so command lines are read-only. The runnable examples are small Node.js programs that parse flags the way a CLI does, which is a useful skill when you write your own scripts.

The four commands

Terminal
vite                # start the dev server (aliases: vite dev, vite serve)
vite build          # create a production build in dist/
vite preview        # serve the built dist/ folder locally
vite optimize       # pre-bundle dependencies manually (rarely needed)

vite (the dev server)

Starts the development server with HMR. You pass an optional root folder: vite ./examples serves that directory instead of the current one. Press h then Enter in the terminal for a keyboard-shortcut menu: r restarts the server, u shows the URL, o opens the browser, c clears the screen and q quits.

vite build

Runs the production pipeline and writes the result to dist/. It always uses mode=production unless you override it. Output includes hashed JavaScript and CSS files and a copy of everything in public/. See the Build and Optimization chapter for what it does in detail.

vite preview

Starts a small static server that serves dist/. It exists to check the build locally before you deploy. It is not a production server: it is not hardened and has no clustering. Default port is 4173.

vite optimize

Triggers dependency pre-bundling without starting the server. Normally Vite does that automatically; you only use this to debug (see Dependency Pre-Bundling).

npm scripts

The scaffolded package.json wires them up:

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

npm run dev looks in node_modules/.bin, finds vite, and runs it. That is why vite is not on your global PATH and npx vite also works. With TypeScript, many teams add a type check before building:

JSON
{
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "preview": "vite preview",
    "typecheck": "tsc --noEmit"
  }
}

If tsc fails, && stops and no build is produced.

To pass an extra flag through npm, add -- first:

Terminal
npm run dev -- --port 3000
npm run build -- --mode staging

pnpm, Yarn and Bun pass flags without the --. This stand-in shows what npm does: it takes the script text and appends the extra arguments.

Node.js Stand-in: how npm run appends arguments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that with tsc --noEmit && vite build, the appended --mode staging lands on vite build, which is usually what you want.

Flags you will use

Flag Applies to Meaning
--port <n> dev, preview Port number (default 5173 dev, 4173 preview)
--host [addr] dev, preview Listen on a network address; bare --host means all interfaces
--open [path] dev, preview Open the browser on start
--strictPort dev, preview Fail instead of choosing another port if it is busy
--mode <name> all Set the mode (selects .env.<mode> files)
--config <file> / -c all Use a different config file
--base <path> all Public base path for deployment under a sub-folder
--outDir <dir> build Output folder
--sourcemap build Emit source maps
--minify <esbuild|terser|false> build Choose the minifier
--watch build Rebuild when sources change
--force dev Ignore the dependency cache and re-bundle
--debug [feat] / -d all Print debug logs
--logLevel <level> all info, warn, error or silent
--clearScreen false all Keep earlier terminal output

A few real-life examples:

Terminal
vite --host --port 3000        # test on a phone on the same Wi-Fi
vite build --base /docs/       # app will be served under /docs/
vite build --mode staging      # reads .env.staging, sets import.meta.env.MODE
vite --config vite.admin.config.js
vite preview --port 8080 --open

The --host flag and phones

By default Vite listens on localhost, so only your own computer can open the page. Add --host and the terminal prints a Network URL like http://192.168.1.20:5173/. Open that on a phone connected to the same Wi-Fi to test touch behaviour. Be careful on public Wi-Fi: anyone on the network can reach your dev server.

Reading flags like a CLI

Vite uses a flag parser much like Node's built-in parseArgs. This runnable example shows how a command line becomes a config object. It is a stand-in that illustrates the idea, not Vite's source.

Node.js Stand-in: parsing a vite command line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the default mode: development for the dev server and production for the build. Modes and Environment Variables explains how the mode selects .env files.

Chaining and running things together

A common need is to run a second process beside the dev server, such as an API. With npm you can use the concurrently package:

JSON
{
  "scripts": {
    "dev": "concurrently \"vite\" \"node server.js\""
  }
}

Another trick is a predeploy script that npm runs before deploy:

JSON
{
  "scripts": {
    "build": "vite build",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}

The Node API

Everything the CLI does is also available from JavaScript, which is handy for custom tools:

JavaScript
import { createServer, build, preview } from 'vite';

const server = await createServer({ server: { port: 3000 } });
await server.listen();
server.printUrls();

Use this when you need to start Vite from inside another program, for example a custom Express server in middleware mode. Most projects never need it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command serves the dist folder locally so you can check the production build?

    vite preview starts a static server for dist/. It is for local checking, not for real production hosting.
  2. 2. How do you pass --port 3000 to a script run with npm run dev?

    npm needs a bare -- to stop its own option parsing, so the remaining arguments go to the script.
  3. 3. What does the --host flag do on the dev server?

    Without --host the server listens only on localhost. With it, other devices can open the printed Network URL.
  4. 4. Which mode does vite build use by default?

    The build defaults to mode production, while the dev server defaults to development.

Summary

  • vite starts the dev server, vite build creates dist/, vite preview serves it locally, vite optimize pre-bundles dependencies.
  • npm scripts wrap these commands; pass extra flags after -- with npm.
  • Useful flags: --port, --host, --open, --strictPort, --mode, --base, --config, --force.
  • The dev server defaults to mode development and the build to production.
  • The same features are available from the Node API (createServer, build, preview).

Next: Native ES Modules in the Browser