feat: ship npm artifacts alongside pnpm in the app template (2/3)

.github/workflows/ci.yml

@@ -164,6 +164,56 @@ jobs:
           DATABRICKS_WORKSPACE_ID: e2e-mock
           DATABRICKS_SERVING_ENDPOINT_NAME: e2e-mock
 
+  template-deploy-shape:
+    name: Template Deploy-Shape (pnpm install, build, and startup)
+    needs: detect-changes
+    if: needs.detect-changes.outputs.appkit == 'true'
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Setup JFrog npm
+        uses: ./.github/actions/setup-jfrog-npm
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 24
+          cache: 'pnpm'
+      - name: Install tooling dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Install, build, and start the pnpm template
+        run: pnpm exec tsx tools/smoke-test-template.ts --package-manager pnpm --output-dir .smoke-test/app-pnpm --run
+
+  template-deploy-shape-npm:
+    name: Template Deploy-Shape (npm install, build, and startup)
+    needs: detect-changes
+    if: needs.detect-changes.outputs.appkit == 'true'
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Setup JFrog npm
+        uses: ./.github/actions/setup-jfrog-npm
+      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 24
+          cache: 'pnpm'
+      - name: Install tooling dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Install, build, and start the npm template
+        run: pnpm exec tsx tools/smoke-test-template.ts --package-manager npm --output-dir .smoke-test/app-npm --run
+
   pr-template-artifact:
     name: PR Template Artifact
     needs: detect-changes
@@ -209,9 +259,26 @@ jobs:
       - name: Prepare template artifact
         run: pnpm exec tsx tools/prepare-template-artifact.ts
 
-      - name: Install template dependencies
+      # Regenerate both lockfiles: the prepare-template-artifact script rewrites
+      # package.json deps to file: references (local tarballs), which invalidates
+      # the committed locks. We regenerate here under the JFrog .npmrc (set up
+      # by setup-jfrog-npm), which bakes JFrog URLs into the locks; the rewrite
+      # step below fixes that to point back to public npm.
+      - name: Regenerate template lockfiles (npm and pnpm)
         working-directory: pr-template
-        run: npm install
+        run: |
+          echo "Regenerating package-lock.json..."
+          npm install
+          echo "✓ Regenerated package-lock.json and node_modules"
+          echo "Regenerating pnpm-lock.yaml (lockfile-only to skip node_modules rebuild)..."
+          # --no-frozen-lockfile allows regeneration even though the committed lock is now stale
+          # (prepare-template-artifact rewrote package.json deps to file: references).
+          # --lockfile-only skips rebuilding node_modules over npm's install above.
+          pnpm install --lockfile-only --no-frozen-lockfile
+          echo "✓ Regenerated pnpm-lock.yaml"
+
+      - name: Verify bundled SDKs in both template locks
+        run: pnpm exec tsx tools/check-template-artifact.ts pr-template
 
       # The scaffold's own vitest suite, run against the tarballs built above
       # rather than the published versions template/package.json pins. This is
@@ -224,14 +291,14 @@ jobs:
         run: npm test
 
       # npm install above runs under the JFrog .npmrc (setup-jfrog-npm), which
-      # bakes internal registry URLs into the regenerated lock. Rewrite them back
+      # bakes internal registry URLs into the regenerated locks. Rewrite them back
       # to public npm and fail-closed if any non-public registry remains, so the
       # shipped scaffold installs from npmjs.org. --allow-file permits the bundled
       # appkit/appkit-ui tarballs that prepare-template-artifact.ts pins.
-      - name: Rewrite and validate template lockfile registry
+      - name: Rewrite and validate template lockfiles registry
         run: >
-          pnpm exec tsx tools/check-template-lock-registry.ts
-          pr-template/package-lock.json --rewrite --allow-file
+          pnpm exec tsx tools/check-template-lock-registry.ts pr-template/pnpm-lock.yaml --rewrite --allow-file &&
+          pnpm exec tsx tools/check-template-lock-registry.ts pr-template/package-lock.json --rewrite --allow-file
 
       - name: Create zip artifact
         working-directory: pr-template
@@ -342,4 +409,3 @@ jobs:
     with:
       appkit-remote: ${{ github.event.pull_request.head.repo.clone_url || format('https://github.com/{0}.git', github.repository) }}
       appkit-ref: ${{ github.head_ref || github.ref_name }}
-

.gitignore

@@ -8,6 +8,9 @@ node_modules
 pr-template
 appkit-template-*.zip
 
+# Scratch dir and output produced by tools/smoke-test-template.ts
+.smoke-test
+
 coverage
 
 *.tsbuildinfo

.oxfmtrc.json

@@ -32,6 +32,7 @@
     "**/*.gen.ts",
     "**/typedoc-sidebar.ts",
     "**/template",
-    "**/appkit-types/metric-views.ts"
+    "**/appkit-types/metric-views.ts",
+    ".smoke-test"
   ]
 }

.oxlintrc.json

@@ -76,6 +76,7 @@
     "**/*.gen.ts",
     "**/typedoc-sidebar.ts",
     "**/template",
-    "**/appkit-types/metric-views.ts"
+    "**/appkit-types/metric-views.ts",
+    ".smoke-test"
   ]
 }

docs/docs/development/templates.md

@@ -24,6 +24,7 @@ Files named with a `_` prefix are renamed to `.` prefix (e.g. `_gitignore` → `
 | `.workspaceHost` | Databricks workspace URL |
 | `.profile` | Databricks CLI profile name (empty if using host-based auth) |
 | `.appDescription` | App description |
+| `.packageManager` | Selected package manager (`npm` or `pnpm`). Use `{{or .packageManager "pnpm"}}` to default to pnpm when an older CLI omits this variable. |
 | `.plugins.<name>` | Non-nil for each selected plugin, enabling conditionals |
 | `.dotEnv.content` | Generated `.env` content from plugin resources |
 | `.dotEnv.example` | Generated `.env.example` content with placeholders |

package.json

@@ -87,6 +87,7 @@
     "vite": "7.2.4",
     "vite-tsconfig-paths": "5.1.4",
     "vitest": "3.2.4",
+    "yaml": "2.8.2",
     "zod": "4.3.6"
   }
 }

template/.npmrc

@@ -0,0 +1,2 @@
+# pnpm 11 needs this to run prebuild (AppKit typegen) before build.
+enable-pre-post-scripts=true

template/README.md → template/README.md.tmpl

@@ -19,7 +19,7 @@ A Databricks App powered by [AppKit](https://developers.databricks.com/docs/appk
 
 ## Prerequisites
 
-- Node.js v22+ and npm
+- Node.js v22+ and {{or .packageManager "pnpm"}}
 - Databricks CLI (for deployment)
 - Access to a Databricks workspace
 
@@ -99,15 +99,15 @@ databricks bundle deploy --profile production
 ### Install Dependencies
 
 ```bash
-npm install
+{{or .packageManager "pnpm"}} install
 ```
 
 ### Development
 
 Run the app in development mode with hot reload:
 
 ```bash
-npm run dev
+{{or .packageManager "pnpm"}} run dev
 ```
 
 The app will be available at the URL shown in the console output.
@@ -117,7 +117,7 @@ The app will be available at the URL shown in the console output.
 Build both client and server for production:
 
 ```bash
-npm run build
+{{or .packageManager "pnpm"}} run build
 ```
 
 This creates:
@@ -130,7 +130,7 @@ This creates:
 Run the production build:
 
 ```bash
-npm start
+{{or .packageManager "pnpm"}} start
 ```
 
 ## Code Quality
@@ -139,15 +139,15 @@ There are a few commands to help you with code quality:
 
 ```bash
 # Type checking
-npm run typecheck
+{{or .packageManager "pnpm"}} run typecheck
 
 # Linting
-npm run lint
-npm run lint:fix
+{{or .packageManager "pnpm"}} run lint
+{{or .packageManager "pnpm"}} run lint:fix
 
 # Formatting
-npm run format
-npm run format:fix
+{{or .packageManager "pnpm"}} run format
+{{or .packageManager "pnpm"}} run format:fix
 ```
 
 ## Deployment with Databricks Asset Bundles

template/app.yaml.tmpl

@@ -1,4 +1,4 @@
-command: ['npm', 'run', 'start']
+command: ['{{or .packageManager "pnpm"}}', 'run', 'start']
 {{- if .appEnv}}
 env:
 {{.appEnv}}

template/package.json

@@ -3,12 +3,13 @@
   "version": "1.0.0",
   "main": "dist/server.js",
   "type": "module",
+  "packageManager": "pnpm@11.0.8",
   "scripts": {
     "start": "NODE_ENV=production node --env-file-if-exists=./.env ./dist/server.js",
     "dev": "NODE_ENV=development tsx watch --tsconfig ./tsconfig.server.json --env-file-if-exists=./.env ./server/server.ts",
     "build:client": "tsc -b tsconfig.client.json && vite build --config client/vite.config.ts",
     "build:server": "tsc -b tsconfig.server.json && tsdown -c tsdown.server.config.ts",
-    "build": "npm run build:server && npm run build:client",
+    "build": "pnpm run build:server && pnpm run build:client",
     "typecheck": "tsc -b tsconfig.server.json && tsc -b tsconfig.client.json",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -17,8 +18,8 @@
     "format:fix": "prettier --write .",
     "test": "vitest run",
     "clean": "rm -rf client/dist dist build node_modules",
-    "prebuild": "npm run sync && npm run typegen -- --wait",
-    "predev": "npm run sync && npm run typegen",
+    "prebuild": "pnpm run sync && appkit generate-types --wait",
+    "predev": "pnpm run sync && pnpm run typegen",
     "sync": "appkit plugin sync --write --silent",
     "typegen": "appkit generate-types",
     "setup": "appkit setup --write"
@@ -72,6 +73,9 @@
     "vite": "npm:rolldown-vite@7.1.14",
     "vitest": "4.1.9"
   },
+  "optionalDependencies": {
+    "@ast-grep/napi-linux-x64-gnu": "0.37.0"
+  },
   "overrides": {
     "vite": "npm:rolldown-vite@7.1.14",
     "@opentelemetry/core": "2.8.0",