DDEV Browsersync

Overview
Installation
Usage
- Auto-start the watcher server
What does this add-on do?
Integrations
Troubleshooting
Credits

Overview

Browsersync is free software that features:

live reloads
click mirroring
network throttling

This add-on allows you to run Browsersync through the DDEV web service.

Installation

To install this add-on, run:

ddev add-on get ddev/ddev-browsersync
ddev restart

After installation, make sure to commit the .ddev directory to version control.

Usage

Command	Description
`ddev browsersync`	Start the watcher
`ddev launch :3000`	Launch the Browsersync page

Examples:

$ ddev browsersync
Proxying Browsersync on https://mysite.ddev.site:3000
[Browsersync] Proxying: http://localhost
[Browsersync] Watching files...

$ ddev launch :3000
# The site should briefly display "Browsersync: connect"
# in the top right corner, confirming it is connect to the server.

Auto-start the watcher server

You can use DDEV’s post-start hook to start the watcher server and launch the page when DDEV starts.

cat <<'EOF' > .ddev/config.browsersync-extras.yaml
hooks:
    post-start:
        - exec-host: bash -c "ddev browsersync &"
        - exec-host: ddev launch :3000
EOF

ddev restart

What does this add-on do?

Checks to make sure the DDEV version is adequate.
Adds .ddev/web-build/Dockerfile.ddev-browsersync, which installs Browsersync using npm.
Adds a browser-sync.js to define the operation of the base setup.
Adds a .ddev/docker-compose.browsersync.yaml, which exposes and routes the ports necessary.
Adds a ddev browsersync shell command, which lets you easily start Browsersync when you want it.

For WordPress projects, this add-on also:

Adds a wp-config-ddev-browser.php file which modifies the WP_HOME and WP_SITEURL values to work with Browsersync.
On install, modifies the wp-config-ddev.php file to include the wp-config-ddev-browser.php file.

Integrations

ddev-browsersync works out of the box for many project types. However, you may want to edit the .ddev/browser-sync.js file to specify exactly what files and directories should be watched. Limiting watched files may reduce hard disk and CPU loads.

Laravel Mix Configuration

Demo: https://github.com/tyler36/browsersync-demo

Update webpack.mix.js

// Use the HOSTNAME provided by DDEV
let url = process.env.DDEV_HOSTNAME;

mix.js('resources/js/app.js', 'public/js')
    .postCss('resources/css/app.css', 'public/css', [
        //
    ])
    .browserSync({
        proxy: "localhost",
        host:  url,
        open:  false,
        ui: false
    });

Start Browsersync service

ddev exec npm run watch
...
[Browsersync] Proxying: http://localhost:3000
[Browsersync] Access URLs:
 ---------------------------------------------------
       Local: http://localhost:3000
    External: http://browsersync-demo.ddev.site:3000
 ---------------------------------------------------

Browsersync will be running on HTTPS at https://browsersync-demo.ddev.site:3000

WordPress Configuration Changes

The changes this add-on makes to the wp-config-ddev.php file during installation can be seen below.

The wp-config-ddev-browserync.php file is included before the /** WP_HOME URL */ comment.

Before:

/** WP_HOME URL */
defined( 'WP_HOME' ) || define( 'WP_HOME', 'https://projectname.ddev.site' );

/** WP_SITEURL location */
defined( 'WP_SITEURL' ) || define( 'WP_SITEURL', WP_HOME . '/' );

After:

/** Include WP_HOME and WP_SITEURL settings required for Browsersync. */
if ( ( file_exists( __DIR__ . '/wp-config-ddev-browsersync.php' ) ) ) {
    include __DIR__ . '/wp-config-ddev-browsersync.php';
}

/** WP_HOME URL */
defined( 'WP_HOME' ) || define( 'WP_HOME', 'https://projectname.ddev.site' );

/** WP_SITEURL location */
defined( 'WP_SITEURL' ) || define( 'WP_SITEURL', WP_HOME . '/' );

Others

There are many other options to integrate Browsersync into your project, including:

Please see Browsersync documentation for more details.

Troubleshooting

No Gateway / 502 error

This error usually occurs when the watcher server is not running. Run ddev browsersync to start the server.

Typo3 No site configuration found / 404 Error

Solution: The base URL (base in the TYPO3 site’s config.yaml (like config/sites/main/config.yaml should specify http even though the frontend is configured for https. This can also be solved by commenting out the default base line.

base: http://examplehost.ddev.site/

Unknown command “browsersync” for “ddev”

:bulb: This add-on moves to a per-project command approach in v2.5.0+. You can safely delete the global ~/.ddev/commands/web/browsersync once you’re on v2.5.0 or higher.

If you run ddev browsersync from a local project and get Error: unknown command "browsersync" for "ddev", please reinstall the add-on.

System limit for number of file watchers reached

This error means the watcher is unable to track all the files it is tasked with watching. You either have to decrease the number of files you’re watching or increase the file watcher limit.

Decrease the number of files you’re watching by updating browser-sync.js:
- Limit the number of files being watch by updating files: [...] section
- Increase the number of ignored files by updating the ignore: [] section
If you use Colima, run colima ssh and sudo sysctl fs.inotify.max_user_watches to see how many watches you have. To increase it, use something like sudo sysctl -w fs.inotify.max_user_watches=2048576. Unfortunately, this has to be done on every Colima restart.
If you use Docker Desktop for Mac, docker run -it --privileged --pid=host justincormack/nsenter1 and sysctl -w fs.inotify.max_user_watches=1048576. Unfortunately, this has to be done again on every Docker restart.
On Docker Desktop for Windows, add or edit ~/.wslconfig with these contents:
[wsl2] kernelCommandLine = "fs.inotify.max_user_watches=1048576"
On Linux, you can change fs.inotify.max_user_watches on the host in /etc/sysctl.d/local.conf or elsewhere.

Credits

PRs for install steps for specific frameworks are welcome.

Contributed and maintained by @tyler36