feat: normalize all package manager execute commands (#333)

Inv1x · tannerlinsley · web-flow · commit 1bcdfb00016f · 2026-02-12T22:09:36.000-07:00
* chore: add ignoredBuiltDependencies to package.json

* feat: add getPackageManagerExecuteScript EJS helper and convert templates to EJS

Convert add-on README, env, and demo files to EJS templates so they can
use package-manager-aware commands (e.g. npx/bunx/pnpm dlx) via the new
getPackageManagerExecuteScript template helper.

* feat: normalize all package manager execute commands in translateExecuteCommand

Rename translateNpxCommand to translateExecuteCommand and extend it to
recognize all known execute-command formats (npx, bunx, pnpx, pnpm dlx,
yarn dlx, deno run npm:*). This ensures add-on commands specified in any
format are correctly translated to the user's chosen package manager.

* chore: remove ignoredBuiltDependencies like in original repo

* fix: readme files addons

---------

Co-authored-by: Tanner Linsley &lt;tannerlinsley@gmail.com&gt;
diff --git a/packages/create/src/create-app.ts b/packages/create/src/create-app.ts
@@ -6,6 +6,7 @@ import { writeConfigFileToEnvironment } from './config-file.js'
 import {
   getPackageManagerScriptCommand,
   packageManagerInstall,
+  translateExecuteCommand,
 } from './package-manager.js'
 import { createPackageJSON } from './package-json.js'
 import { createTemplateFile } from './template-file.js'
@@ -181,18 +182,19 @@ async function runCommandsAndInstallDependencies(
         addOn.phase === phase && addOn.command && addOn.command.command,
     )) {
       s.start(`Running commands for ${addOn.name}...`)
-      const cmd = formatCommand({
+      const translated = translateExecuteCommand(options.packageManager, {
         command: addOn.command!.command,
         args: addOn.command!.args || [],
       })
+      const cmd = formatCommand(translated)
       environment.startStep({
         id: 'run-commands',
         type: 'command',
         message: cmd,
       })
       await environment.execute(
-        addOn.command!.command,
-        addOn.command!.args || [],
+        translated.command,
+        translated.args,
         options.targetDir,
         { inherit: true },
       )
@@ -208,19 +210,20 @@ async function runCommandsAndInstallDependencies(
     options.starter.command.command
   ) {
     s.start(`Setting up starter ${options.starter.name}...`)
-    const cmd = formatCommand({
+    const starterTranslated = translateExecuteCommand(options.packageManager, {
       command: options.starter.command.command,
       args: options.starter.command.args || [],
     })
+    const cmd = formatCommand(starterTranslated)
     environment.startStep({
       id: 'run-starter-command',
       type: 'command',
       message: cmd,
     })
 
     await environment.execute(
-      options.starter.command.command,
-      options.starter.command.args || [],
+      starterTranslated.command,
+      starterTranslated.args,
       options.targetDir,
       { inherit: true },
     )
diff --git a/packages/create/src/frameworks.ts b/packages/create/src/frameworks.ts
@@ -72,8 +72,15 @@ export function scanAddOnDirectories(addOnsDirectories: Array<string>) {
       }
 
       let readme: string | undefined
+      let readmeIsEjs = false
       if (existsSync(resolve(addOnsBase, dir, 'README.md'))) {
         readme = readFileSync(resolve(addOnsBase, dir, 'README.md'), 'utf-8')
+      } else if (existsSync(resolve(addOnsBase, dir, 'README.md.ejs'))) {
+        readme = readFileSync(
+          resolve(addOnsBase, dir, 'README.md.ejs'),
+          'utf-8',
+        )
+        readmeIsEjs = true
       }
 
       let smallLogo: string | undefined
@@ -107,6 +114,7 @@ export function scanAddOnDirectories(addOnsDirectories: Array<string>) {
         packageAdditions,
         packageTemplate,
         readme,
+        readmeIsEjs,
         files,
         smallLogo,
         getFiles,
diff --git a/packages/create/src/frameworks/react/add-ons/better-auth/README.md.ejs b/packages/create/src/frameworks/react/add-ons/better-auth/README.md.ejs
@@ -3,7 +3,7 @@
 1. Generate and set the `BETTER_AUTH_SECRET` environment variable in your `.env.local`:
 
    ```bash
-   npx @better-auth/cli secret
+   <%- getPackageManagerExecuteScript('@better-auth/cli', ['secret']) %>
    ```
 
 2. Visit the [Better Auth documentation](https://www.better-auth.com) to unlock the full potential of authentication in your app.
@@ -28,5 +28,5 @@ export const auth = betterAuth({
 Then run migrations:
 
 ```bash
-npx @better-auth/cli migrate
+<%- getPackageManagerExecuteScript('@better-auth/cli', ['migrate']) %>
 ```
diff --git a/packages/create/src/frameworks/react/add-ons/better-auth/assets/_dot_env.local.append b/packages/create/src/frameworks/react/add-ons/better-auth/assets/_dot_env.local.append
diff --git a/packages/create/src/frameworks/react/add-ons/better-auth/assets/_dot_env.local.append.ejs b/packages/create/src/frameworks/react/add-ons/better-auth/assets/_dot_env.local.append.ejs
@@ -0,0 +1,3 @@
+# Better Auth configuration
+BETTER_AUTH_URL=http://localhost:3000
+BETTER_AUTH_SECRET= # Generate a secret key: `<%- getPackageManagerExecuteScript('@better-auth/cli', ['secret']) %>`
diff --git a/packages/create/src/frameworks/react/add-ons/convex/README.md b/packages/create/src/frameworks/react/add-ons/convex/README.md
diff --git a/packages/create/src/frameworks/react/add-ons/convex/README.md.ejs b/packages/create/src/frameworks/react/add-ons/convex/README.md.ejs
@@ -0,0 +1,4 @@
+## Setting up Convex
+
+- Set the `VITE_CONVEX_URL` and `CONVEX_DEPLOYMENT` environment variables in your `.env.local`. (Or run `<%- getPackageManagerExecuteScript('convex', ['init']) %>` to set them automatically.)
+- Run `<%- getPackageManagerExecuteScript('convex', ['dev']) %>` to start the Convex server.
diff --git a/packages/create/src/frameworks/react/add-ons/drizzle/assets/src/routes/demo/drizzle.tsx.ejs b/packages/create/src/frameworks/react/add-ons/drizzle/assets/src/routes/demo/drizzle.tsx.ejs
@@ -163,19 +163,19 @@ function DemoDrizzle() {
               <li>
                 Run:{' '}
                 <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
-                  npx drizzle-kit generate
+                  <%- getPackageManagerExecuteScript('drizzle-kit', ['generate']) %>
                 </code>
               </li>
               <li>
                 Run:{' '}
                 <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
-                  npx drizzle-kit migrate
+                  <%- getPackageManagerExecuteScript('drizzle-kit', ['migrate']) %>
                 </code>
               </li>
               <li>
                 Optional:{' '}
                 <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
-                  npx drizzle-kit studio
+                  <%- getPackageManagerExecuteScript('drizzle-kit', ['studio']) %>
                 </code>
               </li>
             </ol>
diff --git a/packages/create/src/frameworks/react/add-ons/prisma/assets/src/routes/demo/prisma.tsx.ejs b/packages/create/src/frameworks/react/add-ons/prisma/assets/src/routes/demo/prisma.tsx.ejs
@@ -162,19 +162,19 @@ function DemoPrisma() {
               <li>
                 Run:{' '}
                 <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
-                  npx prisma generate
+                  <%- getPackageManagerExecuteScript('prisma', ['generate']) %>
                 </code>
               </li>
               <li>
                 Run:{' '}
                 <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
-                  npx prisma db push
+                  <%- getPackageManagerExecuteScript('prisma', ['db', 'push']) %>
                 </code>
               </li>
               <li>
                 Optional:{' '}
                 <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
-                  npx prisma studio
+                  <%- getPackageManagerExecuteScript('prisma', ['studio']) %>
                 </code>
               </li>
             </ol>
diff --git a/packages/create/src/frameworks/react/add-ons/prisma/package.json.ejs b/packages/create/src/frameworks/react/add-ons/prisma/package.json.ejs
@@ -11,7 +11,7 @@
     "tsx": "^4.20.6"
   },
   "scripts": {<% if (addOnOption.prisma.database === 'postgres') { %>
-    "post-cta-init": "npx create-db@latest --user-agent tanstack/tsrouter",<% } %>
+    "post-cta-init": "<%- getPackageManagerExecuteScript('create-db@latest', ['--user-agent', 'tanstack/tsrouter']) %>",<% } %>
     "db:generate": "dotenv -e .env.local -- prisma generate",
     "db:push": "dotenv -e .env.local -- prisma db push",
     "db:migrate": "dotenv -e .env.local -- prisma migrate dev",
diff --git a/packages/create/src/frameworks/react/project/base/README.md.ejs b/packages/create/src/frameworks/react/project/base/README.md.ejs
@@ -52,7 +52,7 @@ This project uses [eslint](https://eslint.org/) and [prettier](https://prettier.
 ```
 <% } %>
 <% for(const addon of addOns.filter(addon => addon.readme)) { %>
-<%- addon.readme %>
+<%- addon.readmeIsEjs ? renderTemplate(addon.readme) : addon.readme %>
 <% } %>
 
 ## Routing
diff --git a/packages/create/src/frameworks/solid/add-ons/better-auth/README.md.ejs b/packages/create/src/frameworks/solid/add-ons/better-auth/README.md.ejs
@@ -3,7 +3,7 @@
 1. Generate and set the `BETTER_AUTH_SECRET` environment variable in your `.env.local`:
 
    ```bash
-   npx @better-auth/cli secret
+   <%- getPackageManagerExecuteScript('@better-auth/cli', ['secret']) %>
    ```
 
 2. Visit the [Better Auth documentation](https://www.better-auth.com) to unlock the full potential of authentication in your app.
@@ -28,5 +28,5 @@ export const auth = betterAuth({
 Then run migrations:
 
 ```bash
-npx @better-auth/cli migrate
+<%- getPackageManagerExecuteScript('@better-auth/cli', ['migrate']) %>
 ```
diff --git a/packages/create/src/frameworks/solid/add-ons/better-auth/assets/_dot_env.local.append b/packages/create/src/frameworks/solid/add-ons/better-auth/assets/_dot_env.local.append
diff --git a/packages/create/src/frameworks/solid/add-ons/better-auth/assets/_dot_env.local.append.ejs b/packages/create/src/frameworks/solid/add-ons/better-auth/assets/_dot_env.local.append.ejs
@@ -0,0 +1,3 @@
+# Better Auth configuration
+BETTER_AUTH_URL=http://localhost:3000
+BETTER_AUTH_SECRET= # Generate a secret key: `<%- getPackageManagerExecuteScript('@better-auth/cli', ['secret']) %>`
diff --git a/packages/create/src/frameworks/solid/add-ons/convex/README.md b/packages/create/src/frameworks/solid/add-ons/convex/README.md
diff --git a/packages/create/src/frameworks/solid/add-ons/convex/README.md.ejs b/packages/create/src/frameworks/solid/add-ons/convex/README.md.ejs
@@ -0,0 +1,4 @@
+## Setting up Convex
+
+- Set the `VITE_CONVEX_URL` and `CONVEX_DEPLOYMENT` environment variables in your `.env.local`. (Or run `<%- getPackageManagerExecuteScript('convex', ['init']) %>` to set them automatically.)
+- Run `<%- getPackageManagerExecuteScript('convex', ['dev']) %>` to start the Convex server.
diff --git a/packages/create/src/frameworks/solid/add-ons/solid-ui/README.md.ejs b/packages/create/src/frameworks/solid/add-ons/solid-ui/README.md.ejs
@@ -5,5 +5,5 @@ This installation of Solid-UI follows the manual instructions but was modified t
 To install the components, run the following command (this install button):
 
 ```bash
-npx solidui-cli@latest add button
+<%- getPackageManagerExecuteScript('solidui-cli@latest', ['add', 'button']) %>
 ```
diff --git a/packages/create/src/frameworks/solid/project/base/README.md.ejs b/packages/create/src/frameworks/solid/project/base/README.md.ejs
@@ -31,7 +31,7 @@ If you prefer not to use Tailwind CSS:
 4. Uninstall the packages: `<%= getPackageManagerAddScript('@tailwindcss/vite tailwindcss', true) %>`
 
 <% for(const addon of addOns.filter(addon => addon.readme)) { %>
-<%- addon.readme %>
+<%- addon.readmeIsEjs ? renderTemplate(addon.readme) : addon.readme %>
 <% } %>
 
 ## Routing
diff --git a/packages/create/src/package-manager.ts b/packages/create/src/package-manager.ts
@@ -101,6 +101,43 @@ export function packageManagerInstall(
   return environment.execute(command, commandArgs, cwd)
 }
 
+export function translateExecuteCommand(
+  packageManager: PackageManager,
+  command: { command: string; args?: Array<string> },
+): { command: string; args: Array<string> } {
+  const args = command.args || []
+  const parsed = parseExecuteCommand(command.command, args)
+  if (parsed) {
+    return getPackageManagerExecuteCommand(packageManager, parsed.pkg, parsed.args)
+  }
+  return { command: command.command, args }
+}
+
+function parseExecuteCommand(
+  command: string,
+  args: Array<string>,
+): { pkg: string; args: Array<string> } | null {
+  if (command === 'npx') {
+    const filtered = args[0] === '-y' ? args.slice(1) : args
+    const [pkg, ...rest] = filtered
+    return pkg ? { pkg, args: rest } : null
+  }
+  if (command === 'pnpx' || command === 'bunx') {
+    const filtered = command === 'bunx' && args[0] === '--bun' ? args.slice(1) : args
+    const [pkg, ...rest] = filtered
+    return pkg ? { pkg, args: rest } : null
+  }
+  if ((command === 'pnpm' || command === 'yarn') && args[0] === 'dlx') {
+    const [, pkg, ...rest] = args
+    return pkg ? { pkg, args: rest } : null
+  }
+  if (command === 'deno' && args[0] === 'run' && args[1]?.startsWith('npm:')) {
+    const pkg = args[1].slice(4)
+    return pkg ? { pkg, args: args.slice(2) } : null
+  }
+  return null
+}
+
 export function packageManagerExecute(
   environment: Environment,
   cwd: string,
diff --git a/packages/create/src/template-file.ts b/packages/create/src/template-file.ts
@@ -4,6 +4,7 @@ import { format } from 'prettier'
 
 import { formatCommand } from './utils.js'
 import {
+  getPackageManagerExecuteCommand,
   getPackageManagerInstallCommand,
   getPackageManagerScriptCommand,
 } from './package-manager.js'
@@ -70,6 +71,14 @@ export function createTemplateFile(environment: Environment, options: Options) {
       ]),
     )
   }
+  function getPackageManagerExecuteScript(
+    pkg: string,
+    args: Array<string> = [],
+  ) {
+    return formatCommand(
+      getPackageManagerExecuteCommand(options.packageManager, pkg, args),
+    )
+  }
 
   class IgnoreFileError extends Error {
     constructor() {
@@ -135,13 +144,18 @@ export function createTemplateFile(environment: Environment, options: Options) {
 
       getPackageManagerAddScript,
       getPackageManagerRunScript,
+      getPackageManagerExecuteScript,
 
       relativePath: (path: string, stripExtension: boolean = false) =>
         relativePath(file, path, stripExtension),
 
       integrationImportContent,
       integrationImportCode,
 
+      renderTemplate: (content: string) => {
+        return render(content, templateValues)
+      },
+
       ignoreFile: () => {
         throw new IgnoreFileError()
       },
diff --git a/packages/create/src/types.ts b/packages/create/src/types.ts
@@ -120,6 +120,7 @@ export const AddOnInfoSchema = AddOnBaseSchema.extend({
   integrations: z.array(IntegrationSchema).optional(),
   phase: z.enum(['setup', 'add-on']),
   readme: z.string().optional(),
+  readmeIsEjs: z.boolean().optional(),
 })
 
 export const AddOnCompiledSchema = AddOnInfoSchema.extend({
diff --git a/packages/create/tests/package-manager.test.ts b/packages/create/tests/package-manager.test.ts
diff --git a/packages/create/tests/template-file.test.ts b/packages/create/tests/template-file.test.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Better Auth configuration`
	`2`	`+BETTER_AUTH_URL=http://localhost:3000`
	`3`	+BETTER_AUTH_SECRET= # Generate a secret key: `<%- getPackageManagerExecuteScript('@better-auth/cli', ['secret']) %>`