Deploy From An Existing Repository

Now that you have chosen to deploy from an existing repository, you can select the repository and deploy it to Atlas. Pushing to your main branch in GitHub will then deploy updates to Atlas automatically.

Atlas supports Node.js applications using popular frameworks like Faust.js, Next.js, Gatsby, Nuxt, SvelteKit, etc.

First make sure that you've pushed your application's code to your GitHub repository. If you're not familiar with pushing code to a GitHub repository, see this guide: Adding an existing project to GitHub using the command line.

Your application needs to include a wpe-build script in the scripts field in your project's package.json file. It should execute the build command for your project. This is the script that the Atlas platform will execute when it builds your app.

For example, the package.json file for a Faust.js or Next.js app would need to be updated as shown below.

  "scripts": {
    "wpe-build": "next build",
    // etc.
  },

If you don't know what command needs to be run to build your app, please refer to your JavaScript framework's documentation.

Connect your GitHub account so you can select the repo to deploy to Atlas.

  1. In the Repository Settings view, select Connect.

  2. GitHub opens in another tab of your web browser. Give WP Engine permission to access your repositories.

After Atlas connects to your GitHub account, the Connect button indicates that you are Connected. A list of repositories associated with your GitHub account appears.

Connected to GitHub

Now that GitHub is connected, it's time to connect your repository.

  1. From the list of repositories, select the one with your application's code.

  2. Select Continue to proceed to the WP Engine Settings page.

On the WP Engine Settings screen:

  1. Fill out a name for your application. We recommend choosing a name similar to your GitHub repository's name. The application name cannot be changed once it has been deployed.

  2. Select a region for your application. The region you select will be used for all of your app's environments (production/staging/etc.) and cannot be changed once your Atlas application has been deployed.

  3. Click Continue.

Choose a name and region

  1. From the list of your repository's branches, select the branch you want to base your environment on. Whenever changes are pushed to this branch, your app will be automatically re-deployed.

Examples:

  • If you want to create a production environment, you could use your repo's main branch
  • If you want to create a staging environment, you could use your repository's staging branch

Select a branch

  1. Enter a name for your Atlas environment. The name should represent how you intend to use the environment. For example, enter something like prod if it's a production environment, staging if it's a staging environment, etc.

  2. Every headless environment is associated with a WordPress environment. Choose either:

    • I already have a WordPress environment: Use a WordPress site from your WP Engine account. Select the search bar and search for the name of your WordPress site.
    • I want to create a new WordPress environment: WP Engine makes a new WordPress site and links it to your application. In the box, enter a name for your new WordPress site.

Link to WordPress

  1. In order for your WordPress environment to become "headless", Atlas installs the WP GraphQL and Atlas Content Modeler plugins.

If you're using the Faust.js Starter Kit or an existing Faust.js app repository, check the I am using Faust.js checkbox. This will ensure that the FaustWP plugin is also installed.

Select Faust.js Plugin

NOTE: If you're using an existing application (rather than the Faust.js Starter Kit), see the Environment variables (Optional) section below to set up environment variables before proceeding with the steps below.

  1. Select Create App.

  2. The Atlas app details page appears. When Atlas completes building your application, a checkmark appears under Last Build.

Headless App Building

  1. To visit your headless WordPress app once the first deploy finishes, click the link under the Atlas URL heading. Your Atlas app opens in a new browser tab. Enjoy!

First app deployed

To add environment variables for your app, click Add environment variable.

Enter the Key and Value pairs for each environment variable.

For example, you may need to add a NEXT_PUBLIC_WORDPRESS_URL key with a URL as its value to specify which WordPress site should be used as the data source for the app. You may also need to specify additional environment variables to store sensitive data such as API keys and secrets.

Please refer to your JavaScript framework's documentation if you're unsure what environment variables are required for your app.

To make changes to the look and functionality of your app, see our Local App Development guide.