Replit: Deploying Replit Agent Sites to WP Engine Headless

Objective: This guide documents the end-to-end process for exporting a web application generated by the Replit AI Agent, reconfiguring its strict pnpm monorepo structure, and setting up an automated deployment pipeline to WP Engine’s Atlas (Headless Platform).

1. Project Suitability & Limitations (READ FIRST)

Because the Replit AI Agent is a full-stack developer, it can generate applications in dozens of languages and connect to various local databases. However, WP Engine Headless is strictly a Node.js container environment. Before attempting to deploy a Replit project to WP Engine, ensure the project meets these strict boundaries:

• ✅ MUST BE JAVASCRIPT/TYPESCRIPT: The frontend must be built using a Node-based framework (e.g., React, Next.js, Vite, Vue, Astro).
• ❌ NO NON-NODE BACKENDS: If the Replit Agent built a backend using Python (Flask/Django), Ruby on Rails, Go, or PHP, it will not run on WP Engine Headless.
• ❌ NO LOCAL DATABASES: WP Engine containers are ephemeral. If the Replit project uses a local database (like SQLite or internal Replit DBs), the database will be wiped every time the container restarts.
• ✅ EXTERNAL DBs ARE OKAY: If the site requires database functionality, it must connect to an external headless service via API (e.g., Supabase, Firebase, headless WordPress CMS, or external PostgreSQL).
• 🌟 IDEAL USE CASES: This deployment pipeline is best suited for static brochure sites, portfolios, marketing landing pages, and frontend React applications that fetch data from external APIs.

2. Overview & Architecture Quirks

Unlike standard code generators that output a single, clean website folder, the Replit Agent builds a pnpm workspace (monorepo). This means your actual website code is buried in a subfolder (usually artifacts/nameofproject or similar), and it relies on a master catalog of dependencies located at the root of the project.

Because of this, we cannot simply point WP Engine to the subfolder. We must instruct WP Engine to install dependencies from the root, bypass Replit’s hidden AI sandbox folders, spoof some strict environment variables, and then launch the specific website folder.

Step 1: Pushing the Replit Workspace to GitHub

To set up auto-deployments, the code must be hosted on GitHub.

1. Open your project in Replit.
2. Click the Git icon on the far-left sidebar.
3. If this is your first time, connect your GitHub account.

4. Create a remote repository, manually create a blank repository on GitHub, go to the Git Settings in Replit, and paste the remote URL.
5. Commit your changes and push them to GitHub.

Step 2: Reconfiguring the Root package.json

This is the most critical step. Replit’s default configuration will crash on WP Engine due to strict TypeScript errors, missing environment variables, and pnpm version mismatches.

File to edit: The package.json located at the absolute root of your repository (NOT the one inside the artifacts/project folder).

Replace the entire contents of the root package.json with the following configuration:

{
  "name": "workspace",
  "version": "0.0.0",
  "license": "MIT",
  "scripts": {
    "preinstall": "sh -c 'rm -f package-lock.json yarn.lock; case \"$npm_config_user_agent\" in pnpm/*) ;; *) echo \"Use pnpm instead\" >&2; exit 1 ;; esac'",
    "build": "PORT=3000 BASE_PATH=/ pnpm --filter \"@workspace/brochure\" run build",
    "start": "cd artifacts/brochure && BASE_PATH=/ pnpm exec vite preview --config vite.config.ts --host 0.0.0.0 --port $PORT --outDir dist/public"
  },
  "private": true,
  "devDependencies": {
    "prettier": "^3.8.4",
    "typescript": "~5.9.3"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "packageManager": "pnpm@10.26.1"
}

💡 What this configuration does:

• packageManager: Forces WP Engine to use pnpm v10+, preventing fatal lockfile read errors.
• engines: Forces WP Engine to provision a modern Node 20+ environment.
• buildscript: * Injects dummy PORT and BASE_PATH variables to prevent Vite from panicking during the build.
  • Uses --filter "@workspace/brochure" to skip broken AI sandbox folders and only compile your website.
  • Removes the strict typecheck step to prevent minor AI-generated TypeScript typos from failing the deployment.
• start script: Navigates into the subfolder, sets the required WP Engine host (0.0.0.0), dynamically binds to WP Engine’s $PORT, injects BASE_PATH, and explicitly points Vite to the --outDir dist/public folder.

Action: Commit and push this updated package.json to your GitHub repository.

Step 3: Deploying on WP Engine

With the repository prepared, you can trigger the build.

1. Log in to the WP Engine User Portal and navigate to the Headless Platform tab.
2. Click Add App -> Deploy from Existing Repo.
3. Select your newly created Replit GitHub repository and the main branch.
4. Root Directory: Leave this as ./ (Crucial: Do not change this to the artifacts folder, or the pnpm installation will fail).

5. Linked WordPress Environment: Select an existing blank/dummy WordPress environment (Required by WP Engine for routing).
6. Click Deploy.

WP Engine will now read your custom package.json, install the correct pnpm version, build only the necessary brochure folder, and launch the site. Future pushes from Replit to this branch will now auto-deploy automatically!

Step 4: Continuous Integration & Auto-Deployment

Once the initial deployment is complete, your Replit workspace is securely connected to your live WP Engine environment via GitHub.

Unlike other platforms that automatically push every single prompt to GitHub, Replit gives you full control over when changes go live. The CI/CD pipeline flows like this:

1. Making the Change: You ask the Replit Agent for a UI update, feature addition, or code change. The Agent writes the code and displays it in your Replit workspace preview.

2. Reviewing in Workspace: You verify that the changes look and work exactly how you want them to inside Replit’s editor environment.
3. Manual Push (Your Control): When you are satisfied, you open the Git pane on the left sidebar in Replit, review the files changed, write a commit message, and click Commit and Push.

4. WP Engine Triggers: The moment those changes hit your connected GitHub repository, WP Engine detects the new commit and immediately spins up an automated build using your custom root package.json.

5. Live Update: Once the 4-step build script completes successfully, the updates are instantly pushed live to your production WP Engine URL!

Best Practice: Isolating Production via a Staging Branch

Because the Replit Agent can sometimes break code or install incompatible workspaces while trying to figure out a feature, it is highly recommended to protect your live production URL using a Git branching workflow:

• WP Engine (Production App): Set it to watch the main branch.
• Replit Workspace: Work on a staging or dev branch.

The Workflow:

• Develop in Replit: Ensure your Replit editor is set to your staging branch. Every time you commit and push from the Replit Git pane, it pushes cleanly to staging without affecting your live users.
• Go Live: When a batch of updates or features is fully complete and ready for the world, go to GitHub and open a Pull Request to merge staging into main.
• Auto-Deploy: The moment you approve and merge that Pull Request, WP Engine will detect the update on main, bypass the Replit sandbox folders, and compile your fresh production build safely.