GoDaddy Node.js Hosting

Help users build or fix Node.js apps for GoDaddy Node.js Hosting (upload → install → run build → run start). Package manager: npm, pnpm, or yarn (lockfile determines platform choice).

Rules: [contract.md](contract.md). Recipes: [examples.md](examples.md). Errors: [troubleshooting.md](troubleshooting.md). Email: [email.md](email.md). Validator: [scripts/validate-paas.mjs](scripts/validate-paas.mjs).

When to use which path

Audience routing

Non-technical user (no jargon, “I built this in Lovable”, “how do I upload”):

1. Output the [pre-upload checklist](#pre-upload-checklist) first in plain language.
2. Follow [Adapting an existing app](#adapting-an-existing-app) (existing zip or export).
3. Prefer the [static SPA + Express](examples.md#vite-react-vue-spa) or [static only](examples.md#static-only) recipe when there is no server. For Next.js with output: 'export', use [nextjs-static-export](examples.md#nextjs-static-export) instead — explain: "Your app builds to static files. We add a small server so GoDaddy can run it — your site stays the same."
4. One small change at a time; explain the next hosting step in plain language (Git sync or zip upload in the UI).
5. Run the validator before saying the app is ready.

Technical user - existing app: follow [Adapting an existing app](#adapting-an-existing-app); use the matching framework recipe for start/build only; do not re-explaining basics.

Technical user - new app: follow [New app workflow](#new-app-workflow); use the matching framework recipe from [Framework detection](#framework-detection).

Deploy contract (summary)

• Root package.json with name, version, main (file exists), scripts.build, and scripts.start
• build may be "echo build" when nothing compiles; frameworks need real build commands ([examples.md](examples.md))
• Listen on process.env.PORT; use 0.0.0.0 when the framework needs a host
• Runtime deps in dependencies; do not upload node_modules
• Secrets via process.env; no .env in zip; zip under 100 MB
• One app per upload; lockfile when possible
• Outbound HTTP/HTTPS only; platform MySQL via DB_* env + mysql2 if using a database ([contract.md](contract.md))
• Email via the platform gateway (http://127.0.0.1:2525/api/email/send) using the vended sendEmail() helper; no nodemailer, no external SMTP ([email.md](email.md))

Publishing updates (customer communication)

The platform supports Git repository sync and zip upload in the Node.js Hosting UI. See [AGENTS.md](../../AGENTS.md) Deployment Flow for agent context.

• Do not infer deploy method from .git, lockfiles, or export origin (a zip export may include .git from local development).
• Default when telling the user how to publish: use neutral wording — e.g. “When you’re ready, update the app in Node.js Hosting using Git sync or a zip upload in the hosting UI.”
• Only go path-specific (zip steps vs connect/push Git) if the user states or asks which they use.
• Avoid prescriptive one-path phrases like “upload a new zip” or “push to your remote” without that confirmation.

Managed MySQL

Optional platform MySQL injects DBHOST, DBPORT, DBNAME, DBUSER, DB_PASSWORD. The app must read each from process.env (not hard-coded). Use mysql2 in dependencies and parameterized queries.

Recipe: [examples.md#managed-mysql](examples.md#managed-mysql). Validator: E009, E010 when a DB client or Prisma MySQL provider is detected.

Email

Apps send transactional email (contact forms, notifications, receipts, password resets) through the platform's built-in gateway at http://127.0.0.1:2525/api/email/send — loopback-only, inside every container. No SMTP config, no nodemailer, no third-party API keys; outbound SMTP is not routable from the container.

Copy the sendEmail() helper into src/server/email.ts and call it from route handlers. All email code calls the helper — never POST to the gateway directly, never import nodemailer.

Load-bearing rules (full detail: [email.md](email.md)):

• Omit from by default — the gateway picks the app's canonical sender. Set from only as a hardcoded literal on a verified domain (unverified → 400); never from user input.
• Fixed recipients (contact-form admin, alerts) come from process.env (e.g. CONTACTFORMRECIPIENT_EMAIL), set in the Node.js Hosting UI — never hardcode, never TODO-placeholder. Fail closed when unset. Per-user recipients plumb through from app data, not anonymous request bodies.
• Don't echo raw gateway errors to end-users — log server-side, show a generic failure message.

Recipe and helper: [email.md](email.md). Contract rule: C13. Migrating existing nodemailer code: [email.md#migrating-from-nodemailer](email.md#migrating-from-nodemailer).

Adapting an existing app

Use this path when the user already has a project (local repo, zip export, or app that failed on Node.js Hosting). Goal: hosting compatibility only — not new features, refactors, or framework changes.

Principles

• Do not add or remove product features; do not refactor unrelated code.
• Smallest diff: prefer package.json (name, version, main, build, start), listen/bind lines, and a static server file when missing — not rewriting app logic.
• Keep the detected framework; align main, scripts.start, and scripts.build with [examples.md](examples.md) for that stack only.

Adaptation workflow

Audit against [contract.md](contract.md) (nine platform requirements: package.json fields, build/start, PORT, deps, env vars, Vite, zip size, network, MySQL). For each item: check compliance, apply the smallest fix, preserve all existing behaviour.

Copy and track progress:

- [ ] Run validator on project root (baseline)
- [ ] Map each error/warning to contract rule (see table below)
- [ ] Apply minimal fix per ID; use framework recipe for script names only
- [ ] Re-run validator until exit 0 (or document warnings if not --strict)
- [ ] install → build → start locally (match lockfile package manager)
- [ ] Pre-upload checklist complete

Validator (required before done):

node scripts/validate-paas.mjs /path/to/project

Run from this skill directory (e.g. after npx skills add or symlink to ~/.cursor/skills/godaddy-nodejs-hosting). From a clone of nodejs-hosting-agent-skill: npm run validate -- /path/to/project.

Symptom detail: [troubleshooting.md](troubleshooting.md).

Special cases

• Monorepo (C1): extract a single app folder with its own root package.json before adapting; do not restructure packages in place unless the user asks.
• Next.js static export: Check next.config.* for output: 'export' before applying the standard Next recipe. Use [nextjs-static-export](examples.md#nextjs-static-export) (next build + Express serving the export dir), not next start. Match distDir in config (default out/). Same hosting pattern as Vite/Lovable static apps, but build is next build.
• Frontend-only / no server: [vite-react-vue-spa](examples.md#vite-react-vue-spa) and [AI export quick fixes](#ai-export-quick-fixes).
• Migrating from another host: same steps; focus on PORT, start/build, dependencies, and lockfile.

For Replit, Lovable, and Bolt patterns, see [AI export quick fixes](#ai-export-quick-fixes) after applying this workflow.

Adaptation is complete under the same [done criteria](#done-criteria) as a new app (validator 0, checklist, ready to update in Node.js Hosting).

New app workflow

Copy and track progress:

- [ ] Detect framework (package.json)
- [ ] Apply recipe from examples.md
- [ ] Add `.npmrc` with `registry=https://registry.npmjs.org/` to project root
- [ ] install && run build (if exists) && run start (npm, pnpm, or yarn — match user's lockfile)
- [ ] node scripts/validate-paas.mjs <project-dir>
- [ ] Pre-upload checklist complete

Run the validator as in [Adapting an existing app](#adapting-an-existing-app).

Framework detection

Do not invent start commands for known frameworks; use the recipe exactly.

AI export quick fixes

For Lovable/Bolt static hosting, use the [vite-react-vue-spa](examples.md#vite-react-vue-spa) recipe.

Pre-upload checklist

• package.json: name, version, main, build, start
• Production deps in dependencies; do not deploy node_modules (exclude from zip or Git)
• process.env.PORT for listening; secrets via process.env
• Deployment artifact under 100 MB (zip upload)
• Runs locally: install → build → start
• .npmrc at project root with registry=https://registry.npmjs.org/. Lockfile URLs must be public npm (regenerate lockfile if not)
• Lockfile present (committed or included in upload); validator exit 0; no .env
• HTTP/HTTPS outbound only; DB uses DB_* + mysql2 if applicable

Done criteria

Task is complete only when:

1. validate-paas.mjs exits 0 on the project directory.
2. Pre-upload checklist is satisfied.
3. User knows they can publish/update the app in Node.js Hosting (Git sync or zip upload in the UI). Mention only the path they use if they’ve already said so.