Skip to content

Commit 3094e95

Browse files
authored
feat(gulp-browser-sync): add gulp-browser-sync plugin (#18)
* feat(gulp-browser-sync): add initial Browsersync plugin implementation * chore: update pnpm workspace catalog * chore: add `gulp-browser-sync` to packages list in `release-please` configuration * docs: add `gulp-browser-sync` plugin to list * feat(gulp-browser-sync): add TS definitions * chore: rebuild lock-file
1 parent d29d089 commit 3094e95

File tree

10 files changed

+1295
-159
lines changed

10 files changed

+1295
-159
lines changed

README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,10 @@
88
99
## Available Plugins
1010

11-
| Plugin | Version | Description | Downloads |
12-
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
13-
| [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) |
11+
| Plugin | Version | Description | Downloads |
12+
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
13+
| [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) |
14+
| [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) |
1415

1516
Each plugin includes detailed documentation and usage examples in its respective folder.
1617

plugins/gulp-browser-sync/LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 ForWarD Software (https://forwardsoftware.solutions/)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# gulp-browser-sync
2+
3+
> 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.
4+
5+
## Usage
6+
7+
Install this plugin and the required peer dependencies
8+
9+
```sh
10+
$ npm install --save-dev gulp @forward-software/gulp-browser-sync
11+
```
12+
13+
### Setup
14+
15+
```js
16+
import gulp from 'gulp';
17+
import { gulpBrowsersync } from "@forward-software/gulp-browser-sync";
18+
19+
//
20+
// LIVE-RELOAD WEBSERVER
21+
//
22+
const { browserServe, browserReload } = gulpBrowsersync({
23+
host: "0.0.0.0",
24+
port: 8081,
25+
single: true, // Enable SPA-mode
26+
open: false,
27+
ui: false,
28+
server: {
29+
baseDir: PACKAGE_DIRECTORY,
30+
},
31+
});
32+
33+
// watch files for changes and trigger rebuild tasks
34+
async function watchFiles() {
35+
gulp.watch("src/assets/*", gulp.series(buildAssets, browserReload));
36+
gulp.watch(`src/**/*.html`, gulp.series(buildHtml, browserReload));
37+
}
38+
39+
// npm run watch / npx gulp watch: continuously update index.html from deps
40+
export const watch = gulp.series(dist, gulp.parallel(browserServe, watchFiles));
41+
```
42+
43+
## License
44+
45+
MIT
46+
47+
---
48+
49+
Made with ✨ & ❤️ by [ForWarD Software](https://github.com/forwardsoftware) and [contributors](https://github.com/forwardsoftware/gulp-plugins/graphs/contributors)
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
import babel from "@rollup/plugin-babel";
2+
import commonjs from "@rollup/plugin-commonjs";
3+
import resolve from "@rollup/plugin-node-resolve";
4+
import strip from "@rollup/plugin-strip";
5+
import terser from "@rollup/plugin-terser";
6+
import gulp from "gulp";
7+
import { rimraf } from "rimraf";
8+
import { rollup } from "rollup";
9+
10+
const babelConfig = {
11+
babelHelpers: "bundled",
12+
ignore: ["node_modules"],
13+
compact: false,
14+
extensions: [".js"],
15+
presets: [
16+
[
17+
"@babel/preset-env",
18+
{
19+
targets: {
20+
node: "current",
21+
},
22+
},
23+
],
24+
],
25+
};
26+
27+
const debugRollupPlugins = [resolve(), commonjs(), babel(babelConfig)];
28+
29+
const prodRollupPlugins = [resolve(), commonjs(), strip(), babel(babelConfig), terser()];
30+
31+
async function compile(variant) {
32+
const rollupPlugins = variant === "debug" ? debugRollupPlugins : prodRollupPlugins;
33+
const rollupOutputName = variant !== "prod" ? `index.${variant}.js` : `index.js`;
34+
35+
const builder = await rollup({
36+
input: `./src/index.js`,
37+
plugins: rollupPlugins,
38+
external: ["browser-sync"],
39+
});
40+
41+
await builder.write({
42+
file: `./dist/${rollupOutputName}`,
43+
name: "gulp-browser-sync",
44+
format: "esm",
45+
});
46+
}
47+
48+
// Creates ES module bundles
49+
export async function buildFlavors() {
50+
await Promise.all(["debug", "prod"].map(compile));
51+
}
52+
53+
export function copyTSDefinition() {
54+
return gulp
55+
.src("src/**/*.d.ts", { base: "src/", allowEmpty: true, encoding: false })
56+
.pipe(gulp.dest("dist/", { mode: 0o644, dirMode: 0o755 }));
57+
}
58+
59+
// npm run clean / npx gulp clean: clean 'dist' folder
60+
export const clean = () => rimraf("./dist/");
61+
62+
// npm run build / npx gulp build: build plugin
63+
export const build = gulp.series(clean, buildFlavors, copyTSDefinition);
64+
65+
// watch files for changes and trigger rebuild tasks
66+
async function watchFiles() {
67+
gulp.watch("src/**/*.js", buildFlavors);
68+
gulp.watch("src/**/*.ts", buildFlavors, copyTSDefinition);
69+
}
70+
71+
// npm run watch / npx gulp watch: continuously update index.html from deps
72+
export const watch = gulp.series(build, watchFiles);
73+
74+
export default build;
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"name": "@forward-software/gulp-browser-sync",
3+
"version": "1.0.0",
4+
"description": "Custom plugin for gulp toolkit to setup a browser that can be auto-refreshed when files change",
5+
"author": "ForWarD Software (https://forwardsoftware.solutions/)",
6+
"license": "MIT",
7+
"keywords": [
8+
"gulp",
9+
"gulp-plugin",
10+
"gulp-tasks",
11+
"browsersync",
12+
"browser-sync"
13+
],
14+
"homepage": "https://github.com/forwardsoftware/gulp-plugins/tree/main/plugins/gulp-browser-sync#readme",
15+
"bugs": "https://github.com/forwardsoftware/gulp-plugins/issues",
16+
"repository": {
17+
"type": "git",
18+
"url": "git+https://github.com/forwardsoftware/gulp-plugins.git",
19+
"directory": "plugins/gulp-browser-sync"
20+
},
21+
"type": "module",
22+
"exports": "./dist/index.js",
23+
"types": "./dist/index.d.ts",
24+
"files": [
25+
"dist"
26+
],
27+
"scripts": {
28+
"clean": "gulp clean",
29+
"watch": "gulp watch",
30+
"build": "gulp build"
31+
},
32+
"devDependencies": {
33+
"@babel/core": "catalog:",
34+
"@babel/preset-env": "catalog:",
35+
"@rollup/plugin-babel": "catalog:",
36+
"@rollup/plugin-commonjs": "catalog:",
37+
"@rollup/plugin-node-resolve": "catalog:",
38+
"@rollup/plugin-strip": "catalog:",
39+
"@rollup/plugin-terser": "catalog:",
40+
"gulp": "catalog:",
41+
"rimraf": "catalog:",
42+
"rollup": "catalog:"
43+
},
44+
"peerDependencies": {
45+
"gulp": ">=5"
46+
},
47+
"dependencies": {
48+
"browser-sync": "^3.0.4"
49+
}
50+
}
Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import type { Options } from "browser-sync";
2+
import type { TaskFunction } from "gulp";
3+
4+
/**
5+
* Instance of BrowserSync to be used in gulp tasks.
6+
*/
7+
export interface GulpBrowserSyncInstance {
8+
/**
9+
* Initializes and starts the BrowserSync server.
10+
* This task should be used to start the development server.
11+
*
12+
* @param done - Callback function to signal task completion
13+
*/
14+
browserServe: TaskFunction;
15+
16+
/**
17+
* Reloads the browser(s) connected to the BrowserSync server.
18+
* This task should be used to trigger a browser refresh after file changes.
19+
*
20+
* @param done - Callback function to signal task completion
21+
*/
22+
browserReload: TaskFunction;
23+
}
24+
25+
/**
26+
* Setup an instance of BrowserSync to be used in gulp tasks.
27+
*
28+
* @example
29+
```
30+
import { gulpBrowsersync } from "@forward-software/gulp-browser-sync";
31+
32+
const { browserServe, browserReload } = gulpBrowsersync({
33+
host: "0.0.0.0",
34+
port: 8081,
35+
single: true, // Enable SPA-mode
36+
open: false,
37+
ui: false,
38+
server: {
39+
baseDir: PACKAGE_DIRECTORY,
40+
},
41+
});
42+
```
43+
*/
44+
export function gulpBrowsersync(initOptions: Options): GulpBrowserSyncInstance;
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import browserSync from "browser-sync";
2+
3+
export function gulpBrowsersync(initOptions) {
4+
const server = browserSync.create("gulp-browser-sync");
5+
6+
function browserServe(done) {
7+
server.init(initOptions, done);
8+
}
9+
10+
function browserReload(done) {
11+
server.reload();
12+
13+
done();
14+
}
15+
16+
return {
17+
browserServe,
18+
browserReload,
19+
};
20+
}

0 commit comments

Comments
 (0)