Recipes

A recipe installs or sets up a tool in a project. Each recipe shows the steps before it runs them, and shows the output while it runs.

Run a recipe

1. Click Recipes at the right end of the project tab bar. The Recipes panel opens.
2. Click a recipe card. The dialog shows the steps.
3. Click Proceed. The dialog goes back to the top, so you see the first step and its output.

A recipe continues to run when you close the dialog or the panel, or go to a different tab or project. While a recipe runs, the Recipes button shows a spinner. The card shows the state:

Badge	Meaning
Running	The recipe runs now. Click the card to see the steps and the live output.
Finished	The recipe is complete. Click the card to see the result and next steps.
Failed	The recipe stopped with an error. Click the card to see the output.

The Finished or Failed badge stays until you open the dialog and close it. A notification also shows when a recipe ends.

A recipe cannot run two times at the same time. While it runs, the dialog does not show Proceed.

The panel has two groups:

Group	Recipes	State
This project	The recipes that apply to this project. They run in this project only.	For each project
This computer	Upgrade DDEV, Whisper CLI, whisper-server and ffmpeg. They install tools for all projects.	The same in all projects

Each recipe declares the projects that it applies to, for example DDEV projects, PHP projects in DDEV or Laravel projects in DDEV. The panel does not show a recipe that does not apply. For example, a .NET project does not show the DDEV and PHP recipes. The panel also does not show NPM Dependencies when the project has no package.json, or Sail to DDEV when the project has no Sail compose file. If no recipe applies, the This project group shows a short line that tells you so.

The PHP recipes (Rector, Rector Laravel, Laravel Upgrade, Prettier PHP and Laravel Pint) show only for PHP projects that run in DDEV. Support for PHP projects outside DDEV is in progress.

The app does not keep the recipe state after a restart.

Some recipes show next steps and links when they finish. A card with a green check shows that the recipe has nothing left to do. When you click this card, the dialog does not open. A notification tells you that the tool is already installed or set up. Additional Database is different: its card opens the dialog, so you can change the database name.

Before you run a recipe that changes project files, commit your work. Then review the recipe's changes with git diff or in Git › Changes. See Git Changes.

Available recipes

Addons

Enable or disable DDEV add-ons for the project. See Services & Addons.

NPM Dependencies

Runs npm outdated and lists the outdated packages. The recipe shows only when the project has a package.json.

Cloudflare Tunnel

Share your local site on a public URL through Cloudflare Tunnel. The recipe installs the parts that the project does not have yet:

1. cloudflared. On macOS, the recipe installs it with Homebrew.
2. The ddev-share-cf add-on, with ddev add-on get davo20019/ddev-share-cf. The add-on is installed for each project.

The project must be running. After the recipe, click Share on the project page, or run ddev share-cf. If the project does not have the add-on, Share shows how to install it. Click Or install from Recipes > Cloudflare Tunnel to open this recipe.

Rector

Installs rector/rector with Composer (--dev) and creates rector.php. Needs PHP 7.2 or later. Not available if rector.php exists.

Rector Laravel

Installs driftingly/rector-laravel with Composer (--dev).

Laravel Upgrade

Reads the Laravel version from composer.json and upgrades the code one major version, for example from Laravel 10 to 11. It runs vendor/bin/rector process with the rector-laravel set of the next version on app, bootstrap/app.php, config, database, routes and tests. It supports Laravel 8 to 13. Install Rector and Rector Laravel first. The recipe does not change composer.json. Update laravel/framework and run composer update yourself.

Prettier PHP

Installs prettier and @prettier/plugin-php, creates or updates .prettierrc, and adds PHP to the Prettier settings in .vscode/settings.json.

Laravel Pint

Installs laravel/pint with Composer (--dev) and creates pint.json with the laravel preset. Not available if pint.json exists.

Whisper CLI, whisper-server and ffmpeg

Install the tools for Voice-to-Text. Voice-to-Text does not need this recipe, because whisper-server is part of DevWorkspace Pro. ffmpeg converts audio. It installs with brew (macOS), choco (Windows) or apt-get (Linux).

Upgrade DDEV

Upgrade DDEV to the latest release and remove the Docker images of older DDEV versions. The recipe asks DDEV (ddev self-upgrade) how it was installed, then:

1. Stops all projects (ddev poweroff).
2. Runs the upgrade command for your install method, for example brew upgrade ddev/ddev/ddev or the DDEV install script. If the upgrade needs administrator rights, macOS asks for your password. On Linux and WSL, run the command that the recipe shows in a terminal, then run the recipe again.
3. Removes old DDEV images (ddev delete images -y) to free disk space.
4. Starts the projects that were running before.

When DDEV is up to date, the card shows a green check. Click the card, then click Remove old images in the notification to remove the images of older DDEV versions.

When a new DDEV release is available, a notification tells you. Click Upgrade to open this recipe, or skip that version.

Additional Database

Create another database in your DDEV project, for example a separate database for tests. Enter a name (letters, numbers and underscores). The recipe:

1. Writes a script to .ddev/commands/web/create_additional_database.sh.
2. Adds the script as a DDEV post-start hook in .ddev/config.yaml.

Run ddev restart after the recipe. DDEV then creates the database, and creates it again on each ddev start. The recipe supports MySQL, MariaDB and PostgreSQL. The project must be running. The Database card on the Overview tab lists the additional databases. See Database.

Sail to DDEV

Move a Laravel Sail project and its data to DDEV. The recipe converts the project in place: when the data is in DDEV, it removes the Sail containers and volumes of the project. The recipe shows for Laravel projects that do not use DDEV and that have a compose file with a laravel.test service that is built from a Sail runtime.

When you open the recipe, it checks the computer first. The checks run at the same time:

Check	What it needs
Docker	Docker is installed and running, and docker compose up --wait works.
DDEV	DDEV is installed and has the commands that the recipe uses (ddev add-on get, ddev config --web-environment-add).
bash and gzip	The recipe runs in bash. On Windows, use WSL 2.
Sail data	The Sail database (and MongoDB) container or volume exists.
Database version	DDEV supports the database version that Sail runs. The recipe asks DDEV which versions it supports.
Ports	No other program uses the ports that DDEV needs for Vite (5172 and 5173). Ports that this Sail project uses are free when the recipe stops Sail.
Disk	The disk has space for the database dump.
Hostname	The project hostname resolves. If it does not, DDEV adds it to the hosts file. On macOS, the recipe asks for your password. On Linux, run the ddev hostname command that the recipe shows.

Each failed check shows how to fix it. Convert to DDEV stays disabled until all checks pass. Click Check again after you fix a problem.

The dialog shows only the steps that the recipe does:

1. Copies .env (and the Vite config, if the recipe changes it) to the temporary folder .sail-to-ddev-backup/. Git ignores this folder.
2. Dumps the database from the Sail container to .sail-to-ddev-backup/database.sql.gz (MySQL, MariaDB or PostgreSQL), and records the list of tables and the row counts of small tables.
3. Dumps MongoDB to .sail-to-ddev-backup/mongodb.archive.gz and records the list of collections, if the project has a MongoDB service.
4. Stops Sail.
5. Runs ddev config with the PHP version, the database type and version, and the Node.js version of the Sail setup.
6. Installs the DDEV add-ons for the Sail services, for example Redis, Memcached, MongoDB, Meilisearch, Typesense, RabbitMQ and Selenium.
7. Configures Vite, if vite.config.js has the standard Laravel shape. The recipe exposes port 5173 in DDEV and sets VITE_DEV_SERVER_ORIGIN in the DDEV web container from the project URL that ddev describe shows. The Vite config uses the DDEV server settings only when this variable is set.
8. Starts DDEV and imports the database with ddev import-db.
9. Restores the MongoDB dump into the MongoDB service that ddev describe shows, and sets MONGODB_URI in .env to it.
10. Removes the Sail-only keys from .env, for example APP_PORT, FORWARD_DB_PORT, WWWUSER and WWWGROUP.
11. Checks the data in DDEV. The tables (and MongoDB collections) in DDEV must be the same as in Sail, and the row counts of small tables must match.
12. Removes the Sail containers and volumes of this project with docker compose down -v --remove-orphans, then removes .sail-to-ddev-backup/. The recipe does this only after the data check passes. It does not change the compose file, the docker/ folder or vendor/laravel/sail, because they are project code. It does not remove Docker images.
13. Opens the project as a DDEV project.

The recipe does not do other tasks, for example copy the data of other services or a second database service. Do these tasks yourself.

When the recipe finishes, the project runs in DDEV, and the Sail containers and temporary files are gone.

If a step fails, the recipe stops and does not remove Sail. Sail is stopped, and its containers and data stay. .sail-to-ddev-backup/ also stays: it has the dumps, the files from before the conversion, and RESTORE.txt with the commands to run the project with Sail again. If the data check fails, the error lists the tables or collections that are missing or different. Fix the problem and run the recipe again.

Request a recipe

Open an issue on GitHub and describe the task you want to automate.

Troubleshooting

• The recipe is not available. Click the card. The dialog tells you why, for example a missing dependency or a project that is not running. When the tool is already set up, for example a config file exists, the card shows a green check and a notification tells you.