How the vp create Command Scaffolds New Projects from Templates in Vite Plus

The vp create command acts as a lightweight Rust CLI wrapper that delegates to a JavaScript runtime to parse template identifiers, execute scaffolding logic, and apply Vite Plus-specific configurations for generating monorepos, applications, or libraries.

The vp create command serves as the primary entry point for generating new projects in the voidzero-dev/vite-plus ecosystem. This command bridges a high-performance Rust executable with a flexible JavaScript template engine, enabling developers to scaffold projects from built-in templates, community packages, or remote GitHub repositories while maintaining consistent Vite Plus workflows.

Architecture of the vp create Command

The scaffolding process relies on a two-tier architecture where Rust handles CLI entry and process management while JavaScript executes the template logic.

The Rust CLI Facade

In crates/vite_global_cli/src/commands/create.rs, the command defines an execute function that immediately delegates responsibility without implementing template logic directly. The function forwards the request to the delegator:

super::delegate::execute(cwd, "create", args).await

The delegate.rs module constructs the full argument vector and invokes JsExecutor::delegate_to_local_cli, which determines whether to use a local vite-plus installation or fall back to global scripts. This delegation pattern ensures the Rust side remains a thin, maintainable wrapper.

JavaScript Runtime Execution

The js_executor.rs file manages the managed Node.js runtime through functions like run_js_entry and resolve_local_vite_plus. When executing, the resolver searches for dist/bin.js within the project's node_modules/vite-plus directory. If no local installation exists, it falls back to the global scripts directory via get_scripts_dir.

The executor guarantees consistency by setting environment variables such as VITE_PLUS_CLI_BIN and modifying PATH before spawning the process. Once prepared, the executor runs the bundled dist/bin.js script, which contains the actual template orchestration logic.

Template Resolution and Scaffolding Logic

Inside the JavaScript runtime, the create command parses template identifiers and maps them to executable generators. The system supports multiple template sources:

• Built-in templates: Shorthands like vite:monorepo, vite:library, or vite:application
• Community packages: Resolved from npm registries using shorthand names like @tanstack/start
• Local paths: Absolute or relative directories containing custom templates
• Remote repositories: GitHub URLs such as https://github.com/user/my-template

The JavaScript implementation handles installation of the template package (when necessary), execution of the generator script, and post-processing steps. After the template finishes, Vite Plus applies additional configurations based on CLI flags, such as installing pre-commit hooks with --hooks or configuring the package manager with --agent.

Practical Usage Examples

The vp create command accepts template identifiers and forwards additional arguments after -- directly to the template's own CLI.

Create a monorepo using the built-in template:

vp create vite:monorepo

Scaffold a React application with TypeScript by forwarding arguments to the underlying Vite generator:

vp create vite -- --template react-ts

Use a community starter from npm:

vp create @tanstack/start

Clone and execute a remote template from GitHub:

vp create https://github.com/user/my-template --directory ./my-project

Run in headless mode for CI/CD environments, specifying the target directory and package manager:

vp create vite:application --no-interactive --directory ./app --agent pnpm

Generate a library with automatic pre-commit hook installation:

vp create vite:library --hooks

Summary

• The vp create command in voidzero-dev/vite-plus uses a Rust shim located at crates/vite_global_cli/src/commands/create.rs to handle CLI entry and process delegation.
• The Rust js_executor.rs module manages Node.js runtime resolution and executes the bundled dist/bin.js script, setting environment variables like VITE_PLUS_CLI_BIN.
• Template resolution occurs in JavaScript, supporting built-in shorthands, npm packages, local paths, and GitHub URLs.
• Extra arguments after -- pass through directly to the template's generator, enabling full access to underlying tools like create-vite or create-next-app.
• Vite Plus-specific flags including --directory, --agent, --hooks, and --no-interactive customize the scaffolding process after the template executes.

Frequently Asked Questions

What template sources does the vp create command support?

The command accepts five template identifier types: built-in Vite Plus shorthands (e.g., vite:monorepo), community npm packages (e.g., @tanstack/start), full package names, absolute or relative local file paths, and remote GitHub URLs. The JavaScript resolver in dist/bin.js automatically detects the source type and handles cloning, installation, or local execution accordingly.

How does vp create handle extra arguments passed to templates?

Any arguments placed after a double hyphen (--) forward directly to the template's underlying CLI. For example, vp create vite -- --template react-ts passes --template react-ts to the create-vite generator, allowing full access to template-specific options without requiring Vite Plus to implement parsers for every possible generator flag.

Where is the actual scaffolding logic implemented?

While the Rust files create.rs and delegate.rs handle CLI entry and process spawning, the actual file copying and project generation occurs in the bundled dist/bin.js script. This JavaScript file resolves the template identifier, installs dependencies if needed, and executes the generator. Post-processing steps like adding .vscode settings or configuring husky hooks also run in this JavaScript layer.

Can vp create run in non-interactive environments?

Yes. The --no-interactive flag disables prompts, making the command suitable for CI/CD pipelines. When combined with --directory to specify the output path and --agent to define the package manager, vp create can scaffold projects headlessly without user input, returning appropriate exit codes for automation scripts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}