{"id":13659859,"url":"https://github.com/letorbi/tarp.require","last_synced_at":"2025-12-12T03:08:19.420Z","repository":{"id":7024367,"uuid":"8296827","full_name":"letorbi/tarp.require","owner":"letorbi","description":"A lightweight \u0026 asynchronous JavaScript loader for CommonJS and NodeJS modules.","archived":false,"fork":false,"pushed_at":"2024-09-13T09:58:08.000Z","size":307,"stargazers_count":116,"open_issues_count":3,"forks_count":27,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-02T12:07:04.048Z","etag":null,"topics":["commonjs","javascript","module-loader"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/letorbi.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":"2013-02-19T18:48:07.000Z","updated_at":"2025-02-19T02:02:35.000Z","dependencies_parsed_at":"2022-09-13T08:40:52.870Z","dependency_job_id":null,"html_url":"https://github.com/letorbi/tarp.require","commit_stats":null,"previous_names":["flowyapps/smoothie"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letorbi%2Ftarp.require","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letorbi%2Ftarp.require/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letorbi%2Ftarp.require/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/letorbi%2Ftarp.require/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/letorbi","download_url":"https://codeload.github.com/letorbi/tarp.require/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045230,"owners_count":21038553,"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":["commonjs","javascript","module-loader"],"created_at":"2024-08-02T05:01:13.052Z","updated_at":"2025-12-12T03:08:13.805Z","avatar_url":"https://github.com/letorbi.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"**Important notice:** Tarp.require is the replacement of [Smoothie](https://github.com/letorbi/tarp.require/tree/smoothie).\nIt introduces a number of new features and improvements, so it is recommended to use Tarp.require from now on. Please\nread [the migration documentation](https://github.com/letorbi/tarp.require/blob/master/doc/migration.md) for further\ninformation.\n\n//\\ Tarp.require - a lightweight JavaScript module loader\n=========================================================\nTarp.require is a CommonJS and Node.js compatible module loader licensed as open source under the LGPL v3. It aims to be\nas lightweight as possible while not missing any features.\n\n*Tarp.require has finally reached a stable state. This means that the version 1.x branch will only receive bugfixes from\nnow on. An improved version of Tarp.require with new features and breaking changes can be found in the tarp2-branch.*\n\n## Features\n\n* **Compatible** NodeJS 9.2.0 and CommonJS modules 1.1\n* **Plain** No dependencies, no need to compile/bundle/etc the modules\n* **Asynchronous** Non-blocking loading of module files\n* **Modern** Makes use of promises and other features (support for older browsers via polyfills)\n* **Lightweight** Just about 180 lines of code (incl. comments), minified version is about 2kB\n\n### Browser compatibility\n\n* Firefox 29+\n* Chrome 33+\n* Edge 12+\n* Safari 7.1+\n* iOS Safari 8+\n* Android Browser 4.4.4+\n* Opera 20+\n* Internet Explorer 10+ (with [URL polyfill](https://github.com/lifaon74/url-polyfill) and [ES6 Promise polyfill](https://github.com/lahmatiy/es6-promise-polyfill))\n\n## Installation\n\nThe easiest way to install Tarp.require is via NPM:\n\n```\n$ npm install --save @tarp/require\n```\n\nIf you don't want to use NPM you can just clone the repository directly or add it to your git repository as a submodule:\n\n```\n$ git submodule add https://github.com/letorbi/tarp.require.git\n```\n\n## Usage\n\nAssuming you've installed Tarp.require in the folder *//example.com/node_modules/@tarp/require* and your HTML-document\nis located at *//example.com/page/index.html*, you only have to add the following lines to your HTML to load the script\nlocated at *//example.com/page/scripts/main.js* as your main-module:\n\n```\n\u003cscript src=\"/node_modules/@tarp/require/require.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003eTarp.require({main: \"./scripts/main\"});\u003c/script\u003e\n```\n\nInside your main-module (and any sub-module, of course) you can use `require()` as you know it from CommonJS/NodeJS.\nAssuming you're in the main-module, module-IDs will be resolved to the following paths:\n\n  * `require(\"someModule\")` loads *//example.com/page/node_modules/someModule.js*\n  * `require(\"./someModule\")` loads *//example.com/page/scripts/someModule.js*\n  * `require(\"/someModule\")` loads *//example.com/someModule.js*\n\nNote that global modules are loaded from *//example.com/page/node_modules* and not from *//example.com/node_modules*.\nThis is because the default global module path is set to `['./node_modules']` and is derived from the location of the\npage that initializes Tarp.require.\n\n## Synchronous and asynchronous loading\n\nTarp.require supports synchronous and asynchronous loading of modules. If you load Tarp.require like described above and\nuse only simple require calls you won't have to care about anything: Just write `require(\"someModule\")` and Tarp.require\nwill try to load the module and all its sub-modules asynchronously.\n\nHowever, there might be occasions where you have to force Tarp.require to load a module synchronously. This is possible,\nbut you should try to avoid this, because synchronous requests might block the loading process of your page and are\ntherefore [marked as obsolete](https://xhr.spec.whatwg.org/#the-open()-method) by now.\n\nKeep also in mind that synchronous loading of a module prevents the pre-loading of its sub-modules. You have to\nexplicitly load a sub-module asynchronously to re-start the pre-loading.\n\n### What modules can be pre-loaded?\n\nRight now only plain require-calls are pre-loaded. This means that the ID of the module has to be one simple string.\nAlso require-calls with more than one parameter are ignored.\n\n**Example:** If a module has been loaded asynchronously and contains the require calls `require(\"Submodule1\")`,\n`require(\"Submodule2\", true)` and `require(\"Submodule\" + \"3\")` somewhere in its code, only *Submodule1* will be\npre-loaded, since the require-call for *Submodule2* has more than one parameter and the module-ID in the require-call\nfor *Submodule3* is not one simple string.\n\n### Enforce synchronous or asynchronous loading\n\nSynchronous or asynchronous loading of a module can be enforced by adding a boolean value as a second\nparameter to the require-call:\n\n```\n// explicit synchronous loading\nvar someModule = require(\"someModule\", false);\nsomeModule.someFunc();\n\n // explicit asynchronous loading\nrequire(\"anotherModule\", true).then(function(anotherModule) {\n    anotherModule.anotherFunc();\n});\n```\n\n## Path resolving\n\nTarp.require mainly resolves URLs in the same way as Node.js does resolve paths. The only difference is that\nTarp.require won't look for a file at other locations if it cannot be found at the resolved URL. This decision has been\nmade due to the fact that modules are usually loaded from a remote server and sending multiple request for different\nlocations would be very time-consuming. Tarp.require relies on the server to resolve unknown files instead.\n\n### HTTP redirects\n\nTarp.require is able to handle temporary (301) and permanent (303) HTTP redirects. A common case where redirects might\nbe handy is to return the contents of *index.js* or *package.json* if an ID without a filename is requested. The\nfollowing NGINX configuration rule will mimic the behavior of NodeJS:\n\n```\nlocation ~ ^(/node_modules/.*)\\.(?:js|json)$  {\n    if ( -f $request_filename ) {\n        break;\n    }\n    if ( -f \"${document_root}$1/index.js\" ) {\n        return 301 \"$1/index.js\";\n    }\n    if ( -f \"${document_root}$1/package.json\" ) {\n        return 301 \"$1/package.json\";\n    }\n    return 404;\n}\n```\n\nThis will redirect all requests like */node_modules/someModule* to */node_modules/someModule/package.json*, if\n*/node_modules/someModule* is a directory and if */node_modules/someModule/package.json* is a file. If that file doesn't\nexist, the request will be redirected to */node_modules/path/index.js*. If both files don't exist, a \"404 Not Found\"\nresponse will be sent.\n\nNote: HTTP redirects won't work in IE11 due to limited support of XMLHttpRequest advanced features.\n\n### NPM packages\n//\nThe loading of a NPM package is the only occasion when Tarp.require might redirect a request on its own. Tarp.require\nload a module-ID specified the `main` field of a *package.json* file, if the following checks are true:\n\n 1. The *package.json* file is loaded via a redirect (like explained in the section above)\n 2. The response contains a valid JSON object\n 3. The object has a property called `main`\n\nIf that is the case a second request will be triggered to load the modules specified in `main` and the exports of\nthat module will be returned. Otherwise simply the content of *package.json* is returned.\n\n### The `module.paths` property\n\nTarp.require always uses the first item of the global `paths` array to resolve an URL from a global module-ID.  Unlike\nNode.js it won't iterate over the whole array. Since the global config is always used, any change to `module.paths`\nwon't affect the loading of modules.\n\nTarp.require also supports the `require.resolve.paths()` function that returns an array of paths that have been searched\nto resolve the given module-ID.\n\n## Options\n\n### Change the global module path\n\nIf your modules are not located at *./node_modules/*, you can tell Tarp.require their location via the `paths` option:\n\n```\nTarp.require({main: \"./scripts/main\", paths: [\"/path/to/node/modules\"]});\n```\n\n### Override path resolver\n\nIf you need a more sophisticated path resolver, you can override the default function that resolves a module-id to the\naccording URL:\n\n```\nTarp.require({main: \"./scripts/main\", resolver: function(id, pwd, resolve) { ... }});\n```\n\nThe parameter `id` is the module-id of the module that shall be loaded, `pwd` is the path of the module `require()` is\ncalled from and `resolve` points to the build-in path-resolver function (you might want to call this).\n\nKeep in mind that a custom path-resolver may break NodeJS or CommonJS compatibility, if not implemented\nproperly.\n\n### Change the document root path\n\nThe document root path is used to resolve relative paths inside the `paths` array. It points to `location.href` by\ndefault. You have to set the document root path explicitly, if you want to use Tarp.require inside a web-worker that has\nbeen loaded from a blob.\n\n```\nTarp.require({main: \"./scripts/main\", root: \"/path/to/page/\"});\n```\n\n### Using `require()` directly in the HTML-document\n\nIt is not recommended to load other modules than the main-module directly from your HTML-document. However, if you\nreally want to use `require()` directly in the HTML-document, you can add `Tarp.require` to the global scope:\n\n```\nTarp.require({expose: true});\n```\n\nKeep in mind that a require-call in the HTML-document will load a module synchronously unless you explicitly load it\nasynchronously by adding `true` as a second parameter.\n\n### Load the main-module synchronously\n\nIf you really need to load the main-module synchronously, you can do it by loading Tarp.require with the\nfollowing options:\n\n``` Tarp.require({main: \"./scripts/main\", sync: true}); ```\n\n----\n\nCopyright 2013-2020 Torben Haase \\\u003c[https://pixelsvsbytes.com](https://pixelsvsbytes.com)\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletorbi%2Ftarp.require","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fletorbi%2Ftarp.require","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fletorbi%2Ftarp.require/lists"}