How to Fix 11ty BrowserSync Not Working: Quick Developer Guide

You’re all set to build something awesome with 11ty. Your site runs, your files are neat, and you hit that magic npm start. But wait. Nothing reloads. You’re adding content, refreshing… and nothing happens. Sounds like BrowserSync has ghosted you.

TLDR:

If BrowserSync isn’t working in 11ty, it’s likely because of a config error, missing dependencies, or watching the wrong files. Make sure you’re running eleventy –serve or using an up-to-date config. Try clearing your cache and watching your output directory. Below are the most common causes of the problem and how to fix them fast.

1. First, Check Your 11ty Version

BrowserSync comes built-in with 11ty, but older versions may have bugs or outdated dependencies.

Run npx @11ty/eleventy --version to check your version.
If it’s lower than 1.0, update it: npm install @11ty/eleventy@latest

It’s a simple check that can save you hours of rabbit hole googling. Updating might just solve it all.

2. Are You Running the Right Command?

This sounds silly, but trust us—it gets everyone at least once.

You probably ran npx @11ty/eleventy.
To activate BrowserSync, you need: npx @11ty/eleventy --serve

That --serve flag is what turns on the BrowserSync server. Without it, your site builds but won’t auto-refresh.

3. Check If Your Files Are Being Watched

BrowserSync watches for file changes in your output directory. If it’s not watching the right files, reloads won’t happen.

Look at your .eleventy.js config file. Make sure you’re using the correct input and output folders:


module.exports = function(eleventyConfig) {
  return {
    dir: {
      input: "src",
      output: "_site"
    }
  };
};

If your project writes to another directory, make sure that path matches exactly what BrowserSync is watching.

4. You Might Need to Reset the Cache

Sometimes, things get stuck. Especially if you’ve switched between versions or made big config changes.

Stop your dev server.
Delete the .cache or .eleventy_cache folders if they exist.
Clear node_modules with rm -rf node_modules and then npm install

Then run npx @11ty/eleventy --serve again. Fresh start. Feels good, right?

5. Too Many Custom Scripts?

Are you running 11ty behind a custom script like npm run dev? That script might be missing the --serve flag.

Open your package.json and look for this:


"scripts": {
  "dev": "eleventy --serve"
}

If you don’t see --serve there, add it. Then run npm run dev again.

6. Something’s Blocking the Port

BrowserSync usually runs on port 8080 or 3000. If something else is using that port, BrowserSync might not start up properly.

Try this:

Shut down other apps that might grab those ports (like other servers or localhost apps)
In your .eleventy.js, you can even set a custom port:


eleventyConfig.setBrowserSyncConfig({
  port: 9000
});

This can dodge port conflicts and save you from mysterious “site not loading” errors.

7. Check for Errors in the Terminal

Sometimes, BrowserSync crashes silently. Scroll up in your terminal and look for clues.

Missing files?
Typo in a config?
Permission errors?

9 times out of 10, the fix is right there. But if the logs scroll out of view, just re-run the command to get a fresh look.

8. Watch Your Templates (And Other Eleventy Files)

By default, Eleventy watches files like .md, .njk, and .liquid. But if you’re using custom extensions or folders, those might be ignored.

To make 11ty aware of them, add this in .eleventy.js:


module.exports = function(eleventyConfig) {
  eleventyConfig.addWatchTarget("./src/js/");
  eleventyConfig.addWatchTarget("./src/css/");
};

This tells BrowserSync: “Hey, keep an eye on these too!”

9. HTML Output Still Not Updating?

Even with BrowserSync running, if your templates don’t regenerate, then your HTML won’t change.

Here’s a checklist:

Are you saving files inside the input directory?
Are your templates using valid syntax?
Did you disable passthroughCopy but still expect static files?

Try a fresh save on a template file. If that doesn’t rebuild the output, something is broken in the config.

10. Debug Mode for the Win

Need more info? Run 11ty in debug mode to get extra logging:


DEBUG=Eleventy* npx @11ty/eleventy --serve

You’ll see what 11ty is watching, building, and loading. Great for catching subtle issues.

11. Still Not Working? Reinstall Everything

When all else fails, wipe it clean and reinstall. Here’s the nuclear fix:


rm -rf node_modules
rm package-lock.json
npm cache clean --force
npm install

Yes, it’s a pain. But this reset solves the weirdest voodoo config ghosts.

12. Bonus: Use a Plugin for Better Dev Experience

Want a stronger dev setup? Try the eleventy-dev-server plugin. It gives you more control and is easier to debug.


npm install --save-dev @11ty/eleventy-dev-server

Then in your .eleventy.js file:


module.exports = function(eleventyConfig) {
  return {
    pathPrefix: "/",
    templateFormats: ["njk", "md", "html"],
    dir: {
      input: "src",
      output: "_site"
    },
    serverOptions: {
      port: 3001,
      showAllHosts: true
    }
  }
}

This gives you more fine-tuned control over how files get served and watched.

Final Thoughts

BrowserSync is a powerful tool, but small missteps can block it. Whether it’s wrong paths, ports, or configs, the fix is probably simpler than you think.

When in doubt: update Eleventy, double-check your --serve flag, and don’t be afraid to clean things up. Add logs, watch files deliberately, and keep your config clear.

Now get back to building that beautiful static site—now with sweet auto reloads!