@theme-tools/plugin-browser-sync NPM

Browser Sync Plugin for Theme Tools

Theme core plugins let you easily pass in configuration and get a set of Gulp-ready task functions back that have sensible defaults and work well together.

Getting Started

Requirements

Gulp 4 installed with npm install --save gulp@4

Install

npm install @theme-tools/plugin-browser-sync --save

Configure

The config that is passed in is merged with config.default.js. We suggest starting with config.simple.js to get started:

cp node_modules/@theme-tools/plugin-browser-sync/config.simple.js config.browser-sync.js

Setup

Add this to your gulpfile.js:

const gulp = require('gulp');
const config = {};
config.browserSync = require('./config.browser-sync.js');
const browserSyncTasks = require('@theme-tools/plugin-browser-sync')(config.browserSync);

gulp.task('serve', browserSyncTasks.serve);

Details

Tasks

These tasks are methods inside browserSyncTasks from the above code example. You can run them anyway you can run a function, though they are often ran via Gulp. All tasks take a callback function as the first and only parameter that will run when the task is done - exactly how gulp.task(), gulp.parallel(), and gulp.series() want.

`browserSyncTasks.serve()` - Create server

Create server using Browser Sync.

`browserSyncTasks.reload()` - Reload the page

Probably not needed. Wraps .reload() so you can just fire it or pass in a string or array of strings of paths of files to reload which can allow CSS files to get injected.

Configuration

All configuration is deep merged with config.default.js.

`baseDir`

Type: Object | String | Boolean Default: ./

Where to serve static files from. Disabled when domain is set. Passed to browser-sync's server where lots of extra config info can be found.

`domain`

Type: String Default: null

If you have local hosting already going and you want to use BrowserSync's proxy, then set your local domain here (ie mysite.dev). Having this set disables the static server. Passed to browser-sync's proxy.

`startPath`

Type: String Default: ''

The path shown when the URLs are shown in the Terminal. If you have Pattern Lab going, it's nice to have pattern-lab/public set.

`watchFiles`

Type: Array<String> Default: []

Files to watch that will trigger a reload; css files will try to be injected (as long as they are brought using <link> and not <style>@import</style>). Passed to browser-sync's files.

`openBrowserAtStart`

Type: Boolean Default: false

If the browser(s) should open at the start.

`browsers`

Type: Array<String> Default: [ 'Google Chrome' ]

If openBrowserAtStart, then which browsers to open.

`tunnel`

Type: Boolean Default: false

Tunnel the Browsersync server through a random Public URL like -> http://randomstring23232.localtunnel.me. Great for showing to other people remotely or testing sites on Browser Stack. Passed to browser-sync's tunnel.

`port`

Type: Number Default: 3050

The port to use (i.e. http://localhost:3050). If the port is taken, it will increment by one and use that port so you can have multiple instances running if needed.