Nuxt frontend and Drupal backend, built with Druxt.
This repository is the source of druxtjs.org, the documentation site for Druxt. It is also a working example of a Druxt site: its pages are Drupal content, rendered by Nuxt.
The site is two applications in one repository. nuxt/ is the frontend. It
renders the documentation with Druxt, through DruxtEntity and its wrapper
components. drupal/ is the Drupal 11 backend that editors write in.
Run the whole site on your machine, frontend and backend together. Pick one of three ways.
| Way | You need |
|---|---|
| Dev container | VS Code with Dev Containers, GitHub Codespaces, or DevPod |
| mise | mise, and three PHP extensions |
| By hand | PHP 8.3 or later, Composer and Node 16.20.1 |
| Tool | How |
|---|---|
| VS Code | Clone the repository, open it, then choose Reopen in Container |
| GitHub Codespaces | On the repository page, open Code and choose Codespaces |
| DevPod | Click the badge, or run devpod up https://github.com/druxt/druxtjs.org |
The container has Node 16.20.1, PHP 8.4, Composer and mise. Creating it runs
npm install and npm run setup, so Drupal is running when it opens. Then run
npm run dev.
.mise.toml pins Node 16.20.1 and PHP 8.4. PHP needs the gd, pdo_sqlite
and sodium extensions.
mise install
npm install
npm run setup
npm run devInstall PHP 8.3 or later with the gd, pdo_sqlite and sodium extensions,
Composer, and Node 16.20.1. Then run:
npm install
npm run setup
npm run dev| Command | What it does |
|---|---|
npm install |
Installs the root tooling and enables the git hooks |
npm run setup |
Installs Drupal on a throwaway SQLite database and imports the documentation from druxt.js. Then it starts Drupal |
npm run dev |
Starts the Nuxt dev server against that Drupal. The first run installs the frontend's packages |
npm run login |
Prints a one-time login link for Drupal |
| Service | Address |
|---|---|
| Drupal | http://127.0.0.1:8888, or the next free port. npm run info shows which |
| Nuxt | http://localhost:3000 |
npm run setup writes Drupal's address to .env, and npm run dev reads it
from there. Setup needs network access, for Composer packages and the pinned
documentation on GitHub.
- Run
npm run login, and open the link it prints. - In Drupal, go to Content and edit a page, or add one. The layout paragraphs editor builds a page from sections of text, code and images.
- Save, then reload the page on http://localhost:3000.
Preview, on the edit form, shows unsaved changes. docs/backend.md explains its tabs.
An edit made here is local to this machine's database: it previews and tests the site, and is not how page text is published. See Where changes go for what belongs where.
The Modules, API reference and Components pages come from the druxt.js
packages. npm run docs:generate builds them locally, in the pinned druxt.js
checkout. It installs and builds druxt.js first, so the first run is slow.
| Change | Where it goes |
|---|---|
| The content model, the editor or the site's settings | Export them with vendor/bin/drush config:export in drupal/, and commit drupal/config/sync/ in a pull request |
| The frontend | A pull request with the change in nuxt/ |
| The text of a page | Drupal, where editors change it. The database is the source of truth, and page text is not taken as a pull request yet |
The site's content is stored in its database, and npm run setup seeds that
database from a pinned commit of druxt.js. Edits in your local Drupal stay
local.
nuxt/ is a Nuxt 2 app built with Druxt, and it is written to be read as an example of a Druxt site.
| What | How |
|---|---|
| Pages | Each section page resolves its path with the Druxt router, then renders the Drupal page with <DruxtEntity mode="full">. |
| Wrappers | nuxt/components/druxt/ holds the wrapper components Druxt finds by name. The page is entity/node/DocPageFull.vue, with one component per paragraph type in entity/paragraph/. The rest are fields (field/), layout sections (layout-paragraph/), blocks (block/), block regions (block-region/) and menus (menu/). |
| Display settings | druxt-schema reads Drupal's view and form displays when the app builds, so the frontend follows the display settings editors change in Drupal. |
| Layout | druxt-layout-paragraphs renders the page's layout sections. |
| Header, sidebar and footer | druxt-blocks renders the blocks placed in the druxtjs theme's regions in Drupal. The theme and the site's name and logo come from the druxtjs_org consumer's decoupled settings, read at build by nuxt/modules/decoupled-settings. |
| UI | nuxt/components/dui/ holds presentational components with no Drupal dependency: code blocks, diagrams, rich text and columns. They will move to the shared Druxt UI library. |
| Playground | nuxt/components/global/DruxtExample.vue renders any Druxt component under a runtime of its own for the chosen backend (nuxt/utils/druxt-runtime.js), with what it knows about each component in nuxt/utils/live-examples.js. The same card sits on the module and component reference pages. |
To change how something looks, find the wrapper name Druxt looked for (the Vue devtools show it), and add a component at the matching path under nuxt/components/druxt/. Component resolution explains the naming.
The site runs on Lagoon as one environment, Drupal beside Nuxt. Nuxt serves pre-rendered pages first, and renders live any page it has not stored or that has aged past its time to live. docs/hosting.md covers what a deployment does.
| Command | What it does |
|---|---|
npm run setup |
Install and import the backend, then start it |
npm run dev |
Nuxt dev server against the backend |
npm run storybook |
Storybook on port 3030, against the backend |
npm run start / stop |
Start or stop Drupal |
npm run info |
Where Drupal is, and the versions it runs |
npm run login |
One-time login link for Drupal |
npm run docs:generate |
Build the Modules, API reference and Components pages |
npm run lint |
Every linter except prose |
npm run lint:prose |
Vale, after npm run lint:prose:install once |
npm test |
Node tests for the scripts and the frontend's modules |
See CONTRIBUTING.md for commit messages, checks and what never goes in a file. Open issues and pull requests on druxt/druxtjs.org. docs/backend.md covers the importer and page history.