nango-nextjs-bootstrap

name	nango-nextjs-bootstrap
description	Scaffold a minimal Next.js App Router app and configure it end to end with Nango Connect UI for a GitHub connection. Use when the user asks to create a working Nango, GitHub OAuth, connection-demo, or nango-demo app from scratch and wants Chrome used for Nango dashboard setup.

Nango Next.js Bootstrap

Goal

Create a fresh nango-demo Next.js App Router project, install the official Nango frontend and Node SDKs, configure or verify a Nango dev GitHub integration/API key in Chrome, wire the app with the captured environment secret and integration ID, and leave the user with a local page whose only workflow is:

connect to github -> Nango Connect UI auth -> display safe connection details.

Use the bundled script scripts/apply-nango-next-app.mjs to write the app files after the Nango secret key and integration ID are known.

Required Chrome Skill

For all Nango dashboard work, use the Chrome plugin skill chrome:control-chrome.

Do not hardcode a local plugin cache path. The Chrome plugin is installed under user-, platform-, and version-specific paths, and that location differs across machines.

Resolve Chrome this way:

1. If the user explicitly mentioned or linked chrome:control-chrome, use that skill from the current context.
2. If it is listed in the available skills, open its SKILL.md using the path supplied by the runtime for this session.
3. If the skill is not visible but tool_search is available, search for chrome control-chrome or node_repl js to expose the Chrome/browser-client workflow.
4. If Chrome still is not available, report that the Chrome plugin must be installed/enabled and stop. Do not fall back to the in-app Browser for Nango dashboard edits that require the user's signed-in Chrome session.

After resolving Chrome, follow its bootstrap exactly, read the full browser documentation it returns, and use the Chrome extension browser. Do not substitute generic web browsing, macOS open, or a separate browser tool for Nango dashboard edits.

Normal no-human-intervention operation assumes Chrome already has a valid Nango dashboard session. If Nango or GitHub presents login, MFA, CAPTCHA, or an account chooser that cannot be completed from the current Chrome session, stop and report the blocked state.

Workflow

1. Pick a project directory and exact local origin.

   • Default project command:

     npx create-next-app@latest nango-demo --ts --app --empty --eslint --use-npm --yes --disable-git
     

   • Default origin is http://localhost:3000.
   • If port 3000 is occupied by an unrelated process before Nango is tested, choose the next free port and use that same origin for testing.

2. Install the official SDKs:

   cd nango-demo
   npm install @nangohq/frontend @nangohq/node
   

3. Configure or verify Nango in Chrome.

   • Navigate to https://app.nango.dev/dev/.
   • Use the dev environment unless the user asks for another environment.
   • Prefer the Nango quickstart GitHub integration:
     • Integration ID: github-getting-started
     • If it exists, reuse it.
     • If a different GitHub integration already exists and the user clearly wants that one, use its exact Integration ID instead.
   • If no GitHub quickstart/custom integration is available, create a GitHub integration from the dashboard. If Nango asks for provider OAuth app credentials, pause and tell the user the provider app credentials are required; do not invent credentials.
   • Go to Environment settings -> API Keys. Reuse an existing suitable dev API key if it can be revealed/copied, or create a new key with enough scope to create Connect sessions and read connections.
   • If an icon-only copy/reveal action does not work through a Playwright locator, inspect the visible DOM and click the specific icon node. Treat the clipboard value as valid only after checking that it is non-empty and key-like; do not print it.
   • Capture:
     • NANGO_SECRET_KEY
     • NANGO_INTEGRATION_ID
   • Treat the secret key as sensitive. Write it only to the local app's ignored .env.local; never print it in the final answer or commit it.

4. Patch the app using the bundled script:

   # Set SKILL_DIR to the directory containing this SKILL.md.
   node "$SKILL_DIR/scripts/apply-nango-next-app.mjs" \
     --project-dir . \
     --secret-key "<NANGO_SECRET_KEY>" \
     --integration-id "<NANGO_INTEGRATION_ID>"
   

   Optional flags:

   --demo-user-id "local-nango-demo-user"
   --demo-user-email "[e-mail]"
   --demo-user-display-name "Local Nango Demo"
   

   After the script runs, verify that .env.local exists, .env.local is ignored, .env.example is unignored, and .env.example contains no secret value.

5. Validate locally:

   npm run lint
   npm run build
   

   If npm audit reports issues from the freshly scaffolded Next.js dependency tree, mention them in the final report. Do not run npm audit fix --force when npm says the fix is breaking or downgrades the selected framework.

6. Start and test the app:

   npm run dev -- --port <PORT>
   

   Open the exact local origin in Chrome and click connect to github. Nango Connect UI may open as a full-page iframe and require a second click on its own Connect button before GitHub auth starts. Complete the Nango/GitHub flow, and verify the page displays connection ID, integration ID, provider, credential type, timestamps, scopes, tags, metadata, and errors without exposing access tokens.

7. Verify in the Nango dashboard.

   • Go to Connections in the same Nango environment.
   • Confirm a connection with the same connection ID appears.
   • Confirm the demo user tags match the local app's display.

Dashboard Notes

Use visible page state as source of truth. Prefer Playwright locators from the latest DOM snapshot. After creating or editing a key/integration, reload the dashboard page and inspect the persisted value before treating setup as done.

If a Nango dashboard page initially returns an empty DOM after navigation, wait briefly and re-check once before changing strategy; the dashboard can take a moment to hydrate.

Do not broaden scope into syncing functions, proxy requests, production environments, or custom provider code unless the user asks. The default demo is only a GitHub OAuth connection and safe connection-detail display.

Completion Report

Final output should include:

• Project path and exact local URL.
• Assumptions, especially which Nango environment and integration ID were used.
• Files changed.
• Exact validation commands and results.
• Browser/dashboard verification result.
• Skipped checks and remaining risks.
• No secret values.