fix(create): make create-vinext-app work with npm and npx

[james-elicx]

Summary

• split the importable create-vinext-app API from its executable CLI entry point
• point the package bin at an unconditional CLI runner so npx .bin symlinks execute correctly
• exercise the packed package directly through npx in both Cloudflare scaffold workflows
• publish the @vinext/cloudflare vinext peer from workspace:^ so matching prereleases satisfy npm
• materialize workspace dependencies relative to each local package in the Next.js deploy harness

Root causes

The published creator only called its CLI when import.meta.url exactly matched process.argv[1]. npx launches package binaries through a node_modules/.bin symlink, while Node resolves import.meta.url to the real package file, so the comparison failed and the process exited successfully without doing anything.

Separately, @vinext/cloudflare published vinext >=0.0.0. npm semver excludes prereleases from that range, so an app explicitly using vinext 1.0.0-beta.x failed peer resolution. The workspace:^ source range is rewritten during packing to the matching prerelease range, currently ^1.0.0-beta.1, and will become ^1.0.0 for a stable release.

Validation

• vp test run tests/create-vinext-app.test.ts tests/init.test.ts tests/deploy.test.ts tests/e2e-deploy-script.test.ts
• 428 focused tests passed
• vp run create-vinext-app#build
• vp check
• packed create-vinext-app and scaffolded Node and Cloudflare projects through npx
• packed vinext and @vinext/cloudflare and confirmed npm resolves both beta.1 tarballs without ERESOLVE
• confirmed the packed Cloudflare peer is ^1.0.0-beta.1
• independent sub-agent reviews: NO FINDINGS
• replacement Check, create-vinext-app Cloudflare build, and all unit shards passed

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@vinext/cloudflare@2618

npm i https://pkg.pr.new/create-vinext-app@2618

npm i https://pkg.pr.new/@vinext/types@2618

npm i https://pkg.pr.new/vinext@2618

commit: ada84a9

[github-actions]

Example	Preview	Production	Original
app-router-cloudflare	preview	production
pages-router-cloudflare	preview	production
app-router-playground	preview	production	original
realworld-api-rest	preview	production
nextra-docs-template	preview	production
benchmarks	preview	production
hackernews	preview	production	original
workers-cache	preview	production
web	preview	production

[github-actions]

Performance benchmarks

Compared ada84a9 against base de94652 using alternating same-runner rounds. Next.js was unchanged and skipped.

0 improved · 0 regressed · 6 within ±1.5%

Scenario	Framework	Baseline	Current	Change
Client bundle size (gzip)	vinext	126.7 KB	126.7 KB	⚫ -0.0%
Client entry size (gzip)	vinext	120.6 KB	120.6 KB	⚫ -0.0%
Dev server cold start	vinext	2.67 s	2.66 s	⚫ -0.5%
Production build time	vinext	2.80 s	2.79 s	⚫ -0.4%
RSC entry closure size (gzip)	vinext	98.8 KB	98.8 KB	⚫ -0.0%
Server bundle size (gzip)	vinext	165.6 KB	165.6 KB	⚫ -0.0%

View detailed results and traces

_{🟢 improvement · 🔴 regression · ⚫ change below 1.5% · paired base/head}

[james-elicx]

/bonk review for issues

[ask-bonk]

APIError: Function tools with reasoning_effort are not supported for gpt-5.5 in /v1/chat/completions. To use function tools, use /v1/responses or set reasoning_effort to 'none'.

github run

[ask-bonk]

@james-elicx Bonk workflow failed. Check the logs for details.

View workflow run · To retry, trigger Bonk again.

[james-elicx]

/bigbonk review for issues

[ask-bonk]

Both workflows are consistent. The index.js no longer self-invokes (0 matches for process.argv[1]), so importing it as a library has no side effects — this is the correct fix.

Review Summary

I've completed a thorough review of PR #2618. No blocking issues found. The changes are correct, well-tested, and match Next.js/npm semantics.

What I verified

1. The npx fix (core change) — correct

• src/cli.ts is a new dedicated executable entry with #!/usr/bin/env node; bin now points at dist/cli.js.
• Built dist/cli.js correctly has the shebang and imports runCreateVinextAppCli from ./index.js.
• dist/index.js no longer has the fragile import.meta.url === process.argv[1] self-invocation guard (0 matches confirmed). This was the actual root cause: npx runs binaries through a .bin symlink, so that comparison always failed and the process exited silently. Splitting the CLI into an unconditional runner is the right fix and removes side effects from the library import.

2. The @vinext/cloudflare peer range — correct

• vinext: workspace:^ is rewritten by the packer to ^1.0.0-beta.1 in the published tarball (I packed it and confirmed). This is prerelease-inclusive, fixing the ERESOLVE failure that the old >=0.0.0 caused (npm excludes prereleases from >= ranges). It will become ^1.0.0 for stable, as the body states.

3. The e2e-deploy.sh refactor — correct

• workspaceDependencySpecFor now takes fromPackageDir and computes path.relative per-package with a || '.' self-guard. Since all three .vinext-local-* dirs are siblings under cwd, the cloudflare peer materializes to file:../.vinext-local-package, verified by the new test.

4. CI workflow changes — correct and consistent

• Both ci.yml and create-vinext-app-cloudflare-deploy.yml now use npx --yes --package <tgz> create-vinext-app, exercising the real npx path the fix addresses. The create-vinext-app-*.tgz glob is unambiguous against the sibling vinext-*.tgz / vinext-types-*.tgz / vinext-cloudflare-*.tgz tarballs.

Verification run

• vp test run on all 3 changed test files: 313 tests + 6 e2e-script tests passed.
• vp check on all changed source/test files: format, lint, and types clean.

Minor observations (non-blocking, no action required)

• The --package "${{ runner.temp }}"/create-vinext-app-*.tgz relies on the shell (inside the folded YAML scalar) expanding to exactly one file. This is safe today given the naming, but if a future package were named with a create-vinext-app- prefix the glob could become ambiguous. Not worth changing now.

The PR does what it claims, fixes both root causes at the correct layer, and has adequate regression coverage.

github run