Introducing Runners: A new feature to automate your Browsersync workflows

[shakyShane]

This is your opportunity to feedback on an upcoming feature: Runners.

It's not released yet, but it will be soon!

Runners gives you a way to deterministically interact with the running instance of Browsersync by building up pipelines of commands/npm scripts followed by optionally dispatching actions to browsers.

Why?

I've had countless situations in the past few years where I need a bit of automation/task running/file-watching, but I don't want to construct a webpack/vite/gulp setup. For prototypes especially, but also just for situations where you don't have the 'conventional' frontend stack.

Tools already included

Because Browsersync already has a very robust file-watching mechanism and is event-driven at it's heart, it's a natural fit to start to include features for running tasks too.

This is in no way an attempt to contribute/compete with the vast array of tools/workflows/bundlers already out there. Instead, this is just a convenience for those Browsersync users that may not need anything more than a bit of task co-ordination and especially if those tasks typically result in wanting to reload the browser, or inject files into pages.

Examples

Imagine you have a particular npm script that you know needs to be executed before your development environment is up and running: with Runners you can encode this logic directly into your Browsersync options:

bs.init({
    server: "./public",
    runners: [
        {
            at: "startup",
            run: [
                { npm: ["clean", "build"] }
            ]
        }
    ]
})

On it's own, this doesn't seem to offer much more than just using npm run clean && npm run build && browser-sync - but now consider a situation where you want to run that build command every time a particular file changes too:

bs.init({
    server: "./public",
    runners: [
        {
            at: "startup",
            run: [
                { npm: ["clean", "build"] }
            ]
        },
        {
            at: "runtime",
            when: [ { files: ["styles/css.css", "index.html"] } ],
            run: [
                { npm: "build" },
                { bs: "reload" },
            ]
        }
    ]
})

Note how { bs: "reload" } is at the end of the chain there. This is a special runner that allows you to control Browsersync in exactly the order you need. Previously you just had to hope you were watching the correct files and that the change would be picked up at the correct time... no more!

Tailwind Example

This is great example of where you might want a bit of task automation, but you don't want to bring in dedicated tools like gulp/webpack/vite - sometimes you just want to run some commands following a file change. With Runners you can now construct your own little dedicated pipelines:

{
  "name": "tailwind-example",
  "scripts": {
    "build": "tailwindcss -i base.css -o ./dist/output.css",
    "clean": "rm -rf dist/**"
  },
  "devDependencies": {
    "tailwindcss": "^3.3.2"
  }
}

bs.init({
    server: ".",
    open: false,
    notify: false,
    runners: [
        {
            at: "startup",
            run: [{ npm: ["clean", "build"] }]
        },
        {
            at: "runtime",
            files: ["index.html"],
            run: [{ npm: ["build"] }, { bs: "reload" }]
        }
    ]
});

Unrelated files example

A major limitation of the way Browsersync currently works is that it tightly couples file changes to assets in the browser. For example, if you are 'watching' the dist folder in your project, and Browsersync sees 'styles.css' change, it will attempt to live-reload that single file.

This model breaks when changed files don't match 1:1 for the files you want to inject into the page.

With Runners, you can be very specific about these scenarios, here's an example where a scss file change will cause all CSS files in the page to be live-reloaded. This would be relevant in situations where scss files are compiled on the fly

bs.init({
    proxy: "localhost:8000",
    runners: [
        {
            at: "runtime",
            when: { files: ["sass/**"] },
            run: [{ bs: "inject", files: "*.css" }]
        }
    ]
});

You can read that as follows:

• at runtime, when anything within sass/** changes, ask Browsersync to inject all CSS files in the page.

Summary

This feature is coming very soon and it will NOT add any new dependencies - we already have all the mechanisms we need to enable it.

I'd now love to hear your stories! What situations can you think of that would benefit from these deterministic pipelines of commands?

🙏🏻