feat(create): Support for bun, pnpm, yarn when creating new project (#4877)

Co-authored-by: Michael Bromley <michael@michaelbromley.co.uk>

Author: grolmus

.github/workflows/publish_and_install.yml

@@ -209,3 +209,91 @@ jobs:
                 name: dashboard-test-screenshots-${{ matrix.os }}-${{ matrix.node-version }}
                 path: /tmp/dashboard-test-*.png
                 retention-days: 28
+
+    # Job 3: Verify `@vendure/create` works end-to-end when invoked via bun and pnpm.
+    # The package manager is detected from npm_config_user_agent (which bunx / pnpm dlx
+    # set), so the install step and generated project must use that manager rather than
+    # hard-coding npm (#4390).
+    test_package_managers:
+        needs: build_and_publish
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        strategy:
+            matrix:
+                include:
+                    - pm: bun
+                      scaffold: bunx @vendure/create@ci test-app --ci --log-level info
+                    - pm: pnpm
+                      scaffold: pnpm dlx @vendure/create@ci test-app --ci --log-level info
+            fail-fast: false
+        steps:
+            - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+            - name: Use Node.js 22.x
+              uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+              with:
+                  node-version: 22.x
+            - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+              with:
+                  bun-version: '1.3.10'
+            - name: Enable pnpm via corepack
+              run: |
+                  corepack enable
+                  corepack prepare pnpm@9.15.9 --activate
+                  pnpm --version
+            - name: Download Verdaccio storage
+              uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+              with:
+                  name: verdaccio-storage
+                  path: ~/verdaccio-download
+            - name: Setup Verdaccio with pre-built packages
+              run: |
+                  npm install -g verdaccio
+                  npm install -g wait-on
+                  mkdir -p $HOME/.config/verdaccio
+                  cp -v ./.github/workflows/verdaccio/config.yaml $HOME/.config/verdaccio/config.yaml
+                  cd $HOME/.config/verdaccio
+                  tar -xzf ~/verdaccio-download/verdaccio-storage.tar.gz
+                  nohup verdaccio --config $HOME/.config/verdaccio/config.yaml &
+                  wait-on http://localhost:4873
+                  # Register a Verdaccio user and capture an auth token.
+                  TOKEN_RES=$(curl -XPUT \
+                    -H "Content-type: application/json" \
+                    -d '{ "name": "test", "password": "test" }' \
+                    'http://localhost:4873/-/user/org.couchdb.user:test')
+                  TOKEN=$(echo "$TOKEN_RES" | jq -r '.token')
+                  # npm + pnpm read ~/.npmrc; bun is pointed at Verdaccio via the
+                  # npm_config_registry env var on the install step (see below).
+                  npm set registry=http://localhost:4873
+                  npm set //localhost:4873/:_authToken $TOKEN
+            - name: Install via @vendure/create using ${{ matrix.pm }}
+              # bun ignores the home-directory ~/.npmrc (oven-sh/bun#22971) and does not walk
+              # up to a parent .npmrc/bunfig, but it DOES honour the npm_config_registry env
+              # var — and so does the scaffolded project's nested install (it inherits the
+              # env). This is the one mechanism that reaches both bunx and the nested install.
+              env:
+                  CI: true
+                  npm_config_registry: http://localhost:4873/
+              run: |
+                  mkdir -p $HOME/install
+                  cd $HOME/install
+                  npm dist-tag ls @vendure/create
+                  # No --use-npm: the manager is detected from the invoking bunx / pnpm dlx.
+                  ${{ matrix.scaffold }}
+            - name: Assert the generated project used ${{ matrix.pm }}
+              run: |
+                  cd $HOME/install/test-app
+                  case "${{ matrix.pm }}" in
+                    bun) test -f bun.lock || { echo "Expected bun.lock to exist"; ls -la; exit 1; } ;;
+                    pnpm) test -f pnpm-lock.yaml || { echo "Expected pnpm-lock.yaml to exist"; ls -la; exit 1; } ;;
+                  esac
+                  echo "Lockfile for ${{ matrix.pm }} present ✓"
+            - name: Server smoke tests
+              run: |
+                  cd $HOME/install/test-app
+                  ${{ matrix.pm }} run dev &
+                  node $GITHUB_WORKSPACE/.github/workflows/scripts/smoke-tests
+            - name: Kill dev server after smoke tests
+              if: always()
+              run: |
+                  lsof -ti:3000,5173 | xargs kill 2>/dev/null || true

packages/create/package.json

@@ -19,7 +19,8 @@
         "copy-assets": "rimraf assets && ts-node ./build.ts",
         "build": "npm run copy-assets && rimraf lib && tsc -p ./tsconfig.build.json",
         "watch": "npm run copy-assets && rimraf lib && tsc -p ./tsconfig.build.json -w",
-        "lint": "eslint --fix ."
+        "lint": "eslint --fix .",
+        "test": "vitest --config vitest.config.mts --run"
     },
     "homepage": "https://www.vendure.io",
     "funding": "https://github.com/sponsors/michaelbromley",

packages/create/src/constants.ts

@@ -18,6 +18,12 @@ export const TYPESCRIPT_VERSION = '5.8.2';
  * bundler with breaking changes.
  */
 export const VITE_VERSION = '^7.3.1';
+/**
+ * `concurrently` runs the generated `dev`/`start` scripts. The major is pinned because
+ * the `<pm>:script:*` shorthand expansion (relied on by both the server scripts and the
+ * monorepo root) is a feature whose behaviour could change across majors.
+ */
+export const CONCURRENTLY_VERSION = '^9.0.0';
 
 // Port scanning
 export const PORT_SCAN_RANGE = 20;

packages/create/src/create-vendure-app.ts

@@ -36,11 +36,16 @@ import {
     checkNodeVersion,
     checkThatNpmCanReadCwd,
     cleanUpDockerResources,
+    detectPackageManager,
     downloadAndExtractStorefront,
     findAvailablePort,
     getDependencies,
+    getMonorepoRootPackageJson,
+    getPackageManagerInfo,
+    getServerPackageScripts,
     installPackages,
     isSafeToCreateProjectIn,
+    registerTemplateHelpers,
     resolvePackageRootDir,
     scaffoldAlreadyExists,
     startPostgresDatabase,
@@ -76,7 +81,7 @@ program
     .option('--verbose', 'Alias for --log-level verbose', false)
     .option(
         '--use-npm',
-        'Uses npm rather than as the default package manager. DEPRECATED: Npm is now the default',
+        'Force npm, overriding auto-detection of the package manager that invoked the CLI',
     )
     .option('--ci', 'Runs without prompts for use in CI scenarios', false)
     .option('--with-storefront', 'Include Next.js storefront (only used with --ci)', false)
@@ -96,7 +101,7 @@ void createVendureApp(
 
 export async function createVendureApp(
     name: string | undefined,
-    _useNpm: boolean, // Deprecated: npm is now the default package manager
+    _useNpm: boolean, // Legacy flag: forces npm, overriding package-manager auto-detection
     logLevel: CliLogLevel,
     isCi: boolean = false,
     withStorefront: boolean = false,
@@ -144,7 +149,12 @@ export async function createVendureApp(
     const appName = path.basename(root);
     const scaffoldExists = scaffoldAlreadyExists(root, name);
 
-    const packageManager: PackageManager = 'npm';
+    // `--use-npm` is honoured as an explicit override of auto-detection; otherwise we
+    // detect the manager that invoked the CLI (bunx/pnpm dlx/yarn dlx) so the generated
+    // project, install step and instructions all match what the user is actually using.
+    const packageManager: PackageManager = _useNpm ? 'npm' : detectPackageManager();
+    const pmInfo = getPackageManagerInfo(packageManager);
+    registerTemplateHelpers(pmInfo);
 
     if (scaffoldExists) {
         log(
@@ -196,7 +206,8 @@ export async function createVendureApp(
     }
 
     process.chdir(root);
-    if (packageManager !== 'npm' && !checkThatNpmCanReadCwd()) {
+    // This check spawns `npm` itself, so it only makes sense (and only works) for npm.
+    if (packageManager === 'npm' && !checkThatNpmCanReadCwd()) {
         process.exit(1);
     }
 
@@ -215,15 +226,23 @@ export async function createVendureApp(
         await fs.ensureDir(serverRoot);
         await fs.ensureDir(path.join(serverRoot, 'src'));
 
-        // Generate root package.json from template
-        const rootPackageTemplate = await fs.readFile(templatePath('root-package.json.hbs'), 'utf-8');
-        const rootPackageContent = Handlebars.compile(rootPackageTemplate)({ name: appName });
-        fs.writeFileSync(path.join(root, 'package.json'), rootPackageContent + os.EOL);
+        // Generate root package.json with package-manager-aware workspace scripts
+        fs.writeFileSync(
+            path.join(root, 'package.json'),
+            JSON.stringify(getMonorepoRootPackageJson(appName, pmInfo), null, 2) + os.EOL,
+        );
+
+        // pnpm does not read the package.json `workspaces` field; it requires a
+        // pnpm-workspace.yaml instead.
+        if (!pmInfo.usesPackageJsonWorkspaces) {
+            fs.writeFileSync(path.join(root, 'pnpm-workspace.yaml'), `packages:\n  - 'apps/*'\n`);
+        }
 
         // Generate root README from template
         const rootReadmeTemplate = await fs.readFile(templatePath('root-readme.hbs'), 'utf-8');
         const rootReadmeContent = Handlebars.compile(rootReadmeTemplate)({
             name: appName,
+            packageManager,
             serverPort: port,
             storefrontPort,
             superadminIdentifier: SUPER_ADMIN_USER_IDENTIFIER,
@@ -239,7 +258,7 @@ export async function createVendureApp(
             name: 'server',
             version: DEFAULT_PROJECT_VERSION,
             private: true,
-            scripts: getServerPackageScripts(),
+            scripts: getServerPackageScripts(pmInfo),
         };
         fs.writeFileSync(
             path.join(serverRoot, 'package.json'),
@@ -251,7 +270,7 @@ export async function createVendureApp(
             name: appName,
             version: DEFAULT_PROJECT_VERSION,
             private: true,
-            scripts: getServerPackageScripts(),
+            scripts: getServerPackageScripts(pmInfo),
         };
         fs.writeFileSync(
             path.join(root, 'package.json'),
@@ -302,6 +321,7 @@ export async function createVendureApp(
     // Install server dependencies
     await installDependenciesWithSpinner({
         dependencies,
+        packageManager,
         logLevel,
         cwd: serverRoot,
         spinnerMessage: `Installing ${dependencies[0]} + ${dependencies.length - 1} more dependencies`,
@@ -313,6 +333,7 @@ export async function createVendureApp(
         await installDependenciesWithSpinner({
             dependencies: devDependencies,
             isDevDependencies: true,
+            packageManager,
             logLevel,
             cwd: serverRoot,
             spinnerMessage: `Installing ${devDependencies[0]} + ${devDependencies.length - 1} more dev dependencies`,
@@ -325,6 +346,7 @@ export async function createVendureApp(
         // Install storefront dependencies
         const storefrontInstalled = await installDependenciesWithSpinner({
             dependencies: [],
+            packageManager,
             logLevel,
             cwd: storefrontRoot,
             spinnerMessage: 'Installing storefront dependencies...',
@@ -333,7 +355,9 @@ export async function createVendureApp(
             warnOnFailure: true,
         });
         if (!storefrontInstalled) {
-            log('You may need to run npm install in the storefront directory manually.', { level: 'info' });
+            log(`You may need to run ${pmInfo.install} in the storefront directory manually.`, {
+                level: 'info',
+            });
         }
     }
 
@@ -511,10 +535,13 @@ export async function createVendureApp(
                 ];
                 note(quickStartInstructions.join('\n'));
 
-                const npmCommand = os.platform() === 'win32' ? 'npm.cmd' : 'npm';
+                // Run `dev` via the detected package manager. On Windows the npm/yarn/pnpm
+                // binaries are `.cmd` shims (bun ships a real `bun.exe`).
+                const pmCommand =
+                    os.platform() === 'win32' && pmInfo.name !== 'bun' ? `${pmInfo.name}.cmd` : pmInfo.name;
                 let quickStartProcess: ChildProcess | undefined;
                 try {
-                    quickStartProcess = spawn(npmCommand, ['run', 'dev'], {
+                    quickStartProcess = spawn(pmCommand, ['run', 'dev'], {
                         cwd: root,
                         stdio: 'inherit',
                     });
@@ -527,6 +554,7 @@ export async function createVendureApp(
                     displayOutro({
                         root,
                         name,
+                        packageManager,
                         superAdminCredentials,
                         includeStorefront,
                         serverPort: port,
@@ -557,6 +585,7 @@ export async function createVendureApp(
             displayOutro({
                 root,
                 name,
+                packageManager,
                 superAdminCredentials,
                 includeStorefront,
                 serverPort: port,
@@ -571,26 +600,10 @@ export async function createVendureApp(
     }
 }
 
-/**
- * Returns the standard npm scripts for the server package.json.
- */
-function getServerPackageScripts(): Record<string, string> {
-    return {
-        'dev:server': 'ts-node ./src/index.ts',
-        'dev:worker': 'ts-node ./src/index-worker.ts',
-        'dev:dashboard': 'vite --clearScreen false',
-        dev: 'concurrently --kill-others npm:dev:*',
-        build: 'tsc',
-        'build:dashboard': 'vite build',
-        'start:server': 'node ./dist/index.js',
-        'start:worker': 'node ./dist/index-worker.js',
-        start: 'concurrently npm:start:*',
-    };
-}
-
 interface InstallDependenciesOptions {
     dependencies: string[];
     isDevDependencies?: boolean;
+    packageManager: PackageManager;
     logLevel: CliLogLevel;
     cwd: string;
     spinnerMessage: string;
@@ -607,6 +620,7 @@ async function installDependenciesWithSpinner(installOptions: InstallDependencie
     const {
         dependencies,
         isDevDependencies = false,
+        packageManager,
         logLevel,
         cwd,
         spinnerMessage,
@@ -619,7 +633,7 @@ async function installDependenciesWithSpinner(installOptions: InstallDependencie
     installSpinner.start(spinnerMessage);
 
     try {
-        await installPackages({ dependencies, isDevDependencies, logLevel, cwd });
+        await installPackages({ dependencies, isDevDependencies, packageManager, logLevel, cwd });
         installSpinner.stop(successMessage);
         return true;
     } catch (e) {
@@ -636,6 +650,7 @@ async function installDependenciesWithSpinner(installOptions: InstallDependencie
 interface OutroOptions {
     root: string;
     name: string;
+    packageManager: PackageManager;
     superAdminCredentials?: { identifier: string; password: string };
     includeStorefront?: boolean;
     serverPort?: number;
@@ -647,12 +662,13 @@ function displayOutro(outroOptions: OutroOptions) {
     const {
         root,
         name,
+        packageManager,
         superAdminCredentials,
         includeStorefront,
         serverPort = SERVER_PORT,
         storefrontPort = STOREFRONT_PORT,
     } = outroOptions;
-    const startCommand = 'npm run dev';
+    const startCommand = `${getPackageManagerInfo(packageManager).runScript} dev`;
     const identifier = superAdminCredentials?.identifier ?? SUPER_ADMIN_USER_IDENTIFIER;
     const password = superAdminCredentials?.password ?? SUPER_ADMIN_USER_PASSWORD;
 

packages/create/src/gather-user-responses.ts

@@ -300,6 +300,9 @@ async function generateSources(
         cookieSecret: randomBytes(16).toString('base64url'),
         port,
         isMonorepo: answers.includeStorefront,
+        packageManager,
+        isBun: packageManager === 'bun',
+        needsCorepack: packageManager === 'pnpm' || packageManager === 'yarn',
     };
 
     async function createSourceFile(filename: string, noEscape = false): Promise<string> {