feat(gulp-browser-sync): add gulp-browser-sync plugin

README.md

@@ -8,9 +8,10 @@
 
 ## Available Plugins
 
-| Plugin                           | Version                                                                                                                                     | Description                                                                                                        | Downloads                                                                                                                                      |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| [gulp-sharp](plugins/gulp-sharp) | [![NPM Version](https://img.shields.io/npm/v/%40forward-software%2Fgulp-sharp)](https://www.npmjs.com/package/@forward-software/gulp-sharp) | High-performance image processing using the Sharp library. Supports resizing, format conversion, and optimization. | [![npm downloads](https://img.shields.io/npm/dm/@forward-software/gulp-sharp.svg)](https://www.npmjs.com/package/@forward-software/gulp-sharp) |
+| Plugin                                         | Version                                                                                                                                                   | Description                                                                                                        | Downloads                                                                                                                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [gulp-browser-sync](plugins/gulp-browser-sync) | [![NPM Version](https://img.shields.io/npm/v/%40forward-software%2Fgulp-browser-sync)](https://www.npmjs.com/package/@forward-software/gulp-browser-sync) | Setup a browser that can be auto-refreshed when files change using [Browsersync](https://browsersync.io/) library. | [![npm downloads](https://img.shields.io/npm/dm/@forward-software/gulp-browser-sync.svg)](https://www.npmjs.com/package/@forward-software/gulp-browser-sync) |
+| [gulp-sharp](plugins/gulp-sharp)               | [![NPM Version](https://img.shields.io/npm/v/%40forward-software%2Fgulp-sharp)](https://www.npmjs.com/package/@forward-software/gulp-sharp)               | High-performance image processing using the Sharp library. Supports resizing, format conversion, and optimization. | [![npm downloads](https://img.shields.io/npm/dm/@forward-software/gulp-sharp.svg)](https://www.npmjs.com/package/@forward-software/gulp-sharp)               |
 
 Each plugin includes detailed documentation and usage examples in its respective folder.
 

plugins/gulp-browser-sync/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ForWarD Software (https://forwardsoftware.solutions/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/gulp-browser-sync/README.md

@@ -0,0 +1,49 @@
+# gulp-browser-sync
+
+> Custom plugin for [gulp](https://gulpjs.com/) toolkit to setup a browser that can be auto-refreshed when files change using [Browsersync](https://browsersync.io/) library.
+
+## Usage
+
+Install this plugin and the required peer dependencies
+
+```sh
+$ npm install --save-dev gulp @forward-software/gulp-browser-sync
+```
+
+### Setup
+
+```js
+import gulp from 'gulp';
+import { gulpBrowsersync } from "@forward-software/gulp-browser-sync";
+
+//
+// LIVE-RELOAD WEBSERVER
+//
+const { browserServe, browserReload } = gulpBrowsersync({
+  host: "0.0.0.0",
+  port: 8081,
+  single: true, // Enable SPA-mode
+  open: false,
+  ui: false,
+  server: {
+    baseDir: PACKAGE_DIRECTORY,
+  },
+});
+
+// watch files for changes and trigger rebuild tasks
+async function watchFiles() {
+  gulp.watch("src/assets/*", gulp.series(buildAssets, browserReload));
+  gulp.watch(`src/**/*.html`, gulp.series(buildHtml, browserReload));
+}
+
+// npm run watch / npx gulp watch: continuously update index.html from deps
+export const watch = gulp.series(dist, gulp.parallel(browserServe, watchFiles));
+```
+
+## License
+
+MIT
+
+---
+
+Made with ✨ & ❤️ by [ForWarD Software](https://github.com/forwardsoftware) and [contributors](https://github.com/forwardsoftware/gulp-plugins/graphs/contributors)

plugins/gulp-browser-sync/gulpfile.mjs

@@ -0,0 +1,74 @@
+import babel from "@rollup/plugin-babel";
+import commonjs from "@rollup/plugin-commonjs";
+import resolve from "@rollup/plugin-node-resolve";
+import strip from "@rollup/plugin-strip";
+import terser from "@rollup/plugin-terser";
+import gulp from "gulp";
+import { rimraf } from "rimraf";
+import { rollup } from "rollup";
+
+const babelConfig = {
+  babelHelpers: "bundled",
+  ignore: ["node_modules"],
+  compact: false,
+  extensions: [".js"],
+  presets: [
+    [
+      "@babel/preset-env",
+      {
+        targets: {
+          node: "current",
+        },
+      },
+    ],
+  ],
+};
+
+const debugRollupPlugins = [resolve(), commonjs(), babel(babelConfig)];
+
+const prodRollupPlugins = [resolve(), commonjs(), strip(), babel(babelConfig), terser()];
+
+async function compile(variant) {
+  const rollupPlugins = variant === "debug" ? debugRollupPlugins : prodRollupPlugins;
+  const rollupOutputName = variant !== "prod" ? `index.${variant}.js` : `index.js`;
+
+  const builder = await rollup({
+    input: `./src/index.js`,
+    plugins: rollupPlugins,
+    external: ["browser-sync"],
+  });
+
+  await builder.write({
+    file: `./dist/${rollupOutputName}`,
+    name: "gulp-browser-sync",
+    format: "esm",
+  });
+}
+
+// Creates ES module bundles
+export async function buildFlavors() {
+  await Promise.all(["debug", "prod"].map(compile));
+}
+
+export function copyTSDefinition() {
+  return gulp
+    .src("src/**/*.d.ts", { base: "src/", allowEmpty: true, encoding: false })
+    .pipe(gulp.dest("dist/", { mode: 0o644, dirMode: 0o755 }));
+}
+
+// npm run clean / npx gulp clean: clean 'dist' folder
+export const clean = () => rimraf("./dist/");
+
+// npm run build / npx gulp build: build plugin
+export const build = gulp.series(clean, buildFlavors, copyTSDefinition);
+
+// watch files for changes and trigger rebuild tasks
+async function watchFiles() {
+  gulp.watch("src/**/*.js", buildFlavors);
+  gulp.watch("src/**/*.ts", buildFlavors, copyTSDefinition);
+}
+
+// npm run watch / npx gulp watch: continuously update index.html from deps
+export const watch = gulp.series(build, watchFiles);
+
+export default build;

plugins/gulp-browser-sync/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@forward-software/gulp-browser-sync",
+  "version": "1.0.0",
+  "description": "Custom plugin for gulp toolkit to setup a browser that can be auto-refreshed when files change",
+  "author": "ForWarD Software (https://forwardsoftware.solutions/)",
+  "license": "MIT",
+  "keywords": [
+    "gulp",
+    "gulp-plugin",
+    "gulp-tasks",
+    "browsersync",
+    "browser-sync"
+  ],
+  "homepage": "https://github.com/forwardsoftware/gulp-plugins/tree/main/plugins/gulp-browser-sync#readme",
+  "bugs": "https://github.com/forwardsoftware/gulp-plugins/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forwardsoftware/gulp-plugins.git",
+    "directory": "plugins/gulp-browser-sync"
+  },
+  "type": "module",
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "gulp clean",
+    "watch": "gulp watch",
+    "build": "gulp build"
+  },
+  "devDependencies": {
+    "@babel/core": "catalog:",
+    "@babel/preset-env": "catalog:",
+    "@rollup/plugin-babel": "catalog:",
+    "@rollup/plugin-commonjs": "catalog:",
+    "@rollup/plugin-node-resolve": "catalog:",
+    "@rollup/plugin-strip": "catalog:",
+    "@rollup/plugin-terser": "catalog:",
+    "gulp": "catalog:",
+    "rimraf": "catalog:",
+    "rollup": "catalog:"
+  },
+  "peerDependencies": {
+    "gulp": ">=5"
+  },
+  "dependencies": {
+    "browser-sync": "^3.0.4"
+  }
+}

plugins/gulp-browser-sync/src/index.d.ts

@@ -0,0 +1,44 @@
+import type { Options } from "browser-sync";
+import type { TaskFunction } from "gulp";
+
+/**
+ * Instance of BrowserSync to be used in gulp tasks.
+ */
+export interface GulpBrowserSyncInstance {
+  /**
+   * Initializes and starts the BrowserSync server.
+   * This task should be used to start the development server.
+   *
+   * @param done - Callback function to signal task completion
+   */
+  browserServe: TaskFunction;
+
+  /**
+   * Reloads the browser(s) connected to the BrowserSync server.
+   * This task should be used to trigger a browser refresh after file changes.
+   *
+   * @param done - Callback function to signal task completion
+   */
+  browserReload: TaskFunction;
+}
+
+/**
+ * Setup an instance of BrowserSync to be used in gulp tasks.
+ * 
+ * @example
+  ```
+  import { gulpBrowsersync } from "@forward-software/gulp-browser-sync";
+
+  const { browserServe, browserReload } = gulpBrowsersync({
+    host: "0.0.0.0",
+    port: 8081,
+    single: true, // Enable SPA-mode
+    open: false,
+    ui: false,
+    server: {
+      baseDir: PACKAGE_DIRECTORY,
+    },
+  });
+  ```
+ */
+export function gulpBrowsersync(initOptions: Options): GulpBrowserSyncInstance;

plugins/gulp-browser-sync/src/index.js

@@ -0,0 +1,20 @@
+import browserSync from "browser-sync";
+
+export function gulpBrowsersync(initOptions) {
+  const server = browserSync.create("gulp-browser-sync");
+
+  function browserServe(done) {
+    server.init(initOptions, done);
+  }
+
+  function browserReload(done) {
+    server.reload();
+
+    done();
+  }
+
+  return {
+    browserServe,
+    browserReload,
+  };
+}