DDEV Drupal Experience Builder Development Environment
This creates and configures a DDEV project for local Drupal Experience Builder (XB) module development. Specifically, it creates a Drupal site, clones and installs the module, sets up the front-end dependencies, and provides specialized development and testing tools.
Notice: This add-on is experimental. See Support & community below.
Requirements
Obviously, this requires a working DDEV installation. It has been successfully tested with Orbstack, Lima, Colima, Rancher Desktop, and Docker Desktop. Others should work fine, as well.
Installation
# Create a new directory for your new DDEV project.
# This can be any place you like. For example:
mkdir ~/Sites/xb-dev
cd ~/Sites/xb-dev
# Configure the new DDEV project.
ddev config --project-type=drupal11 --docroot=web
# Create the Drupal project.
ddev composer create drupal/recommended-project:11.x@dev --no-install
# Install the add-on.
ddev add-on get drupal-xb/ddev-drupal-xb-dev
# Perform one-time setup operations.
ddev xb-setup
# Optionally add some convenience extras for development.
ddev xb-dev-extras
# Optionally configure the environment for Workspaces development. Note: This can be
# a little volatile due to upstream Workspaces changes. Be aware that it can fail
# and leave your site in a non-working state requiring you to set it up again from scratch.
ddev xb-workspaces-dev
Usage
The resulting DDEV project is just like any other one. Interact with it using the the built-in commands, e.g., ddev launch to browse the site.
The installation process clones the Experience Builder module into web/modules/contrib/experience_builder. Develop and contribute from either location like you would any other Git repo for a normal Drupal project.
Any time you update the Experience Builder module or modify its front-end code, be sure to rebuild the UI app assets:
When developing the React app, make sure to use the HTTPS URL of your DDEV project, then run:
To completely reinstall Drupal and the Experience Builder module, run:
For the full list of available Experience Builder commands, run this:
Updating
Update the Experience Builder module clone just like you would any other Git repo. No tools are currently provided for updating Core.
Cypress
Experience Builder uses Cypress for front-end testing. It is currently only supported on macOS.
Setup
Carefully follow the below XQuartz configuration steps after installing it. Failure to do so will result in frustrating, difficult to debug problems.
Install XQuartz using Homebrew. See also https://www.xquartz.org/.
Configure XQuartz to allow connections from the host:
- Open XQuartz.
- Open Preferences (“XQuartz” > “Settings…” from the menu or
⌘,).
- Go to the “Security” tab.
- Check the “Allow connections from network clients” checkbox.
- Log out and back in or restart your machine for the change to take effect.
Usage
Run Cypress tests interactively:
Run them headlessly:
Run component/unit tests:
- Experience Builder module
- #experience-builder Drupal Slack channel
-
| Background on this add-on: [DDEV support for Cypress tests [#3458369] |
Drupal.org](https://www.drupal.org/project/experience_builder/issues/3458369) |
FAQ & known issues
Can I use Cypress on Linux or Windows?
No, not currently; and there are no plans at present to support it. See Support & community above if you want to make a case for it.
What if Cypress fails to start?
If you get an error like the below when attempting to run Cypress on macOS…
- Confirm that you have carefully followed all the instructions under Cypress.
- See if your Docker provider above requires any special configuration.
If these don’t resolve the issue, see Support & community above.
Cypress failed to start.
This may be due to a missing library or dependency. https://on.cypress.io/required-dependencies
Please refer to the error below for more details.
----------
[2536:0808/191430.352014:ERROR:bus.cc(407)] Failed to connect to the bus: Failed to connect to socket /run/dbus/system_bus_socket: No such file or directory
[2536:0808/191431.055343:ERROR:ozone_platform_x11.cc(240)] Missing X server or $DISPLAY
[2536:0808/191431.055373:ERROR:env.cc(255)] The platform failed to initialize. Exiting.
----------
Platform: linux-arm64 (Debian - 12)
Cypress Version: 13.12.0
Failed to execute command node_modules/.bin/cypress open --browser electron --project .: exit status 1
Failed to run xb-cypress-open ; error=exit status 1
What if I get an HTTPS error?
If this is your first time using DDEV, you may get an error like the following when you try to visit your site. If so, you need to configure your OS and browser to trust the root certificate authority that DDEV uses. See DDEV Installation.
This site can't be reached
The webpage at https://xb-dev.ddev.site/ might be temporarily down or it may have moved permanently to a new web address.
ERR_SSL_UNRECOGNIZED_NAME_ALERT