Update dependencies and fix quickstart drift

[dex-the-ai]

Summary

• Update Next.js quickstart dependencies within supportable semver ranges and refresh the lockfile.
• Keep the sample working with couchbase@4.7.0 by normalizing local Couchbase connection strings, moving API-route tests to the Node environment, and adding a small Jest setup shim for TextEncoder/TextDecoder.
• Fix README drift around the user_profile bucket name, Node prerequisite wording, and the stale NextJS_README.md reference.
• Make the build-time Couchbase strip step skip cleanly when no native couchbase_impl.node artifact is present.

Verification

• npm ci
• npm run check
• npm run init-db:default
• npm test (Node 16.20.2 and Node 20.20.2)
• npm run init-db:local
• npm run load-sample-data
• npm run dev (served locally on http://localhost:3001 because port 3000 was already in use)
• node /tmp/nextjs_walkthrough_api.mjs (GET/POST/PUT/search/DELETE against the live dev server)
• PORT=3002 npm run dev + Dockerized Playwright capture against the live UI
• npm run build

Evidence

• Baseline before updates: npm run check, npm run init-db:default, and npm test all passed on Node 16.20.2; npm audit reported 33 vulnerabilities (6 low / 13 moderate / 12 high / 2 critical).
• After the dependency refresh, npm run check and npm test passed on both Node 16.20.2 and Node 20.20.2.
• npm audit --omit=dev now reports 3 remaining prod vulnerabilities, all gated behind breaking upgrades (next@16 and uuid@14).
• The local walkthrough exercised the live /api/user flow end to end: list existing profiles, create a profile, update it, search for it, and delete it again.
• Dockerized Playwright capture now covers the live Next.js UI itself: load the directory, create a user, edit it, search/select it, and delete it again.
• The production build now completes successfully with the updated dependency set.

UI screenshot

Walkthrough video

Open the user directory walkthrough

Walkthrough excerpt

## POST /api/user
status: 201
pid: c8e4e3da-40e3-4fbb-a391-03a0070141a2

## PUT /api/user?pid=created
status: 200
email: taylor.verified@example.com

## GET /api/user?search=Taylor&limit=5
status: 200
matches: 1

## DELETE /api/user?pid=created
status: 200
message: Successfully Deleted: c8e4e3da-40e3-4fbb-a391-03a0070141a2

Build notes

No couchbase_impl.node found; skipping strip
✓ Compiled successfully
✓ Generating static pages (2/2)

The build still logs pre-existing Couchbase local-environment quirks when sample data already exists or when the local indexer storage mode has not been set, but the build exits successfully.

• tutorial-maintenance/runs/couchbase-examples__nextjs-quickstart/2026-04-30-115029/verification.md
• tutorial-maintenance/runs/couchbase-examples__nextjs-quickstart/2026-04-30-115029/walkthrough-api.log
• tutorial-maintenance/runs/couchbase-examples__nextjs-quickstart/2026-04-30-115029/build.log
• tutorial-maintenance/runs/couchbase-examples__nextjs-quickstart/2026-04-30-115029/media-urls.txt
• tutorial-maintenance/runs/couchbase-examples__nextjs-quickstart/2026-04-30-115029/visual-evidence-blocker.txt

Notes

• README drift fixed in-repo: CB_BUCKET should be user_profile, not user_profiles.
• README also referenced a NextJS_README.md file that is not present in this repository.
• The public tutorial page still appears drifted from repo reality (user_profiles, NodeJS & NPM (v12+)).
• Native Playwright browser install is still blocked on this ubuntu26.04-arm64 host, so the visual proof now uses the Dockerized browser path instead.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
couchbase-nextjs-quickstart	Ready	Preview, Comment	May 1, 2026 10:50pm
nextjs-quickstart	Ready	Preview, Comment	May 1, 2026 10:50pm

[gemini-code-assist]

Code Review

This pull request updates project dependencies, documentation, and environment defaults, while transitioning the Jest configuration to a Node.js environment. Key improvements include more robust Couchbase connection string handling and a refined script for stripping the Couchbase SDK binary. Feedback highlights the need to correctly handle existing query parameters when appending TLS settings and points out potential portability issues with the shell-based stripping script on Windows.

[dex-the-ai]

I pushed a follow-up update in 4f7d711 and resolved the open review threads.

• bumped next to the latest stable 16.2.4
• aligned the quickstart to Node 24 LTS (package.json engines, lockfile regenerated on Node 24, Actions test job updated to 24.x)
• migrated linting to ESLint 9 flat config so the Next 16 upgrade still passes lint locally/CI
• replaced the shell-only strip-cb-sdk helper with a cross-platform Node script
• fixed the couchbases://...tls_verify=none query-string separator handling

All PR checks are now green on 4f7d711.

One caveat from the dependency check: npm audit --omit=dev still reports the current next / transitive postcss advisory even on 16.2.4, so updating to latest stable did not fully clear that advisory. I left uuid alone in this pass so the branch stayed focused on the requested Next/Node 24 work.

Local verification

• npm install
• npm run check
• npm run init-db:default
• npm test
• set -a && . ./.env.default && set +a && npm run build
• npm audit --omit=dev --json

Notes:

• local Couchbase init/build still printed the existing index-storage warnings and sample-data DocumentExistsError, but the scripts completed
• reviewer-facing browser screenshot capture was blocked on this host because Playwright cannot install Chromium on ubuntu26.04-arm64 and there is no system browser available
• artifact directory: tutorial-maintenance/runs/nextjs-quickstart/pr-193-followup-20260430-next16/

[dex-the-ai]

@ejscribner owner ping for this maintenance PR — testing the new manifest-driven owner notification flow. The review request is already present on this PR; this comment is just the tagging half of the workflow.

[ejscribner]

@dex-the-ai I got some errors when trying to load up the preview build on Vercel:

2026-05-01 22:36:01.315 [error] Failed to handle / Error: Failed to load external module couchbase-fd37fa160f83eb64: Error: Could not find native build for platform=linux, arch=x64, runtime=napi, nodeVersion=24.14.1, sslType=openssl3, libc=linux loaded from /var/task/node_modules/couchbase.
    at Context.externalRequire [as x] (.next/server/chunks/ssr/[turbopack]_runtime.js:624:15)
    at module evaluation (.next/server/chunks/ssr/[externals]_couchbase_0z~f7l4._.js:1:44)
    at instantiateModule (.next/server/chunks/ssr/[turbopack]_runtime.js:853:9)
    at getOrInstantiateModuleFromParent (.next/server/chunks/ssr/[turbopack]_runtime.js:877:12)
    at Context.esmImport [as i] (.next/server/chunks/ssr/[turbopack]_runtime.js:281:20)
    at module evaluation (.next/server/chunks/ssr/[root-of-the-server]__00st03j._.js:1:83)
    at instantiateModule (.next/server/chunks/ssr/[turbopack]_runtime.js:853:9)
    at getOrInstantiateModuleFromParent (.next/server/chunks/ssr/[turbopack]_runtime.js:877:12)
    at Context.esmImport [as i] (.next/server/chunks/ssr/[turbopack]_runtime.js:281:20)
    at <unknown> (.next/server/chunks/ssr/[root-of-the-server]__00st03j._.js:6:6600)
2026-05-01 22:36:01.316 [error] Error: Failed to load external module couchbase-fd37fa160f83eb64: Error: Could not find native build for platform=linux, arch=x64, runtime=napi, nodeVersion=24.14.1, sslType=openssl3, libc=linux loaded from /var/task/node_modules/couchbase.
    at Context.externalRequire [as x] (.next/server/chunks/ssr/[turbopack]_runtime.js:624:15)
    at module evaluation (.next/server/chunks/ssr/[externals]_couchbase_0z~f7l4._.js:1:44)
    at instantiateModule (.next/server/chunks/ssr/[turbopack]_runtime.js:853:9)
    at getOrInstantiateModuleFromParent (.next/server/chunks/ssr/[turbopack]_runtime.js:877:12)
    at Context.esmImport [as i] (.next/server/chunks/ssr/[turbopack]_runtime.js:281:20)
    at module evaluation (.next/server/chunks/ssr/[root-of-the-server]__00st03j._.js:1:83)
    at instantiateModule (.next/server/chunks/ssr/[turbopack]_runtime.js:853:9)
    at getOrInstantiateModuleFromParent (.next/server/chunks/ssr/[turbopack]_runtime.js:877:12)
    at Context.esmImport [as i] (.next/server/chunks/ssr/[turbopack]_runtime.js:281:20)
    at <unknown> (.next/server/chunks/ssr/[root-of-the-server]__00st03j._.js:6:6600)
    ```

[dex-the-ai]

@ejscribner I checked this and pushed a123b36.

The preview failure looked real: the Next 16/Turbopack trace was bundling node_modules/couchbase, but not the optional @couchbase/...-napi platform package that the SDK resolves at runtime on Vercel. That leaves /var/task/node_modules/couchbase present without the Linux x64 native build, which matches the error you hit.

What I changed:

• added next.config.mjs with outputFileTracingIncludes for / and /api/user so Next includes ./node_modules/@couchbase/**/* in the traced server output

What I verified locally:

• npm run check
• npm test
• set -a && . ./.env.default && set +a && npm run build
• after the build, both .next/server/pages/index.js.nft.json and .next/server/pages/api/user.js.nft.json now include the @couchbase native package files (on this host, the arm64 variants)

Vercel and CI are rerunning on a123b36 now. If the preview still errors after that deploy finishes, I’ll keep digging, but this looks like the missing trace input.