feat: add create-vinext-app scaffolding CLI #406
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,5 +6,9 @@ | |
| "semi": true, | ||
| "singleQuote": false, | ||
| "trailingComma": "all", | ||
| "ignorePatterns": [ | ||
| "tests/fixtures/ecosystem/**", | ||
| "examples/**", | ||
| "packages/create-vinext-app/templates/**" | ||
| ] | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,8 @@ | ||
| { | ||
| "ignorePatterns": [ | ||
| "fixtures/ecosystem/**", | ||
| "tests/fixtures/ecosystem/**", | ||
| "examples/**", | ||
| "packages/create-vinext-app/templates/**" | ||
| ] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -26,6 +26,8 @@ pnpm run lint # oxlint | |
| pnpm run fmt # oxfmt (format) | ||
| pnpm run fmt:check # oxfmt (check only, no writes) | ||
| pnpm run build # Build the vinext package | ||
| pnpm --filter create-vinext-app test # create-vinext-app tests | ||
| pnpm --filter create-vinext-app build # Build the CLI | ||
| ``` | ||
|
|
||
| ### Project Structure | ||
|
|
@@ -39,6 +41,11 @@ packages/vinext/src/ | |
| server/ # SSR handlers, ISR, middleware | ||
| cloudflare/ # KV cache handler | ||
|
|
||
| packages/create-vinext-app/ | ||
| src/ # CLI source | ||
| templates/ # App Router & Pages Router scaffolding templates | ||
| tests/ # Unit, integration, e2e tests | ||
|
|
||
| tests/ | ||
| *.test.ts # Vitest tests | ||
| fixtures/ # Test apps (pages-basic, app-basic, etc.) | ||
|
|
@@ -49,14 +56,16 @@ examples/ # User-facing demo apps | |
|
|
||
| ### Key Files | ||
|
|
||
| | File | Purpose | | ||
| | -------------------------------------------- | ------------------------------------------------------------------ | | ||
| | `index.ts` | Vite plugin — resolves `next/*` imports, generates virtual modules | | ||
| | `shims/*.ts` | Reimplementations of `next/link`, `next/navigation`, etc. | | ||
| | `server/dev-server.ts` | Pages Router SSR handler | | ||
| | `entries/app-rsc-entry.ts` | App Router RSC entry generator | | ||
| | `routing/pages-router.ts` | Scans `pages/` directory | | ||
| | `routing/app-router.ts` | Scans `app/` directory | | ||
| | `packages/create-vinext-app/src/index.ts` | CLI entry point for `npm create vinext-app` | | ||
| | `packages/create-vinext-app/src/scaffold.ts` | Template copying and variable substitution | | ||
|
|
||
| --- | ||
|
|
||
|
|
@@ -119,15 +128,16 @@ pnpm test -t "middleware" | |
|
|
||
| **Which test files to run** depends on what you changed: | ||
|
|
||
| | If you changed... | Run these tests | | ||
| | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | | ||
| | A shim (`shims/*.ts`) | `tests/shims.test.ts` + the specific shim test (e.g., `tests/link.test.ts`) | | ||
| | Routing (`routing/*.ts`) | `tests/routing.test.ts`, `tests/route-sorting.test.ts` | | ||
| | App Router server (`entries/app-rsc-entry.ts`) | `tests/app-router.test.ts`, `tests/features.test.ts` | | ||
| | Pages Router server (`server/dev-server.ts`) | `tests/pages-router.test.ts` | | ||
| | Caching/ISR | `tests/isr-cache.test.ts`, `tests/fetch-cache.test.ts`, `tests/kv-cache-handler.test.ts` | | ||
| | Build/deploy | `tests/deploy.test.ts`, `tests/build-optimization.test.ts` | | ||
| | Next.js compat features | `tests/nextjs-compat/` (the relevant file) | | ||
| | create-vinext-app (`packages/create-vinext-app/`) | `pnpm --filter create-vinext-app test` | | ||
|
|
||
| **Let CI run the full suite.** The full `pnpm test` and all 5 Playwright E2E projects run in CI on every PR. You do not need to run the full suite locally before pushing. CI will catch any cross-cutting regressions. | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -31,6 +31,23 @@ For browser-level debugging (verifying rendered output, client-side navigation, | |
|
|
||
| Check the [open issues](https://github.com/cloudflare/vinext/issues). If you're looking to contribute, those are a good place to start. | ||
|
|
||
| ### Working on create-vinext-app | ||
|
|
||
| The `packages/create-vinext-app/` package is a standalone CLI for scaffolding new vinext projects. | ||
|
|
||
| ```bash | ||
| # Run tests | ||
| pnpm --filter create-vinext-app test | ||
|
|
||
| # Build | ||
| pnpm --filter create-vinext-app build | ||
|
|
||
| # Test manually | ||
| node packages/create-vinext-app/dist/index.js test-app --yes --skip-install | ||
| ``` | ||
|
|
||
| Templates live in `packages/create-vinext-app/templates/`. When updating dependency versions in templates, update both `app-router/package.json.tmpl` and `pages-router/package.json.tmpl`. | ||
|
|
||
| ## Project structure | ||
|
|
||
| See `AGENTS.md` for the full project structure, key files, architecture patterns, and development workflow. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -74,11 +74,20 @@ Options: `-p / --port <port>`, `-H / --hostname <host>`, `--turbopack` (accepted | |
|
|
||
| `vinext init` options: `--port <port>` (default: 3001), `--skip-check`, `--force`. | ||
|
|
||
| ### New Project | ||
|
|
||
| ```bash | ||
| npm create vinext-app@latest | ||
| ``` | ||
|
|
||
| This scaffolds a new vinext project with Cloudflare Workers support. You'll be prompted for a project name and router type (App Router or Pages Router). | ||
|
|
||
| Options: | ||
|
|
||
| - `--template <app|pages>` — Router template (default: app) | ||
| - `--yes` / `-y` — Skip prompts | ||
| - `--skip-install` — Skip dependency installation | ||
| - `--no-git` — Skip git init | ||
|
|
||
| ### Migrating an existing Next.js project | ||
|
|
||
|
|
@@ -534,7 +543,7 @@ These are intentional exclusions: | |
| - **`next export` (legacy)** — Use `output: 'export'` in config instead. | ||
| - **Turbopack/webpack configuration** — This runs on Vite. Use Vite plugins instead of webpack loaders/plugins. | ||
| - **`next/jest`** — Use Vitest. | ||
| - **`create-next-app` scaffolding** — Replaced by `create-vinext-app` (`npm create vinext-app@latest`). | ||
| - **Bug-for-bug parity with undocumented behavior** — If it's not in the Next.js docs, we probably don't replicate it. | ||
|
|
||
| ## Known limitations | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,7 +2,7 @@ | |
| "name": "vinext-monorepo", | ||
| "private": true, | ||
| "scripts": { | ||
| "build": "pnpm --filter vinext --filter create-vinext-app run build", | ||
| "test": "vitest run", | ||
| "test:watch": "vitest", | ||
| "generate:google-fonts": "node scripts/generate-google-fonts.js", | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| { | ||
| "name": "create-vinext-app", | ||
| "version": "0.0.1", | ||
| "description": "Scaffold a new vinext project targeting Cloudflare Workers", | ||
| "keywords": [ | ||
| "cloudflare", | ||
| "create", | ||
| "next", | ||
| "scaffold", | ||
| "vinext", | ||
| "vite", | ||
| "workers" | ||
| ], | ||
| "license": "MIT", | ||
| "bin": { | ||
| "create-vinext-app": "dist/index.js" | ||
| }, | ||
| "files": [ | ||
| "dist", | ||
| "templates" | ||
| ], | ||
| "type": "module", | ||
| "scripts": { | ||
| "build": "tsc", | ||
| "pretest": "tsc", | ||
| "test": "vitest run", | ||
| "test:watch": "vitest" | ||
Divkix marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| }, | ||
| "dependencies": { | ||
| "@clack/prompts": "^0.10.0" | ||
| }, | ||
| "devDependencies": { | ||
| "typescript": "^5.8.2", | ||
| "vitest": "^3.2.1" | ||
| }, | ||
| "engines": { | ||
| "node": ">=18" | ||
| } | ||
| } | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CI passes an absolute path as the positional arg.
This feeds
${{ runner.temp }}/cva-testas the project name. The code atindex.ts:140correctly handlespath.isAbsolute()by extracting the basename. However, the resultingpackage.jsonwill have"name": "cva-test"and the worker name will be"cva-test". That's fine and works, but it's worth noting that this CI step is exercising the absolute-path code path, not the typical user flow ofcreate-vinext-app my-app.Consider adding a second test that uses a plain name (the typical user flow) to ensure both paths are covered in CI.