DOCSEARCHbyAlgolia
Submit Docs

Vite+ Documentation

repository·main·Indexed 26 days ago

https://github.com/voidzero-dev/vite-plus

A unified web development toolchain integrating Vite, Vitest, Oxlint, Oxfmt, and Rolldown into a single CLI (`vp`). It simplifies the development lifecycle through a single `vite.config.ts` for managing runtimes, package managers, linting, testing, and building. Includes specialized tools like `vite_install` for automated package management and `vite_static_config` for extracting configuration without a Node.js runtime.

Tokens
128.3K
Snippets
290
Records
699
Agent score
86%

What's inside Vite+

  1. Overview of Interactive CLI Snapshot Testing

    main

    The new snapshot testing solution replaces the legacy steps.json/snap.txt system with a PTY-backed (Pseudo-Terminal) runner. It uses a vt100 screen emulator to run CLI commands in a real terminal environment, allowing for the testing of interactive elements like prompts, pickers, spinners, and watch modes.

    Key features include:

    • Scripted Interactions: Test cases can send keystrokes (arrows, enter, ctrl-c, etc.) and synchronize on specific render milestones.
    • Markdown Snapshots: Results are stored as Markdown files containing rendered terminal screens.
    • Real Assertions: Unlike the old runner, mismatches trigger a test failure with a unified diff.
    • Process Isolation: Each test case runs with its own VP_HOME, cleared environment, and controlled PATH to prevent cross-case interference.

  2. Overview of the vp dlx command

    main

    The vp dlx command provides a unified interface for remote package execution across pnpm, npm, yarn, and bun. It automatically detects the project's package manager to ensure a consistent experience.

    Key features include:

    • Unified Interface: Works across all major package managers.
    • Intelligent Fallback: Handles yarn@1 automatically.
    • Pass-through: Supports passing advanced options to the target package.
    • Shell Mode: Enables execution of complex commands.
    • Silent Mode: Optimized for CI/CD and scripting.
    • Version Specifiers: Supports versioning for reproducible runs.
    • Multiple Package Support: Can handle multiple packages in a single execution.

  3. Understand the Vite+ unified workflow

    main

    Vite+ unifies the modern web development toolchain into a single package, replacing the need to manually manage separate runtimes, package managers, dev servers, linters, and bundlers. Instead of managing multiple configuration files and tools, you use a consistent set of CLI commands to interact with the integrated toolchain.

    Core Workflow Commands:

    • vp dev: Starts the development server.
    • vp check: Runs code quality checks (formatting, linting, and type-checking) in a single pass.
    • vp test: Executes tests.
    • vp build: Performs application builds.

  4. Understand Vite+ CLI Output Branding and Conventions

    main

    Vite+ standardizes terminal output to provide a consistent experience across its tools.

    Branding

    • Dev Server: Displays VITE+ v<version> in the banner.
    • Build: Displays vite+ v<version> building ....
    • Version Information: The banner shows only the VITE+ version. For detailed version information (including the underlying Vite version), use the --version flag.

    Log Prefixes

    All CLI prefixes are lowercase and bolded to match Rust compiler conventions:

    • info:
    • warn:
    • error:
    • note:
    • success:

    Sub-tool Banners

    When spawning sub-tools like vitest, oxlint, or oxfmt, Vite+ prints a single leading line to identify the context: vite+ v0.3.0 — <command>

    Note: Banners are automatically skipped when output is piped (e.g., vp dev | cat).

    Verification Commands

    You can manually verify the output branding using these commands:

    • vp dev: Check for VITE+ v<version> banner.
    • vp build: Check for vite+ v<version> build banner.
    • vp upgrade --check: Check for info: checking for updates....
    • vp env doctor: Check for consistent ✓/✗/⚠ symbols.
    • vpx: Check for error: vpx requires a command to run (when no args provided).

  5. Understand Vite+ Global CLI Command Categories

    main

    The Vite+ Global CLI is a standalone Rust binary that manages different types of tasks by delegating to Node.js, JavaScript scripts, or local packages. Commands are categorized into four types based on their execution requirements:

    1. Package Manager Commands: Wraps pnpm, npm, or yarn. The CLI uses vite_js_runtime to automatically manage Node.js to execute these.
    2. JS Script Commands: Executes JavaScript-based logic (like scaffolding or migrations) using managed Node.js.
    3. Local CLI Delegation: Forwards core development commands (like dev or build) to the local vite-plus installation in your project.
    4. Pure Rust Commands: Commands that do not require Node.js (e.g., help).

  6. Understand `devEngines` support for runtime and package manager selection

    main

    Vite+ supports the devEngines specification in package.json to manage development runtimes (Node.js) and package managers (pnpm, yarn, npm, bun). This allows you to specify required versions and how the CLI should behave if those requirements are not met.

    Supported Features

    • runtime: Supports name: "node". Other runtimes are surfaced by vp env doctor but not managed.
    • packageManager: Supports pnpm, yarn, npm, and bun (can be a single string or an array).
    • version: Supports optional versions and semver range syntax.
    • onFail: Defines behavior when a requirement isn't met. Supported values are ignore, warn, error, and download (note: full behavioral matrix for runtime is currently deferred; packageManager uses onFail to drive the detection chain fallthrough).

    Priority and Conflicts

    • Runtime Priority: devEngines.runtime takes precedence over engines.node. If they disagree, vp env doctor will issue a warning.
    • Package Manager Priority: If devEngines.packageManager is present, it drives selection. If a project has a lockfile but no packageManager field, Vite+ will auto-write to devEngines.packageManager instead of the top-level packageManager field.

  7. Understand Node.js runtime verification policy

    main

    Vite+ provides high-assurance Node.js runtime installation by verifying both integrity (SHA-256 checksums) and authenticity (PGP signatures).

    • Official Sources: When downloading from nodejs.org (the default), Vite+ requires a valid PGP signature from the SHASUMS256.txt.asc file. A missing or invalid signature results in a hard error.
    • Custom Mirrors: If using a custom mirror via VP_NODE_DIST_MIRROR that does not provide .asc files, Vite+ treats the signature as optional (required = false) and falls back to the plain SHASUMS256.txt with a warning.
    • Unofficial Builds: For unofficial-builds.nodejs.org, no signature is expected, and the plain SHASUMS256.txt is used.

  8. Understand the Vite+ CLI architecture

    main

    Vite+ has unified its global and local CLI into a single package: vite-plus. The CLI operates in two modes depending on the command being executed:

    1. Package Manager Commands (Rust-based): Commands like install, add, remove, update, dedupe, outdated, why, info, link, unlink, dlx, and pm are handled directly by the Rust vp binary using the vite_pm_cli crate. These interact with your project's package manager (pnpm, npm, yarn, or bun).

    2. Task and Utility Commands (JavaScript/NAPI-based):

      • Project Tasks: Commands like build, test, lint, fmt, run, vite, and doc are routed through the unified bin.ts entry point and executed via NAPI bindings.
      • Global Utilities: Commands like create, migrate, and --version (or -V) are handled by bundled JavaScript modules in dist/global/.

    The vp binary automatically attempts to resolve a local installation of vite-plus in your project directory using oxc_resolver. If no local installation is found, it falls back to the global installation located in ~/.vite-plus/.

  10. Manage Node.js versions with `vp env`

    main

    The vp env command manages Node.js versions both globally and on a per-project basis. It uses shims for node, npm, and related tools to automatically resolve the correct version based on your project configuration.

    Version Resolution Priority:

    1. .node-version file (current or parent directories).
    2. devEngines.runtime in package.json (the devEngines standard).
    3. engines.node in package.json.
    4. The global default (set via vp env default) or the latest LTS.

    Managed vs. System-First Mode:

    • Managed Mode (vp env on): Enabled by default. Shims always use the Vite+-managed Node.js installation.
    • System-First Mode (vp env off): Shims prefer your system Node.js and only fall back to the Vite+-managed runtime when needed.

  11. Understand vite_static_config functionality

    main
    The vite_static_config crate provides a way to statically extract configuration from vite.config.* files without requiring a Node.js runtime (NAPI). It uses oxc_parser to parse the files and extract top-level fields that consist of pure JSON literals. This is useful for reading configurations like run in environments where executing JavaScript is not feasible.

  12. Understand Task Caching in Vite+

    main

    Vite Task automatically tracks dependencies to cache tasks run via vp run. When a task succeeds (exit code 0), Vite+ saves its terminal output and written files. On subsequent runs, it checks for changes in:

    1. Arguments: Changes to additional arguments passed to the task.
    2. Environment variables: Changes to fingerprinted environment variables.
    3. Inputs: Changes to any input files the command reads.

    If all checks match, Vite+ replays the cached output and restores files, skipping the command execution. If a cache miss occurs, Vite+ provides a reason (e.g., cache miss: 'src/utils.ts' modified, executing).