Guide

Getting started

Bootstrap the monorepo, start the VIP CLI dev-env, and verify you can open the local site.

Local environment

All local development and Playwright E2E testing use the VIP CLI dev-env (prc-platform), configured via .wpvip/vip-dev-env.yml.

ContextCommand
Interactive local dev (macOS)npm run vip:start — assume already running at https://prc-platform.vipdev.lndo.site/
Cursor Cloud / autonomous agentsnpm run vip:cloud — auto-started via .cursor/environment.json
Playwright E2E testsnpm run vip:start && npm test

See Cursor Cloud agents for cloud-specific gotchas (Elasticsearch disabled in cloud agents, HTTPS trust, VIP keychain on headless VMs).

Prerequisites

  1. Bootstrap JS deps (once per clone): npm run bootstrap from the repo root. This generates .npmrc / auth.json for private packages and installs the unified root Composer autoloader into client-mu-plugins/vendor/.
  2. Build plugins (required on a fresh clone): npm run build:all (or npx turbo build --force --concurrency=8 if remote-cache hits lack local artifacts).
  3. Install VIP CLI globally: npm install -g @automattic/vip

Getting started with local development

  1. Create the dev-env

    First time only: vip dev-env create --elasticsearch=n (omit --elasticsearch=n to enable ES locally). This reads .wpvip/vip-dev-env.yml, which sets multisite to subdirectory.

  2. Start the dev-env

    Run npm run vip:start. It checks for Composer vendor and block-library build artifacts and may run a long first-time install/build.

  3. macOS networking

    First time: bash bin/setup/vip-dev-env-macos-network.sh to add /etc/hosts entries and trust the WPVIP Local CA for HTTPS.

  4. Import database (optional)

    From sync: npm run vip:sync:alpha. Partial import: npm run vip:partial-sync.

  5. Open the site

    pewresearch.org: https://prc-platform.vipdev.lndo.site/pewresearch-org. Admin: https://prc-platform.vipdev.lndo.site/wp-admin/network.

  6. Build and test

    Rebuild affected workspaces with Turbo, e.g. npx turbo build --filter=@prc/block-library.

GitHub Codespaces (cloud environment)

GitHub Codespaces offers a unique alternative to local development, shifting environment resources to the cloud. This allows for a more consistent development environment and the ability to work from any device with a browser. It also offers that native, desktop-like experience with Visual Studio Code.

Each developer may have up to 4 codespaces running at once. Codespaces are billed by the minute, but an org wide policy enforces an idle time of 1 hour. This means that if you are not actively using your codespace, it will be automatically shut down after 1 hour of inactivity. You will not lose any work, but you will need to wait for the codespace to start up again which takes anywhere from 1-3 minutes.

Additionally, the default profile for the codespace is set to 16gb of RAM and 4 vCPUs. This can be adjusted after the fact but it is not recommended to use the cloud environment for heavy tasks such as image processing or large database imports. Use the local environment for these tasks.

Getting started with cloud environment – Browser/VS Code Interface

  1. Create a new branch for your work in GitHub following the issue/ naming convention.
  2. Navigate to the repository in GitHub.
  3. Select the button labeled "<> Code".
  4. In the displayed options, select the tab labeled "Codespaces".
  5. Select the button labeled "Create codespace on issue/**".**

In a new browser tab, a displayed output log will report progress on the creation of the new codespace. The creation process will take several minutes to complete.

When creation of the codespace is complete, the content in the browser tab will refresh and display a Visual Studio Code (VS Code) interface.

You can also access your codespaces directly from the Remote Explorer View in VS Code Desktop or by searching for Open in VS Code Desktop in the browser app or directly from the repo "<> Code" menu. You can also set VS Code Desktop as the default editor for codespaces in your settings.

Getting started with cloud environment – CLI Interface/Cursor Interface

  1. Make sure you have the Remote – SSH extension installed in Cursor.
  2. Run npm run codespace:create to create a new codespace.
  3. When the codespace is created, in a new Cursor window, run Remote – SSH: Connect to Host from the command palette and then select your new codespace from the list.
  4. To make your application port public, run npm run codespace:public and select your codespace.
  5. For partial database imports (Codespaces or local VIP CLI), run npm run vip:partial-sync and follow the prompts. See client-mu-plugins/prc-vip-dev-env/DBIMPORT.md for more details.
  6. NOTE: For now, you will need to get the URL from the browser or the end of the create script output to open the codespace application, ports will not show up in the "Ports" tab in Cursor…for now.
  7. Once you are connected via remote-ssh, click "open folder" and select /workspaces/prc-platform/ to open the repo in Cursor.

Log in to cloud based WordPress

In the VS Code interface:

  1. Select the tab labeled "Ports" located in the bottom half of the screen.
  2. In the row for "Application (80)", select the value in the column labeled "Local Address". Three icons will be displayed at the right of the local address value.
  3. Load the front end of the codespace environment in a new browser tab by either:
  • Selecting the globe icon labeled "Open in Browser".
    • Or right-clicking on the local address value and selecting "Open in Browser" from the flyout menu.
  1. Access the WordPress login portal by appending /wp-admin to the local address value in the browser's address bar (e.g., https://$CODESPACE_NAME-80.preview.app.github.dev/wp-admin).
  2. Log in with the default user credentials, or user credentials that exist in a database that was imported to the codespace environment.

Default login credentials

Users can log in to the VIP dev-env or codespace with default WordPress user account credentials.

Default username: vipgo

Default password: run vip dev-env info --slug prc-platform for the generated password, or use the autologin URL from that output.

The default user account has a Super Admin role on the WordPress multisite.

Was this helpful?