require() node_modules, js, css, html, and json in the browser with as little effort as loading jquery. (No building, compiling, etc required).
Simply serve the clientside-require.js file to a browser and enjoy one of life's greatest pleasures, npm modules, in the browser:
<script src = "/path/to/clientside-require.js"></script>
<script>
var promise_request = load("clientside-request") // loads the `clientside-request` npm package
var promise_utility = load("/path/to/utility.js") // loads a custom js script without poluting global scope
</script>If the npm package you are loading contains require() statements, the clientside-require module's load method will automatically resolve (i.e., load) each dependency before loading the script - enabling the require() statement in the load()'ed script.
For example, /path/to/utility.js can contain require('relevant-npm-module'), require('./another_utility.js'), or require('./configuration.json').
npmmodules in the browser (i.e., reusability!)- the package looks in the
node_modulesfolder for module_names
- the package looks in the
- easy importing of static content (e.g., js, html, image, etc)
- e.g.,
require('path/to/whatever') - supports relative and absolute paths
- e.g.,
- importing JS files does not pollute global scope
- each js file has its own global scope
- content is explicitly exported (CommonJS format - like used in Node.js)
module.exports= ...
- all imported content (load and require) is stored in the same cache and is only loaded once
Short Version: require() is available to load()'ed scripts.
See this explanation for the long version.
- install the module
npm install clientside-require --save
- load the module into your page
<script src = "node_modules/clientside-require/dist/bundle.js"></script>
- copy the
/dist/bundle.jsfile to your server - load it as any other script
<script src = "path/to/clientside-require/dist/bundle.js"></script>
If you intend to use node modules, please read this configuration detail to ensure the module works in all contexts. Otherwise, everything is setup by default already.
This package enables utilizing npm for clientside development. The node modules you npm install all the time can be utilized out of the box:
load("qs") // asynchronously load a node module by module name; module was installed with `npm install qs`
.then((qs)=>{
var query_string = qs.stringify({foo:bar}); // foo=bar
})or
load("color-name")
.then((color_name)=>{
console.log(color_name.blue); // outputs [0, 0, 255]
})In addition, you can load your own JS content into the browser without polluting the global scope:
load("./util.js") // require a js file with a relative path
.then((exports)=>{
exports.awesome_functionality(); // where `exports` is defined by `model.exports` in `util.js`
})Further we can import any file type (e.g., js, json, html, css, txt, etc):
load("/path/to/config.json") // get contents of a json file file with an absolute path
.then((html)=>{
console.log(html)
})If we load a JS script with load(), we can use require() statements (in addition to load() statements) in the script. This allows us to write functionality just as we would on the serverside with node.js:
random_name_generator.js:
var list_of_names = require("./list_of_names.json");
var random_selector = require("./random_selector.js");
var random_name = random_selector.select(list_of_names);
module.exports = random_name;index.html:
load("/path/to/random_name_generator.js")
.then((random_name)=>{
console.log(random_name)
})Creating a view element with clientside-view-loader
This uses the clientside-view-modal-login_signup npm package. Use the repo as an example for how you can create your own view module!
npm install clientside-view-modal-login_signupload("clientside-view-loader")
.then(view=>view.load("clientside-view-modal-login_signup").generate())
.then((dom)=>{
document.body.appendChild(dom); // append the dom to the document body
dom.show("login"); // display the login view
})generates a fully functional one of these:
Browsers do not permit dynamic synchronous loading as it as it ruins user experience. The only way to dynamically load a file into a web page requires asynchronous operations. The load method loads content in this way and returns a promise that resolves with the requested content.
When a script is load()'ed, we give it the require() method as the clientside-require module reads the file in advance, loads all of the require()'ed dependencies, and only after loading the dependencies does it load the target script. By doing so, all of the dependencies are available by the time the script needs them.
This allows us, after load()ing, to use the synchronous require() function in the browser.
All require'ed modules are cached to eliminate duplicate requests. The require function is injected into loaded scripts (e.g., module scripts) so that the cache is maintained in every file and module loaded.
The request argument in require(request) and load(request) expects an absolute path, a relative path, or a node_module name.
For the following examples, lets assume the following directory structure:
awesome_directory/
awesome_file.js
awesome_helper.js
node_modules/
clientside-view-loader/
root.html
Absolute paths operate exactly as one would expect. A request to retrieve the file will be sent directly to that path.
// inside `root.html`
require("/awesome_directory/awesome_file.js")
.then((exports)=>{/* ...magic... */})Relative paths operate exactly like you would expect, too! The require() function utilizes the clientside-require to keep track of the path to each file its loaded in.
Not only can you do this:
// inside `root.html`
require("./awesome_directory/awesome_file.js")
.then((exports)=>{/* ...magic... */})But inside awesome_directory/awesome_file.js, which is eventually loaded by root.html, we can do this:
// inside awesome_directory/awesome_file.js
require("./awesome_helper.js")
.then((helper_exports)=>{ /* ... use the other scripts for even more magic ... */ })The require(request) function will assume any request that does not start with "/" and has no file extension is a node_module name. It will:
- find the root of the
node_moduleby utilizing thenode_module_root - parse the
package.jsonfile to find themainscript - load the main script
The require() loader is capable of loading html, css, json, txt, and js. Notably for js we load the contents of the script without polluting the global scope.
The content returned from a js file is what is included in the module.exports object. This is in line with what one would expect with if they worked with node modules.
The way that the clientside-require imports js enables the user to protect the global scope. By loading the script into an iframe and extracting the module.exports object from the iframe we protect the global scope from any global variable definitions that may exist in the target js script.
As there is no way to provide scoping for css, css is loaded directly into the main window with global scope.
By default, the clientside-require expects the node_modules directory to be in the same directory as the file it is loaded in e.g.:
node_modules/
this_file.html
in this case (above) it will work by default.
If your node_modules is not in the same directory as the file that the clientside-require is loaded you, e.g.:
node_modules/
a_directory/
this_file.html
you will need to define the path to the node_modules directory by defining window.node_modules_root, e.g.:
window.node_modules_root = '/../node_modules' // if node_modules is in parent directory of this file's directoryThis must be defined before you load the clientside-require script.
Note, scope goes two ways. Not only does the namespace that you load not enter the main window, the namespace of the main window does not enter the namespace that you load. E.g., the clientside-require passes a reference to console so that it can output to the main window console and not an unreachable console.
npm packages written for the browser utilizing clientside-require:
- clientside-view-loader
- clientside-view-button
- clientside-request - mimics the npm
requestpackage for the browser