Nuxt CLI

Common errors

• nuxi: command not found

  cause The `nuxi` executable is not found in your system's PATH. This usually means it's not installed globally, or `npx` cannot locate the local installation.
  fix Ensure `nuxi` is installed as a dev dependency in your project (`npm install nuxi --save-dev`) and then use `npx nuxi <command>` or run it via a `package.json` script (e.g., `npm run dev`).

• Error: Nuxt CLI requires Node.js version ^16.10.0 || >=18.0.0. You are using Node.js v14.x.x

  cause Your current Node.js version is older than the minimum required by Nuxi.
  fix Upgrade your Node.js version to 16.10.0 or higher, or 18.0.0 or higher. Tools like NVM (Node Version Manager) can help: `nvm install 18 && nvm use 18`.

• Failed to proxy request from 'http://localhost:3000/api/data' to 'http://localhost:5000/data' because the built-in proxy server was removed.

  cause Your Nuxt project is configured to use the deprecated built-in proxy server, which was removed in Nuxi v3.30.0, leading to failed API requests.
  fix Remove any direct `proxy` configurations from your Nuxt CLI settings or `nuxt.config.ts` that relied on the internal proxy. Implement an external proxy solution (e.g., `@nuxtjs/proxy`, a custom server middleware, or a reverse proxy server).

Warnings

• breaking Nuxi v3.30.0 removed its built-in proxy server. Projects relying on this internal proxy for API forwarding or similar functionalities during development will now experience failures. Users must implement an alternative proxy solution.
  Fix: Migrate any proxy configurations to external solutions (e.g., `h3-proxy`, `@nuxtjs/proxy` module, or a dedicated reverse proxy like Nginx) or configure Nuxt's server proxy directly if applicable.
• deprecated The `nuxi module add` command has been superseded by `nuxi add` in v3.32.0. While the older command might still be recognized for compatibility, it's recommended to update your workflows to use the new, more generalized `nuxi add` command.
  Fix: Replace `nuxi module add <module-name>` with `nuxi add <module-name>` in all scripts and documentation.
• breaking Nuxi has strict Node.js engine requirements: `^16.10.0` or `>=18.0.0`. Running Nuxi with unsupported Node.js versions will lead to immediate errors and prevent project operations.
  Fix: Upgrade your Node.js environment to a compatible version using a Node Version Manager (e.g., `nvm install 18` and `nvm use 18`).
• gotcha In certain development scenarios, particularly in older versions, Nuxi's development server might override the `NODE_ENV` environment variable. This can lead to unexpected behavior if your application logic depends on a specific `NODE_ENV` value during development.
  Fix: Explicitly define `NODE_ENV` in your `package.json` scripts or `.env` files. Ensure you thoroughly test your application's behavior in development mode if `NODE_ENV` manipulation is critical.
• gotcha Early versions of `nuxi init` and `nuxi module add` (before v3.31.3/v3.32.0) had issues with module compatibility filtering and verbose dependency installation logs. This could lead to selecting incompatible modules or a cluttered terminal output.
  Fix: Always use the latest stable version of `nuxi` (`npx nuxi upgrade`) to benefit from improved interactive prompts, better error handling, and more refined user experience during project setup and module management.

Install

• npm install nuxi npm
• yarn add nuxi yarn
• pnpm add nuxi pnpm

Imports

• nuxi (CLI via npx)
  wrong:

  npm install -g nuxi && nuxi <command>

  correct:

  npx nuxi <command>

  The primary and recommended way to use Nuxi for ad-hoc commands is via 'npx', which uses the locally installed version or downloads it temporarily. Global installations are generally discouraged for dev tools.
• nuxi (package.json script)
  wrong:

  "scripts": { "dev": "nuxt dev" }

  correct:

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

  For consistent, project-specific execution, define Nuxi commands within your 'package.json' scripts. This ensures the version installed as a dev dependency is always used.
• runMain (programmatic)
  wrong:

  import nuxi from 'nuxi'; // No default export for a direct programmatic API

  correct:

  import { runMain } from 'nuxi/dist/shared/nuxi';
  
  async function executeNuxiCommand() {
    // Example: Programmatically run 'nuxi build ./path/to/my-project'
    await runMain(['build', './path/to/my-project']);
    console.log('Nuxt build completed programmatically.');
  }
  
  executeNuxiCommand();

  While primarily a CLI, Nuxi exposes an internal `runMain` function for advanced programmatic execution, suitable for CI/CD pipelines or custom build tools. The exact import path ('nuxi/dist/shared/nuxi') might be subject to change in future versions as it is an internal API.

Quickstart

Initializes a new Nuxt 3 project with interactive prompts, installs dependencies, and starts the development server, demonstrating the core Nuxi workflow.

# Initialize a new Nuxt 3 project in a directory named 'my-nuxt-project'.
# This command will interactively guide you through setting up project preferences
# such as package manager, TypeScript support, and common Nuxt modules.
npx nuxi init my-nuxt-project

# Navigate into your newly created project directory to continue setup.
cd my-nuxt-project

# Install the necessary project dependencies using your chosen package manager (e.g., npm, yarn, pnpm).
# This step fetches all required packages, including Nuxt itself and any modules you selected during initialization.
npm install

# Start the Nuxt development server. This command compiles your application
# and provides hot module reloading, making it easy to see changes instantly.
# Your application will typically be accessible in your web browser at http://localhost:3000.
npm run dev

# After development, you can build your application for production using:
# npm run build