Create a new project

Local setup with ddev

For setting up a new project, you may want to use the lupus-decoupled-project template, which supports both Gitpod cloud environments and local docker-based development environments via

Prerequisites: ddev & docker

ddev is a ridiculously simple setup for complex development environments, based upon docker compose.


Launch it

To spin up the project locally run:

  git clone
  cd lupus-decoupled-project
  ddev start
  ddev composer install
  ddev drush site-install -y --account-pass=admin --site-name='lupus_decoupled' standard
  ddev drush pm-enable lupus_decoupled, services_env_parameter -y
  # Configure lupus-decoupled frontend base URL
  ddev drush config:set lupus_decoupled_ce_api.settings frontend_base_url -y
  # Login and get started adding some test-nodes
  ddev drush user-login

When using ddev locally, the URLs are by default:

Once you are up and running, try adding some content nodes and menu items to see it working and continue with your first steps

ddev configuration


If you want to customize URLs, take a look at the .ddev/config.yaml file and re-run ddev start.

Frontend repository

By default, the nuxt3-demo frontend repository is used. It can be customized by setting the FRONTEND_REPOSITORY via ddev config:

  # Configure a different frontend repository.
  ddev config --web-environment-add="FRONTEND_REPOSITORY="


Custom setup

If preferred, you can incorporate the pieces in your custom setup and/or setup everything from scratch by following the next steps.

Setting up Drupal

If you don't have an existing Drupal installation yet, or you want to start from scratch, install Drupal first:

composer create-project drupal/recommended-project drupal-project
cd drupal-project

If you do not have composer installed, see the official composer installation instructions.

Continue with the Drupal installation, e.g. by using Drupal's quick start command:

php ./web/core/scripts/drupal quick-start standard

The quick-start command uses PHP's built-in webserver to run your site. Just keep it running after installation.

If you prefer a full local development setup based upon docker, check the Local development guide.

Add drush - the Drupal cli:

composer require drush/drush
# If no global drush launcher is already in use, run
alias drush=$PWD/vendor/bin/drush

Adding Lupus Decoupled Drupal

The Lupus Custom Elements renderer module lets Drupal provide an API backend rendering custom elements. Add the module and its dependencies, then enable the module via the UI or if installed, via drush.

composer config minimum-stability beta
composer require drupal/lupus_decoupled:@beta
drush en lupus_decoupled -y
drush user-login

Test your installation by opening - when logged in, you should see a JSON response with the following content property:

<drupal-markup>Welcome to your custom-elements enabled Drupal site!</drupal-markup>

Setting up Nuxt.js

npx nuxi@latest init <project-name>
pnpm dlx nuxi@latest init <project-name>

Answer the questions as preferred, generally the defaults work fine. Once the project is created, you can remove the example components.

For further details, please refer to the official Nuxt installation docs.

Adding the Nuxt connector module

Please refer to the Setup steps then continue below.

Run nuxt

Ready to go! Start testing by running Nuxt in development mode:

npm run dev
yarn dev
pnpm dev

Now, when accessing the nuxt dev server (e.g. at http://localhost:3000/) you should see a naked page rendered, having the "Home" breadcrumb and the message shown to logged-out users on the frontpage: "You are not authorized to access this page."

Connecting the dots

In your Drupal backend, set the URL of your frontend site, either via UI or via console:

  drush config:set lupus_decoupled_ce_api.settings frontend_base_url http://localhost:3000 -y