Setting Up Your Dev Playground

Purpose

List the steps to run a PageBuilder instance locally.

Audience

Developers learning to work with PageBuilder.

Getting Started

To start using PageBuilder Engine, you must use the Arc Fusion Command-Line Interface (CLI), which enables you to perform the following tasks:

• Create pages and layouts using a local PageBuilder Engine and PageBuilder Editor server.
• Test your custom components (feature blocks) locally.
• Create bundles for deployments if you have access to an Arc XP organization.

Note

Experience with tools like Create-React-App can make it easier to work with the PageBuilder Engine CLI tool.

Prerequisites to Running PageBuilder

Ensure you have the following prerequisites before you run PageBuilder locally:

• Skills
• System Requirements
• Access to an Arc XP Organization (Optional)

Skills

Ensure you have the following skills:

• Basic web development knowledge
• Proficiency with Javascript
• Working knowledge of Docker
• Basic knowledge of React
• Familiarity with Node.js
• Familiarity with npm

System Requirements

Ensure you have the following system requirements:

• Installed Docker: In Docker’s Settings, ensure to set up the Resources as follows:
  • CPUs: 6
  • Memory: 8GB or more
• Installed Node.js.
• Installed npm: Ensure that the version is 5.2 or later.
  

Note

npx comes pre-packaged with npm in npm Versions 5.2.0 and later. If you don’t have npx installed, run npm install -g npx.

To verify the version, take the following steps:

1. Open a terminal.
2. Run the following command: npm -v
   If npm is installed, the command returns the version. For example, 10.7.0
   

Access to an Arc XP Organization (Optional)

Access to an Arc XP Organization requires a signed contract with Arc XP. After becoming a customer, you get the credentials and settings to use Arc XP’s full feature set.

To connect to an Arc XP Organization, you must configure access tokens and website information in your local development environment while using the Arc Fusion CLI. However, you can use Arc Fusion CLI without connecting it to an Arc XP organization.

The Arc Fusion CLI works in the following scenarios:

• Running PageBuilder Locally without Arc XP Credentials (Available for anyone).

  • Enables you to try core Arc XP functionalities.
  • Runs a local server with PageBuilder Engine and PageBuilder Editor.
  • Enables you to test custom feature blocks with content from APIs you already have access to (non-Arc XP APIs).

• Running PageBuilder Locally with Arc XP Credentials (Available for onboarded Arc XP customers).

  • Runs a local server with PageBuilder Engine and PageBuilder Editor.
  • Enables you to set API access tokens as environment variables.
  • Enables you to test custom components with content sources from your Arc XP organization.

Important

This guide lists the steps to run PageBuilder without Arc XP credentials.

Running PageBuilder Locally Without Arc XP Credentials

To run PageBuilder locally, complete the following steps:

1. In the location of your choice, create the directory for your local PageBuilder instance:

   mkdir <directory-name>

   Important

   Ensure the absolute path to the directory does not contain periods (”.”) to avoid the following MongoDB error:
   UnhandledPromiseRejectionWarning: MongoAPIError: database names cannot contain the character '.'

2. Enter the directory you created:

   cd <directory-name>

3. Install Arc Fusion CLI:

   npx @arc-fusion/cli init

   Note

   Step 3 installs Arc Fusion CLI locally as a project dependency, which:

   • Ensures consistent CLI versions across teams.
   • Prevents system PATH configuration issues.

   Optionally, you can install Arc Fusion CLI globally with the command npm i -g @arc-fusion/cli. The following steps assume a local Arc Fusion CLI installation.

4. Type y to grant permission to install @arc-fusion/cli packages
   The initialization process continues and completes.

5. Start the PageBuilder Engine and PageBuilder Editor local server:

   npx fusion start

   The project builds and runs the server.

6. In your browser, open the following URL: localhost/pagebuilder/pages
   A PageBuilder page displays:

   Figure 1. PageBuilder Editor

The PageBuilder Engine homepage is empty because you have not created any pages. Complete the Creating with PageBuilder process to populate the PageBuilder Engine homepage.

Important

Without credentials or environment variables to work with a live Arc XP organization, the PageBuilder Editor displays an error message. You can ignore the error message while you complete the steps listed in the Quick Start documents.

Figure 2 shows the Site Service Configurations error message.

Figure 2. Site Service Configurations Error in PageBuilder Editor

Stopping the PageBuilder Engine Locally

To stop the PageBuilder Engine on your local machine, run:

npx fusion down

To verify that all the PageBuilder Engine services stopped, run:

docker ps