create-vanilla-vite 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,29 +1,49 @@
1
- # Changelog
2
-
3
- ## 1.2.0 - 2026-11-11
4
-
5
- - Added non-interactive scaffold options and optional Git initialization.
6
- - Added the npm/pnpm scaffold smoke-test matrix and GitHub Actions CI.
7
- - Added graceful backend shutdown and JSON error handling.
8
- - Preserved child-process colors in the combined development runner.
9
- - Made the `h` shortcut update LAN API and CORS environment settings for both workspaces.
10
- - Added a frontend backend-health control when a backend is scaffolded.
11
- - Preserved completed projects when cancelling the Git prompt and restored ignored env files from examples.
12
- - Loaded backend `.env` files with dotenv and corrected TypeScript basic-server commands.
13
- - Restricted Vite to port 5173 and added explicit Axios and icon-library selections.
14
- - Shared basic Node routing/CORS logic across layouts and added JSON Express module routes and 404s.
15
- - Defaulted dependency installation to the client and aligned pnpm build approvals with CI.
16
- - Added highlighted dependency and shortcut banners to `npm run dev` / `pnpm dev`.
17
- - Added `g` to cycle combined, side-by-side, and stacked log layouts; moved the dependency reminder out of scaffolding output.
18
- - Replaced framed log panels with headings and simple dividers.
19
- - Retained full development logs for the runner session across layout changes and app restarts.
20
- - Recorded each development session in a root `.dev.log`, cleared at startup and used to redraw alternate log layouts.
21
- - Cleaned up incomplete scaffolds on interruption and kept Vite config-shape mismatches non-fatal.
22
- - Added bounded log replay, missing-env-template fallback, and consistent specific-origin CORS variation.
23
- - Kept backend status controls development-only and documented strict-port and `--yes` update-check behavior.
24
- - Expanded smoke checks for generated feature installs, CORS variation, and both pnpm build-approval keys.
25
- - Changed the `c` development shortcut to clear the terminal and the current `.dev.log` contents.
26
- - Added stricter CLI option validation, safe scaffold cancellation, install retry guidance, and Git-worktree detection.
27
- - Added backend host binding and environment resets for reliable local and network hosting; protected active development logs with a runner lock.
28
- - Expanded smoke coverage for frontend templates, fresh installs, CLI argument errors, and React lint scripts.
29
- - Added bounded CI runs and release checks, smoke validation, pnpm version alignment, and npm provenance publishing.
1
+ # Changelog
2
+
3
+ ## 1.2.2 - 2026-11-19
4
+
5
+ - Added `--install-mode=adD|plain|both` option and interactive prompt to choose dependency installation behavior.
6
+ - Added dependency synchronization when running `adD` with no package arguments.
7
+ - Fixed Express 5 server listen callback to prevent printing success message on startup errors.
8
+ - Fixed `--dry-run` in version manager to never write package files.
9
+ - Added full rollback on publish failure to restore original package files.
10
+ - Switched version manager command execution to cross-spawn for Windows compatibility and interactive 2FA/OTP publishing.
11
+ - Updated release workflow to derive dist-tag using version-manager and skip duplicate versions on npm.
12
+ - Added unit tests step to CI workflow.
13
+ - Mapped signal exit codes to 130 for SIGINT and 143 for SIGTERM in runner and dependency scripts.
14
+ - Guarded dev runner process signaling to avoid sending signals to terminated child processes.
15
+ - Excluded internal version-manager script from published package files.
16
+
17
+ ## 1.2.1 - 2026-11-12
18
+
19
+ - Made the npm install-guard smoke check account for npm versions that skip the root preinstall lifecycle on direct package installs.
20
+ - Updated CI to install dependencies from the pnpm lockfile.
21
+ - Verified all 36 scaffold smoke-test scenarios pass on Linux and Windows.
22
+
23
+ ## 1.2.0 - 2026-11-11
24
+
25
+ - Added non-interactive scaffold options and optional Git initialization.
26
+ - Added the npm/pnpm scaffold smoke-test matrix and GitHub Actions CI.
27
+ - Added graceful backend shutdown and JSON error handling.
28
+ - Preserved child-process colors in the combined development runner.
29
+ - Made the `h` shortcut update LAN API and CORS environment settings for both workspaces.
30
+ - Added a frontend backend-health control when a backend is scaffolded.
31
+ - Preserved completed projects when cancelling the Git prompt and restored ignored env files from examples.
32
+ - Loaded backend `.env` files with dotenv and corrected TypeScript basic-server commands.
33
+ - Restricted Vite to port 5173 and added explicit Axios and icon-library selections.
34
+ - Shared basic Node routing/CORS logic across layouts and added JSON Express module routes and 404s.
35
+ - Defaulted dependency installation to the client and aligned pnpm build approvals with CI.
36
+ - Added highlighted dependency and shortcut banners to `npm run dev` / `pnpm dev`.
37
+ - Added `g` to cycle combined, side-by-side, and stacked log layouts; moved the dependency reminder out of scaffolding output.
38
+ - Replaced framed log panels with headings and simple dividers.
39
+ - Retained full development logs for the runner session across layout changes and app restarts.
40
+ - Recorded each development session in a root `.dev.log`, cleared at startup and used to redraw alternate log layouts.
41
+ - Cleaned up incomplete scaffolds on interruption and kept Vite config-shape mismatches non-fatal.
42
+ - Added bounded log replay, missing-env-template fallback, and consistent specific-origin CORS variation.
43
+ - Kept backend status controls development-only and documented strict-port and `--yes` update-check behavior.
44
+ - Expanded smoke checks for generated feature installs, CORS variation, and both pnpm build-approval keys.
45
+ - Changed the `c` development shortcut to clear the terminal and the current `.dev.log` contents.
46
+ - Added stricter CLI option validation, safe scaffold cancellation, install retry guidance, and Git-worktree detection.
47
+ - Added backend host binding and environment resets for reliable local and network hosting; protected active development logs with a runner lock.
48
+ - Expanded smoke coverage for frontend templates, fresh installs, CLI argument errors, and React lint scripts.
49
+ - Added bounded CI runs and release checks, smoke validation, pnpm version alignment, and npm provenance publishing.
package/README.md CHANGED
@@ -1,195 +1,302 @@
1
- # Vanilla Vite
2
-
3
- Create a Vite app with the official interactive setup. Choose React or any other offered template, and optionally add a Node.js or Express backend in the same npm or pnpm workspace.
4
-
5
- [![npm version](https://img.shields.io/npm/v/create-vanilla-vite)](https://www.npmjs.com/package/create-vanilla-vite)
6
- [![npm downloads](https://img.shields.io/npm/dm/create-vanilla-vite)](https://www.npmjs.com/package/create-vanilla-vite)
7
- [![GitHub repository](https://img.shields.io/badge/GitHub-Wasib--2005%2FVanilla--Vite-181717?logo=github)](https://github.com/Wasib-2005/Vanilla-Vite)
8
-
9
- **Links:** [npm package](https://www.npmjs.com/package/create-vanilla-vite) · [GitHub repository](https://github.com/Wasib-2005/Vanilla-Vite) · [Report an issue](https://github.com/Wasib-2005/Vanilla-Vite/issues)
10
-
11
- ## Requirements
12
-
13
- - Node.js 20.6 or newer
14
- - npm or pnpm
15
-
16
- The commands below work in Windows PowerShell or Command Prompt as well as macOS and Linux terminals. pnpm commands require pnpm to be installed; npm is sufficient.
17
-
18
- ## Create a project
19
-
20
- With pnpm:
21
-
22
- ```bash
23
- pnpm create vanilla-vite@latest my-app
24
- ```
25
-
26
- With npm:
27
-
28
- ```bash
29
- npm create vanilla-vite@latest my-app
30
- ```
31
-
32
- Omit the project name to enter it when prompted:
33
-
34
- ```bash
35
- pnpm create vanilla-vite@latest
36
- # or
37
- npm create vanilla-vite@latest
38
- ```
39
-
40
- The generator starts the official `create-vite@latest` wizard in `my-app-client`. Choose **React** for a React application, then select JavaScript or TypeScript. You can instead choose any other template offered by Vite. Afterward, choose whether to install Tailwind CSS v4 and Axios. For React templates, you can also choose React Router, which adds a `MainRouter` with Home and Login pages and navigation. The router starter uses Tailwind utility classes when Tailwind is selected, or a standalone stylesheet otherwise. You can also choose React Icons or `@animateicons/react`. The Yes option is preselected for each yes/no prompt, including adding a backend; choose No to skip an option. Frontend setup questions appear in cyan, and backend setup questions appear in yellow. The frontend wizard may install dependencies temporarily; the generator removes nested install files and Git metadata, configures one shared workspace, and installs all dependencies from the project root.
41
-
42
- ### Non-interactive options
43
-
44
- Use `--yes` to accept the default answers for generator prompts. It does not
45
- answer the official create-vite template questions, so include `--template` to
46
- skip those prompts as well. `--yes` also skips the npm update check. Individual
47
- options select a value and skip that option's prompt:
48
-
49
- ```bash
50
- pnpm create vanilla-vite@latest my-app --yes --template=react --backend=basic --ts --structure=simple --tailwind --pm=pnpm
51
- npm create vanilla-vite@latest my-app -- --template=react --backend=express --js --axios --icons=react-icons --router
52
- ```
53
-
54
- Available options are `--tailwind`, `--axios`, `--no-axios`, `--router`,
55
- `--no-router`, and `--icons=react-icons|animateicons|none`;
56
- `--backend=none|basic|express`; `--ts` or `--js` (these language flags apply
57
- to the optional backend only);
58
- `--structure=simple|module`; and `--pm=npm|pnpm`. `--no-tailwind` opts out of
59
- Tailwind when using `--yes`. `--template=vanilla` passes a template directly to
60
- create-vite. `--no-start` creates the project without starting its dev server.
61
- The generator offers to initialize Git and make an initial commit; use
62
- `--no-git` to skip this step.
63
-
64
- The CLI checks npm for a newer version before scaffolding. Skip this check with
65
- `--no-update-check`; it is also skipped automatically in CI. To avoid any
66
- network exposure by default, Vite binds to localhost. Pass `--host` when
67
- creating the project to make the frontend dev server available on your network:
68
-
69
- ```bash
70
- pnpm create vanilla-vite@latest my-app --host
71
- npm create vanilla-vite@latest my-app -- --host
72
- ```
73
-
74
- For npm, also forward the update-check option with `--`:
75
-
76
- ```bash
77
- npm create vanilla-vite@latest my-app -- --no-update-check
78
- ```
79
-
80
- The optional backend supports JavaScript or TypeScript, either basic Node.js or Express, and a simple or module-based folder layout. Express and the module-based layout are preselected by default; Express adds Express, CORS, and dotenv, enables JSON parsing, and provides `GET /api/health`, returning `{ "status": "ok" }`. The basic Node.js server uses dotenv to load `.env`, supports CORS, returns the same health response, and responds with JSON 404s for unknown paths. In the Express module layout, `/` and `/api/health` return JSON and unknown paths return a JSON 404. When a backend is selected, the generated frontend includes a **Check connection** button that requests `/api/health` and reports whether the backend is reachable. This works with or without React Router and is omitted for frontend-only projects. Both backend layouts create the `src/app` and `src/server` entry points. The simple layout has `routes`, `controllers`, `middleware`, and `config` folders; the module-based layout has `module`, `config`, `middleware`, and `utils` folders plus `mainRouter`. The `--default` flag selects the simple layout without prompting.
81
-
82
- Pass `--default` after the project name to use the simple backend folder layout without prompting:
83
-
84
- ```bash
85
- pnpm create vanilla-vite@latest my-app --default
86
- npm create vanilla-vite@latest my-app -- --default
87
- ```
88
-
89
- The generated project structure is:
90
-
91
- ```text
92
- my-app/
93
- ├── my-app-client/ # Vite app; choose React or another Vite template
94
- ├── my-app-server/ # optional backend
95
- ├── scripts/
96
- ├── package.json
97
- └── pnpm-workspace.yaml # used by pnpm; npm uses package.json workspaces
98
- ```
99
-
100
- The frontend gets a `.env.local` file with `VITE_API_URL=http://localhost:4000` and a tracked `.env.example` template. If you choose a backend, it gets a `.env` file with `PORT=4000`, `HOST=localhost`, and `CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173`, plus its own `.env.example`. On startup, the development runner recreates either ignored local environment file from `.env.example` when it is missing. The local `.env` files are ignored by Git.
101
-
102
- ## Run the project
103
-
104
- The generator starts the development server automatically after creating the
105
- project. To start it again later, run this from the project root:
106
-
107
- ```bash
108
- pnpm dev
109
- # or
110
- npm run dev
111
- ```
112
-
113
- At startup, the runner displays the dependency commands and a highlighted shortcut panel. Only one development runner per project is supported; a second instance exits without clearing the active runner's log. Logs are combined by default. Press `g` to split client and server logs side by side with a divider, press it again to stack the logs with a horizontal divider, and once more to return to the combined view. The split layouts use headings and dividers rather than enclosing boxes. App output and runner notices are recorded in the root `.dev.log` file, which is cleared each time `dev` starts. New log lines append without clearing earlier output, including when either app restarts. Pressing `g` redraws the current view from that file. Press `r` to restart both apps, `h` to toggle network hosting, `c` to clear the terminal and empty `.dev.log`, or Ctrl+C to stop. Enabling `h` sets the client `VITE_API_URL` to the preferred LAN IPv4 address, binds the backend to `0.0.0.0`, and configures backend CORS for localhost and every detected IPv4 interface (including container bridges), then restarts both apps; disabling it restores localhost values. The selected hosting mode is kept when you later press `r`.
114
- Pass `--host` when creating a project to start with network hosting enabled.
115
- The generated Vite config enables `server.strictPort`; if port 5173 is already in
116
- use, the client process stops with a port-in-use error rather than silently
117
- switching ports.
118
-
119
- Run one workspace individually. Add `dev` to run it in development mode:
120
-
121
- ```bash
122
- pnpm client
123
- pnpm server
124
- pnpm client dev
125
- ```
126
-
127
- Or with npm:
128
-
129
- ```bash
130
- npm run client
131
- npm run server
132
- npm run client -- dev
133
- ```
134
-
135
- The server commands are only available if you chose a backend.
136
-
137
- Use the root `build` and `lint` scripts to run the matching script in every
138
- workspace that defines it:
139
-
140
- ```bash
141
- pnpm build
142
- pnpm lint
143
- # or
144
- npm run build
145
- npm run lint
146
- ```
147
-
148
- ## Add dependencies
149
-
150
- Always use one of these commands to add dependencies. The prompt lets you
151
- choose the project root, client, or server (if you created one); the client is
152
- selected by default, including when you press Esc:
153
-
154
- ```bash
155
- pnpm adD <package>
156
- pnpm add-dependency <package>
157
- npm run adD -- <package>
158
- npm run add-dependency -- <package>
159
- ```
160
-
161
- Do not use `npm install`, `npm add`, `pnpm install`, or `pnpm add` directly to
162
- add packages. They bypass the location prompt or may be blocked by the
163
- workspace install guard. The guard runs only when the package manager invokes
164
- the root `preinstall` hook; direct `npm install <package>` behavior varies by
165
- npm version and is not blocked by versions that skip that hook. A failed or
166
- aborted install can leave `node_modules` behind, causing a plain reinstall to
167
- be blocked. Use one of the `adD` commands above to add dependencies.
168
-
169
- ## Development
170
-
171
- To test from the source:
172
-
173
- ```bash
174
- git clone https://github.com/Wasib-2005/Vanilla-Vite
175
-
176
- pnpm exec node [Stored Path]/Vanilla-Vite/bin/create-template.mjs my-app
177
- # or
178
- npm exec -- node [Stored Path]/Vanilla-Vite/bin/create-template.mjs my-app
179
- ```
180
-
181
- Run the scaffold smoke matrix (npm and pnpm, JavaScript and TypeScript,
182
- frontend-only/basic Node/Express backends, with and without Tailwind) with:
183
-
184
- ```bash
185
- npm install
186
- npm run test:smoke
187
- ```
188
-
189
- Use `npm run test:smoke -- --quick` for a smaller publish-time check,
190
- `SMOKE_FILTER=<text> npm run test:smoke` to select matching cases, or
191
- `SMOKE_KEEP=1 npm run test:smoke` to keep generated test projects for inspection.
192
-
193
- ## License
194
-
195
- ISC
1
+ # Vanilla Vite
2
+
3
+ Create a Vite app with the official interactive setup. Choose React or any other offered template, and optionally add a Node.js or Express backend in the same npm or pnpm workspace.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/create-vanilla-vite)](https://www.npmjs.com/package/create-vanilla-vite)
6
+ [![npm downloads](https://img.shields.io/npm/dm/create-vanilla-vite)](https://www.npmjs.com/package/create-vanilla-vite)
7
+ [![GitHub repository](https://img.shields.io/badge/GitHub-Wasib--2005%2Fvanilla--vite-181717?logo=github)](https://github.com/Wasib-2005/vanilla-vite)
8
+
9
+ **Links:** [npm package](https://www.npmjs.com/package/create-vanilla-vite) · [GitHub repository](https://github.com/Wasib-2005/vanilla-vite) · [Report an issue](https://github.com/Wasib-2005/vanilla-vite/issues)
10
+
11
+ ## Requirements
12
+
13
+ - Node.js 20.6 or newer
14
+ - npm or pnpm
15
+
16
+ The commands below work in Windows PowerShell or Command Prompt as well as macOS and Linux terminals. pnpm commands require pnpm to be installed; npm is sufficient.
17
+
18
+ ## Create a project
19
+
20
+ With pnpm:
21
+
22
+ ```bash
23
+ pnpm create vanilla-vite@latest my-app
24
+ ```
25
+
26
+ With npm:
27
+
28
+ ```bash
29
+ npm create vanilla-vite@latest my-app
30
+ ```
31
+
32
+ Omit the project name to enter it when prompted:
33
+
34
+ ```bash
35
+ pnpm create vanilla-vite@latest
36
+ # or
37
+ npm create vanilla-vite@latest
38
+ ```
39
+
40
+ The generator starts the official `create-vite@latest` wizard in `my-app-client`. Choose **React** for a React application, then select JavaScript or TypeScript. You can instead choose any other template offered by Vite. Afterward, choose whether to install Tailwind CSS v4 and Axios. For React templates, you can also choose React Router, which adds a `MainRouter` with Home and Login pages and navigation. The router starter uses Tailwind utility classes when Tailwind is selected, or a standalone stylesheet otherwise. You can also choose React Icons or `@animateicons/react`. The Yes option is preselected for each yes/no prompt, including adding a backend; choose No to skip an option. Frontend setup questions appear in cyan, and backend setup questions appear in yellow. The frontend wizard may install dependencies temporarily; the generator removes nested install files and Git metadata, configures one shared workspace, and installs all dependencies from the project root.
41
+
42
+ ### Non-interactive options
43
+
44
+ Use `--yes` to accept the default answers for generator prompts. It does not
45
+ answer the official create-vite template questions, so include `--template` to
46
+ skip those prompts as well. `--yes` also skips the npm update check. Individual
47
+ options select a value and skip that option's prompt:
48
+
49
+ ```bash
50
+ pnpm create vanilla-vite@latest my-app --yes --template=react --backend=basic --ts --structure=simple --tailwind --pm=pnpm
51
+ npm create vanilla-vite@latest my-app -- --template=react --backend=express --js --axios --icons=react-icons --router
52
+ ```
53
+
54
+ Available options are `--tailwind`, `--axios`, `--no-axios`, `--router`,
55
+ `--no-router`, and `--icons=react-icons|animateicons|none`;
56
+ `--backend=none|basic|express`; `--ts` or `--js` (these language flags apply
57
+ to the optional backend only);
58
+ `--structure=simple|module`; `--pm=npm|pnpm`; and
59
+ `--install-mode=adD|plain|both` (controls dependency install tooling; adD is default).
60
+ `--no-tailwind` opts out of
61
+ Tailwind when using `--yes`. `--template=vanilla` passes a template directly to
62
+ create-vite. `--no-start` creates the project without starting its dev server.
63
+ The generator offers to initialize Git and make an initial commit; use
64
+ `--no-git` to skip this step.
65
+
66
+ The CLI checks npm for a newer version before scaffolding. Skip this check with
67
+ `--no-update-check`; it is also skipped automatically in CI. To avoid any
68
+ network exposure by default, Vite binds to localhost. Pass `--host` when
69
+ creating the project to make the frontend dev server available on your network:
70
+
71
+ ```bash
72
+ pnpm create vanilla-vite@latest my-app --host
73
+ npm create vanilla-vite@latest my-app -- --host
74
+ ```
75
+
76
+ For npm, also forward the update-check option with `--`:
77
+
78
+ ```bash
79
+ npm create vanilla-vite@latest my-app -- --no-update-check
80
+ ```
81
+
82
+ The optional backend supports JavaScript or TypeScript, either basic Node.js or Express, and a simple or module-based folder layout. Express and the module-based layout are preselected by default; Express adds Express, CORS, and dotenv, enables JSON parsing, and provides `GET /api/health`, returning `{ "status": "ok" }`. The basic Node.js server uses dotenv to load `.env`, supports CORS, returns the same health response, and responds with JSON 404s for unknown paths. In the Express module layout, `/` and `/api/health` return JSON and unknown paths return a JSON 404. When a backend is selected, the generated frontend includes a **Check connection** button that requests `/api/health` and reports whether the backend is reachable. This works with or without React Router and is omitted for frontend-only projects. Both backend layouts create the `src/app` and `src/server` entry points. The simple layout has `routes`, `controllers`, `middleware`, and `config` folders; the module-based layout has `module`, `config`, `middleware`, and `utils` folders plus `mainRouter`. The `--default` flag selects the simple layout without prompting.
83
+
84
+ Pass `--default` after the project name to use the simple backend folder layout without prompting:
85
+
86
+ ```bash
87
+ pnpm create vanilla-vite@latest my-app --default
88
+ npm create vanilla-vite@latest my-app -- --default
89
+ ```
90
+
91
+ The generated project structure is:
92
+
93
+ ```text
94
+ my-app/
95
+ ├── my-app-client/ # Vite app; choose React or another Vite template
96
+ ├── my-app-server/ # optional backend
97
+ ├── scripts/
98
+ ├── package.json
99
+ └── pnpm-workspace.yaml # used by pnpm; npm uses package.json workspaces
100
+ ```
101
+
102
+ The frontend gets a `.env.local` file with `VITE_API_URL=http://localhost:4000` and a tracked `.env.example` template. If you choose a backend, it gets a `.env` file with `PORT=4000`, `HOST=localhost`, and `CORS_ORIGIN=http://localhost:5173,http://127.0.0.1:5173`, plus its own `.env.example`. On startup, the development runner recreates either ignored local environment file from `.env.example` when it is missing. The local `.env` files are ignored by Git.
103
+
104
+ ## Run the project
105
+
106
+ The generator starts the development server automatically after creating the
107
+ project. To start it again later, run this from the project root:
108
+
109
+ ```bash
110
+ pnpm dev
111
+ # or
112
+ npm run dev
113
+ ```
114
+
115
+ At startup, the runner displays the dependency commands and a highlighted shortcut panel. Only one development runner per project is supported; a second instance exits without clearing the active runner's log. Logs are combined by default. Press `g` to split client and server logs side by side with a divider, press it again to stack the logs with a horizontal divider, and once more to return to the combined view. The split layouts use headings and dividers rather than enclosing boxes. App output and runner notices are recorded in the root `.dev.log` file, which is cleared each time `dev` starts. New log lines append without clearing earlier output, including when either app restarts. Pressing `g` redraws the current view from that file. Press `r` to restart both apps, `h` to toggle network hosting, `c` to clear the terminal and empty `.dev.log`, or Ctrl+C to stop. Enabling `h` sets the client `VITE_API_URL` to the preferred LAN IPv4 address, binds the backend to `0.0.0.0`, and configures backend CORS for localhost and every detected IPv4 interface (including container bridges), then restarts both apps; disabling it restores localhost values. The selected hosting mode is kept when you later press `r`.
116
+ Pass `--host` when creating a project to start with network hosting enabled.
117
+ The generated Vite config enables `server.strictPort`; if port 5173 is already in
118
+ use, the client process stops with a port-in-use error rather than silently
119
+ switching ports.
120
+
121
+ Run one workspace individually. Add `dev` to run it in development mode:
122
+
123
+ ```bash
124
+ pnpm client
125
+ pnpm server
126
+ pnpm client dev
127
+ ```
128
+
129
+ Or with npm:
130
+
131
+ ```bash
132
+ npm run client
133
+ npm run server
134
+ npm run client -- dev
135
+ ```
136
+
137
+ The server commands are only available if you chose a backend.
138
+
139
+ Use the root `build` and `lint` scripts to run the matching script in every
140
+ workspace that defines it:
141
+
142
+ ```bash
143
+ pnpm build
144
+ pnpm lint
145
+ # or
146
+ npm run build
147
+ npm run lint
148
+ ```
149
+
150
+ ## Add dependencies
151
+
152
+ During scaffolding, you can select how dependencies should be installed:
153
+
154
+ 1. **adD only (default)**: All packages should be added using `pnpm adD <package>` or `npm run adD -- <package>`. Direct root installs are blocked by the workspace install guard to prevent placing packages in the wrong location.
155
+ 2. **Plain install only**: Dependencies are installed using standard `pnpm add <package>` or `npm install <package>`. No guard is enabled and `adD` is not scaffolded.
156
+ 3. **Both**: Provides the `adD` interactive workspace picker, but also allows direct `pnpm add` / `npm install` without blocking.
157
+
158
+ When using `adD` (in `adD only` or `both` mode), the prompt lets you choose the project root, client, or server (if you created one); the client is selected by default, including when you press Esc:
159
+
160
+ ```bash
161
+ pnpm adD <package>
162
+ pnpm add-dependency <package>
163
+ npm run adD -- <package>
164
+ npm run add-dependency -- <package>
165
+ ```
166
+
167
+ To sync or install all workspace dependencies across the monorepo, run `adD` with no package arguments:
168
+
169
+ ```bash
170
+ pnpm adD
171
+ # or with npm:
172
+ npm run adD
173
+ ```
174
+
175
+ In `adD only` mode, do not use `npm install <package>`, `npm add <package>`, or `pnpm add <package>` directly to add packages. They bypass the location prompt and are blocked by the workspace install guard. A failed or aborted install can leave `node_modules` behind; running `pnpm adD` with no arguments safely syncs dependencies.
176
+
177
+ ## Development
178
+
179
+ To test from source:
180
+
181
+ ```bash
182
+ git clone https://github.com/Wasib-2005/vanilla-vite
183
+ cd vanilla-vite
184
+ pnpm install
185
+ ```
186
+
187
+ Run the generator directly:
188
+
189
+ ```bash
190
+ pnpm exec node bin/create-template.mjs my-app
191
+ # or
192
+ node bin/create-template.mjs my-app
193
+ ```
194
+
195
+ Run the scaffold smoke matrix (npm and pnpm, JavaScript and TypeScript,
196
+ frontend-only/basic Node/Express backends, with and without Tailwind) with:
197
+
198
+ ```bash
199
+ pnpm test:smoke
200
+ ```
201
+
202
+ Use `pnpm test:smoke -- --quick` for a smaller publish-time check,
203
+ `SMOKE_FILTER=<text> pnpm test:smoke` to select matching cases, or
204
+ `SMOKE_KEEP=1 pnpm test:smoke` to keep generated test projects for inspection.
205
+
206
+ ## Version management and publishing
207
+
208
+ Vanilla-Vite includes a version management CLI to safely bump versions and publish to the npm registry.
209
+
210
+ ### With a specified version
211
+
212
+ ```bash
213
+ pnpm vpublish 1.0.5
214
+ ```
215
+
216
+ ### Interactive prompt
217
+
218
+ If invoked without arguments, the version manager compares the latest npm version and the local package version, then prompts for the target version:
219
+
220
+ ```bash
221
+ pnpm vpublish
222
+ ```
223
+
224
+ Interactive example prompt:
225
+
226
+ ```text
227
+ Vanilla-Vite Version Manager
228
+
229
+ Latest npm version: 1.2.1
230
+ Local repository version: 1.2.0
231
+
232
+ Enter the new version:
233
+ ```
234
+
235
+ ### Safety and validation checks
236
+
237
+ Before publishing, the version manager automatically performs the following safeguards:
238
+
239
+ 1. **Root execution restriction**: The CLI refuses to publish when run as root on Linux or macOS to prevent accidental privilege escalation and file permission issues. To override in automated environments, set `ALLOW_ROOT_PUBLISH=1` or pass `--allow-root`.
240
+ 2. **Repository verification**: Validates that the command runs from the root of `create-vanilla-vite`.
241
+ 3. **SemVer validation**: Enforces strict semantic versioning (e.g. `1.0.5`, `1.1.0-beta.1`). Invalid versions such as `1.0` or `hello` are rejected.
242
+ 4. **Duplicate publication prevention**: Checks the npm registry to verify the target version has not already been published.
243
+ 5. **Downgrade prevention**: Rejects versions lower than the latest published npm version (override available with `--allow-downgrade`).
244
+ 6. **Authentication check**: Verifies active npm registry credentials before running build and publish steps.
245
+ 7. **Pre-publish test verification**: Automatically executes `pnpm test:smoke -- --quick` to guarantee all critical smoke tests pass before publishing.
246
+ 8. **Prerelease tag routing**: Prerelease versions (such as `1.1.0-beta.1`, `1.1.0-rc.1`) are published with their corresponding distribution tag (`beta`, `rc`, etc.) rather than `latest`. Stable versions publish under `latest`.
247
+ 9. **Changelog verification**: Checks `CHANGELOG.md` for an entry corresponding to the target version. If an entry already exists, publishing continues automatically. If no entry exists, the CLI prompts for what to add to the changelog (or accepts `--changelog="<entry>"`).
248
+ 10. **Confirmation prompt**: Displays a complete publication summary and requires explicit confirmation before modifying files or uploading packages.
249
+
250
+ ### Non-interactive and CI usage
251
+
252
+ ```bash
253
+ pnpm vpublish 1.2.2 --yes
254
+ ```
255
+
256
+ To test the publishing process without modifying the registry:
257
+
258
+ ```bash
259
+ pnpm vpublish 1.2.2 --dry-run
260
+ ```
261
+
262
+ ## Troubleshooting
263
+
264
+ ### Installation guard blocks direct install
265
+
266
+ Direct installs in the root workspace are blocked in `adD only` mode to keep dependencies organized within individual client and server workspaces.
267
+ - Add dependencies using:
268
+ ```bash
269
+ pnpm adD <package>
270
+ # or with npm:
271
+ npm run adD -- <package>
272
+ ```
273
+ - To recover from an interrupted install or sync all workspace packages:
274
+ ```bash
275
+ pnpm adD
276
+ # or with npm:
277
+ npm run adD
278
+ # or with the allow flag:
279
+ VANILLA_VITE_ALLOW_INSTALL=1 pnpm install
280
+ ```
281
+
282
+ ### Publishing via CLI or GitHub Release
283
+
284
+ Package publishing is intended to be performed EITHER via the local CLI `pnpm vpublish` OR via a GitHub release, not both. The GitHub Actions release workflow automatically checks whether the version has already been published to the npm registry and skips the publish step if it already exists.
285
+
286
+ ### Port conflicts
287
+
288
+ - If port 5173 is in use, Vite stops with a port error due to `strictPort: true`. Free port 5173 or modify `vite.config` to use another port.
289
+ - If backend port 4000 is in use, Express logs `Port 4000 is already in use.` and exits cleanly with non-zero exit code. Change `PORT` in `[server-folder]/.env`.
290
+
291
+ ### Root execution error on publish
292
+
293
+ If you see:
294
+ ```text
295
+ Refusing to run publishing operations as root.
296
+ Publishing packages with root privileges is unsafe.
297
+ ```
298
+ Run `pnpm vpublish` as your regular user. In automated container environments that run as root, set `ALLOW_ROOT_PUBLISH=1` or pass `--allow-root`.
299
+
300
+ ## License
301
+
302
+ ISC