The command-line tool for Druxt, the fully decoupled Drupal and Nuxt framework.
This repository holds two packages:
| Package | What it is |
|---|---|
@druxt/cli |
The CLI. Its binary is drx. |
create-druxt |
npm create druxt. It runs drx init and does nothing else. |
npm create druxt@latest my-site
cd my-site
npx @druxt/cli infoYou will need Node 22.12 or newer to run the CLI. The site it creates has its own requirements, which drx init prints.
| You want to | Run |
|---|---|
| Create a site | npm create druxt@latest [dir] |
| Run any command | npx @druxt/cli <command> |
| Use it in a project | npm install -D @druxt/cli, then drx <command> in a package script or npx drx <command> |
npx drx does not work outside a project that has @druxt/cli installed. Another package holds the name drx on npm, so npx drx downloads that package and not this one. Use npx @druxt/cli.
drx runs on Node 22.12 or later. A site may pin an older Node for itself, as the 0.x starter pins Node 16, and a version manager then switches to it in the site's directory. drx still works there: started on an older Node, it runs the same command again on a newer Node from the machine. It looks beside its own binary first, which is the Node it was installed with, then along PATH, then where mise, nvm, fnm, Volta and asdf keep their installs.
The tools a command starts, such as the site's package manager, come from your own PATH, so the site is installed with the Node it runs on. When the Node you are on is too old, DRX_NODE chooses the newer one: set it to the path of a node binary. A Node that is new enough is used as it is, whatever DRX_NODE says.
Creates a site from a starter in a registry, writes drx.config.json at its root, and prints what the site needs and what to run next.
| Option | What it does | Default |
|---|---|---|
[dir] |
The directory to create the site in | Asked for, or the starter's default with --yes |
--starter <name> |
The starter to create the site from | The registry's default |
--layout <layout> |
monorepo, split or workspace. Only monorepo is available. |
The starter's layout |
--registry <url> |
A starter registry: a URL, or a name from the user configuration | The public registry |
--source <name> |
Where the Druxt packages come from. Only npm is available. |
npm |
--install, --no-install |
Install the site's dependencies after creating it, or do not | Asked for, or no |
--force |
Write into a directory that exists and is not empty | Refuse |
--yes, -y |
Accept the default for everything not given, and ask nothing | |
--json |
Print the result as JSON on stdout |
At a terminal, init asks for the directory, the starter when the registry has more than one, the layout, and whether to install. A flag answers each question, so the command runs unattended:
npx @druxt/cli init my-site --yes --jsonWith no terminal, init uses the defaults and never waits for input. It needs the directory or --yes, and fails with a message saying so when it has neither.
--install runs the install of the package manager the starter declares. For the quickstart starter that is npm install, which also sets up the Drupal backend when PHP and Composer are present. The steps printed under "Next" then leave out what the install ran, so nothing is set up twice.
Prints the versions of the CLI and Node. Inside a project it adds the layout and, for each part, the packages that matter: nuxt and every druxt, druxt-* or @druxt/* package for a Nuxt part, and Drupal core and the Druxt module for a Drupal part. Run it from any directory in the project.
| Option | What it does |
|---|---|
--json |
Print the report as JSON on stdout |
Outside a project it says so and prints the two versions.
Usage for the CLI or one command, and the version.
- The result of a command goes to stdout: text, or one JSON document with
--json. - Progress, warnings, errors and prompts go to stderr.
- A command that fails exits with 1. With
--jsonit also prints{ "ok": false, "error": { "code", "message" } }on stdout.
drx init writes drx.config.json at the root of the site. Later commands find the project by it.
{
"layout": "monorepo",
"line": "0.x",
"starter": "quickstart",
"source": "npm",
"parts": [
{ "role": "frontend", "kind": "nuxt", "path": "nuxt" },
{ "role": "backend", "kind": "drupal", "path": "drupal" }
]
}| Key | What it holds |
|---|---|
layout |
The arrangement of the parts: monorepo, split or workspace |
line |
The Druxt release line |
starter |
The name of the starter the site was created from |
source |
The name of the source its Druxt packages come from |
parts |
Each part of the site: its role (frontend or backend), its kind and its path from the root |
A kind is nuxt or drupal in this version.
A registry is a URL that answers /<name>.json for each starter, in the format giget defines, and /index.json with the names. The public registry is the starters/ directory of this repository.
{
"name": "quickstart",
"tar": "https://codeload.github.com/druxt/quickstart/tar.gz/refs/heads/develop",
"defaultDir": "my-druxt-site",
"url": "https://github.com/druxt/quickstart",
"druxt": {
"line": "0.x",
"layout": "monorepo",
"parts": [
{ "role": "frontend", "kind": "nuxt", "path": "nuxt" },
{ "role": "backend", "kind": "drupal", "path": "drupal" }
],
"requires": {
"node": "16.18.1",
"tools": ["PHP 8.3 or newer with Composer, or DDEV"]
},
"maintained": "2026-11-15",
"default": true,
"steps": ["npm run setup", "npm run dev"],
"install": {
"runs": ["npm run setup"],
"notes": ["npm run dev starts the backend again when it is not running."]
}
}
}name, tar, defaultDir, url, subdir and headers are giget's fields. giget ignores the druxt object, so the same file works with GIGET_REGISTRY=<url> npx giget quickstart.
Key in druxt |
What it holds |
|---|---|
line |
The Druxt release line |
layout |
The layout the starter has |
parts |
The parts of the starter, as in the project configuration |
requires.node |
The Node version the site runs on: a full version, or a major such as 22 |
requires.tools |
What else the site needs, each as a phrase to show the user |
maintained |
The date the starter was last checked to work, as YYYY-MM-DD |
default |
true for the starter init uses when none is named |
steps |
Optional. The commands to run in the new site, in order |
install.runs |
Optional. The steps the install runs itself, left out of "Next" after one |
install.notes |
Optional. Lines printed under "Note" after an install |
index.json is { "starters": ["quickstart"] }.
init checks an entry before it downloads anything, and fails with a message naming the field that is wrong. It warns when the starter was last maintained more than a year ago, and when the running Node is not the one the starter needs.
The package includes a copy of the public registry. When the public registry cannot be read, init uses the copy and says so. A registry you name with --registry is never replaced by the copy.
~/.config/drx/config.json names registries and sources of your own. DRX_CONFIG points at another file, and XDG_CONFIG_HOME is used when it is set.
{
"registries": {
"team": "https://example.com/starters"
},
"sources": {
"next": { "type": "npm", "tag": "next" },
"branch": { "type": "git", "url": "https://example.com/druxt.git", "ref": "main" }
}
}--registry teamreads starters from that URL.GIGET_AUTHis giget's own variable, and giget sends it as a bearer token with every tarball it downloads. The CLI also sends it to a registry you name, and never to the public registry.--sourcetakesnpm,git:<url>#<ref>, or a name defined here. Onlynpmcreates a site in this version. The others are read and answer that they are not available yet.
- The
splitandworkspacelayouts.--layoutaccepts them and fails with a message. - Sources other than
npm. - Adding a module, making a wrapper component and upgrading a site.
- Kinds other than
nuxtanddrupal. - A published public registry. Until this repository is public,
initreads the copy in the package.
See CONTRIBUTING.md.
npm install
npm run build
npm test