{"id":17134701,"url":"https://github.com/robojones/gulp-webrequire","last_synced_at":"2026-05-06T23:31:47.586Z","repository":{"id":57147746,"uuid":"113623648","full_name":"robojones/gulp-webrequire","owner":"robojones","description":"Use require in the browser with this gulp plugin.","archived":false,"fork":false,"pushed_at":"2018-03-23T19:09:48.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-22T22:01:45.602Z","etag":null,"topics":["browser","dependencies","gulp","gulpplugin","module","npm","require","sourcemaps","web"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/gulp-webrequire","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robojones.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-08T22:38:59.000Z","updated_at":"2018-03-23T19:09:49.000Z","dependencies_parsed_at":"2022-09-05T16:50:37.584Z","dependency_job_id":null,"html_url":"https://github.com/robojones/gulp-webrequire","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robojones%2Fgulp-webrequire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robojones%2Fgulp-webrequire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robojones%2Fgulp-webrequire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robojones%2Fgulp-webrequire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robojones","download_url":"https://codeload.github.com/robojones/gulp-webrequire/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245025993,"owners_count":20549071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","dependencies","gulp","gulpplugin","module","npm","require","sourcemaps","web"],"created_at":"2024-10-14T19:45:31.819Z","updated_at":"2026-05-06T23:31:42.563Z","avatar_url":"https://github.com/robojones.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gulp-webrequire\n\nUse require in the browser with this gulp plugin.\n\n[![CircleCI](https://circleci.com/gh/robojones/gulp-webrequire.svg?style=shield)](https://circleci.com/gh/robojones/gulp-webrequire)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Installation\n\n```\nnpm install --save gulp-webrequire\n```\n\n## Key features\n- Use __require__ in you client side javascript.\n- Require __NPM modules__.\n- Full __sourcemap__ support with [gulp-sourcemaps](https://npmjs.com/package/gulp-sourcemaps).\n- Dynamic package creation with __smart packing__.\n- __Script tag__ generator.\n\n## Table of contents\n- [How it works](#how-it-works)\n- [Setup with gulp](#setup-with-gulp)\n  - [Project](#project)\n    - [Options](#options)\n    - [Project#through](#projectthrough)\n- [How to find out what script tags need to be added to your HTML](#how-to-find-out-what-script-tags-need-to-be-added-to-your-html)\n  - [generateTags()](#generatetags)\n  - [setup()](#setup)\n  - [Examples](#examples)\n\n## How it works\n\nThe difference between this plugin and other solution like webpack is, that it does not create a single .js file containing all of your code.\nInstead it detects the references between your modules and builds packages out of them using a __smart packing__ algorithm.\n\n__Smart packing?__\n\nThe most important facts are:\n- Every module that is not required by any other module is considered an entry point. You can generate script tags for these entry points later on by using the [api](#how-to-find-out-what-script-tags-need-to-be-added).\n- No module will be included multiple packs. → All files can be cached by the browser and no module will be loaded twice.\n\n__So why should I use this?__\n\nThe advantage of __not packing__ all your code into __one big `.js` file__ is, that you can decide when a resource is loaded.\nSo instead of downloading a whole bunch of JavaScript, where you only need a fraction of it, you can load only what's needed.\nThis lets you take advantage of the browser cache and improves your website performance.\n\n__How is this better than adding script-tags the old-fashioned way?__\n\n`gulp-webrequire` generates script tags with the `async` attribute.\nThis will allow your JavaScript files to be loaded parallely.\nYou don't need to worry about the order in which your scripts are executed - If one of your scripts requires another one,\n`gulp-webrequire` will make sure that the required file is executed first.\nIt is also guaranteed that your scripts will be __executed after the \"DOMContentLoaded\" event__ was emitted.\n\n\n## Setup with gulp\n\nExample with `gulp-webrequire` and `gulp-minify`\n\nIn your `gulpfile.json`:\n\n```javascript\nconst gulp = require('gulp')\nconst minify = require('gulp-minify')\nconst sourcemaps = require('gulp-sourcemaps')\nconst { webrequire } = require('gulp-webrequire')\n\nconst project = webrequire()\n\ngulp.task('javascript', function () {\n  return gulp.src('src/**/*.js')\n    .pipe(sourcemaps.init())\n    .pipe(project.through())\n    .pipe(minify())\n    .pipe(sourcemaps.write())\n    .pipe(gulp.dest('public/'))\n})\n\ngulp.task('default', ['javascript'])\n```\n\n### Project\n\nYou can create a project using the factory:\n\n```javascript\nconst { webrequire } = require('gulp-webrequire')\nconst project = webrequire(options)\n```\n\nOr by using the class directly:\n\n```javascript\nconst { Project } = require('gulp-webrequire')\nconst project = new Project(options)\n```\n\n\n- options\n  - __entryPoints__ `\u003cstring[]\u003e` - Manually add entry points if they are not automatically detected. (In theory you will never have to use this)\n  - __modulesDir___ `\u003cstring\u003e` - Will be used in the sourcemaps as the directory that contains NPM modules that you use in your code. This is purely aesthetic. (Default: `modues/`)\n\n### Project#through()\nThis method returns a stream that you can use in your gulp task to pipe files through. You **must** create a new stream for each gulp task.\n\n```javascript\nconst gulp = require('gulp')\nconst { webrequire } = require('gulp-webrequire')\n\n// Create a project\nconst project = webrequire()\n\ngulp.task('javascript', function () {\n  return gulp.src('src/**/*.js')\n    .pipe(project.through()) // This is where the magic happens.\n    .pipe(gulp.dest('public/'))\n})\n```\n\n## How to find out what script tags need to be added to your HTML\n\nGulp-webrequire comes with an extremely nice api that you can use in your code (e.g. directly in your view engine).\n```javascript\nconst { generateTags, setup } = require('gulp-webrequire')\n\nsetup({ base: 'public/js' })\ngenerateTags(['login.js', 'menu.js'])\n```\n\nThe generateTags method will find all js files that are being imported in the `login.js` and `menu.js` file.\nIt will then return HTML script tags for these files as one big string.\nYour can use the returned string to render it into your website's HTML.\n\n### generateTags()\n\nThis method allows you to generate scripttags for all files that are related to an entry point.\n\n```javascript\nconst { generateTags } = require('gulp-webrequire')\ngenerateTags(entryPoint, options)\n```\n\n- entryPoints `\u003cstring|string[]\u003e` - Entry points to your code relative to the base directory. (The file extension should be set.)\n- options\n  - base `\u003cstring\u003e` - The directory that contains your public javascript files.\n  - tagGenerator `\u003cfunction\u003e` - A function that receives a path and generates a script-tag for it. The path is relative to the base directory and does not begin with a `/`.\n  - cache `\u003cboolean\u003e` - Gulp-webrequire will cache which files are in which packs. To disable this behaviour you can set this option to false. (default: `true`)\n\n### setup()\n\nWith this method you can change default options for the generateTags method.\n\n```javascript\nconst { setup } = require('gulp-webrequire')\nsetup(options)\n```\n\n- options - The same ones that your can set in the [generateTags](#generatetags) method.\n\n### Examples\n\n#### Express \u0026 EJS\n\nYour nodejs app:\n\n```javascript\nconst app = require('express')()\nconst { generateTags, setup } = require('gulp-webrequire')\n\nsetup({\n  base: 'public/js'\n})\n\napp.get('/login', function(req, res){ \n  const tags = generateTags('login.js')\n  res.render('index', {\n    scriptTags: tags\n  })\n})\n\napp.listen(80)\n```\n\nIn your EJS view:\n\n```html\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003eLogin\u003c/title\u003e\n    \u003c%- scriptTags %\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    ...your html...\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n#### Marko view engine\n```marko\n$ var webrequire = require('gulp-webrequire').generateTags;\nhtml\n  head\n    title -- Login\n    -- $!{webrequire('login.js', { base: 'public/js' })}\n  body\n    ...your website...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobojones%2Fgulp-webrequire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobojones%2Fgulp-webrequire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobojones%2Fgulp-webrequire/lists"}