{"id":23377969,"url":"https://github.com/beyondjs/uimport","last_synced_at":"2025-11-10T02:02:12.644Z","repository":{"id":41119011,"uuid":"467553680","full_name":"beyondjs/uimport","owner":"beyondjs","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-16T21:50:13.000Z","size":773,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-20T11:12:56.133Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/beyondjs.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-03-08T14:48:49.000Z","updated_at":"2025-09-08T19:04:46.000Z","dependencies_parsed_at":"2024-12-21T18:33:49.886Z","dependency_job_id":"6bb50746-5d59-4aaa-a32b-a9a7ebe67ee1","html_url":"https://github.com/beyondjs/uimport","commit_stats":{"total_commits":82,"total_committers":3,"mean_commits":"27.333333333333332","dds":0.2682926829268293,"last_synced_commit":"a100eec1d6725c67814d5a9931c28d30ff2ab463"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/beyondjs/uimport","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondjs%2Fuimport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondjs%2Fuimport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondjs%2Fuimport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondjs%2Fuimport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beyondjs","download_url":"https://codeload.github.com/beyondjs/uimport/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyondjs%2Fuimport/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283609759,"owners_count":26864222,"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","status":"online","status_checked_at":"2025-11-10T02:00:06.292Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-12-21T18:33:37.864Z","updated_at":"2025-11-10T02:02:12.634Z","avatar_url":"https://github.com/beyondjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UImport\n\n\u003e Convert NPM packages (ex: react, vue, d3, ...) into fresh ESM, locally!\n\nImport them in any ESM environment (browser, Node.js v14+, Deno, etc).\n\n![Consuming react as a local package](./readme/example.png 'Consuming react as a local package').\n\n# How it works\n\n```bash\nnpm install -g uimport\n```\n\n-   UImport uses [esbuild](https://esbuild.github.io/api/#build-api) to generate the pre-packaged version of the bundle,\n    and to obtain the metafile information of the package/subpath required to analyze the dependencies, esbuild is\n    written in Go and it performs 10-100x faster than other bundlers written in javascript.\n\n-   UImport does not install the packages, but instead requires the packages to be installed in the working directory\n    before calling it.\n\n## Bundles\n\nWe define as `bundles` to the ES modules generated from the packages or the subpaths of the packages.\n\nBy instance\n\n\u003e `react` is a package that does not define subpaths, so react is a bundle.\n\u003e\n\u003e `svelte` is a package that does define subpaths, so `svelte/internal` or `svelte/store` are bundles of the same svelte\n\u003e package.\n\n## Subpaths\n\nUImport generates the packages considering the subpaths specified in the `.exports` property of the package.json.\nSpecifying the `.exports` property of the package.json is a best practice for separating the package into independently\nunits of code.\n\n```javascript\n// The following two EM modules belong to the same package (svelte)\nimport 'svelte/internal';\nimport 'svelte/store';\n```\n\nWhen uimport generates a bundle, and finds a dependency on a subpath of a package that does not specify the .exports\nproperty, then uimport will not split the code, but rather include the code in the requested bundle.\n\nUnfortunately, there is a wide variety of packages that do not follow such specific criteria. Many of them were created\nbefore the .exports property of package.json existed, and were generally intended to work with bundlers like webpack,\nand not to be consumed directly from a browser or deno.\n\n## Local server\n\nYour application can consume the bundles through a local server provided by uimport, by running:\n\n```bash\nuimport server --port=8080 --cwd=working_directory\n```\n\n### Resources URLs\n\n#### Load the package at the version specified in the package.json.\n\n```javascript\nimport 'http://localhost:port/package_name.js';\nimport 'http://localhost:port/package_name/subpath.js';\n```\n\n#### Load the exact version of the package\n\nWe recommend importing packages by specifying their version.\n\n```javascript\nimport 'http://localhost:port/package_name@version.js';\nimport 'http://localhost:port/package_name@version/subpath.js';\n```\n\nAlthough an application uses a specific version of a package (according to what is specified in the package.json of your\napp), the packages have in turn its own dependencies and there could be version conflict among packages.\n\nUImport generates by default the dependencies of the packages according to the version that each of them requires. This\nway, if your app specified a dependency (ex: dep_a@2.0.0) in the package.json, but then another dependency requires\ndep_a@1.0.0, uimport will be able to generate both.\n\n## API\n\nUImport will look into the node_modules folder to find the package to be bundled. You can optionally specify the current\nworking directory where node_modules resides.\n\n```javascript\nconst uimport = require('uimport');\nconst bundle = 'react';\nconst { code, errors, warnings, dependencies } = await uimport(bundle);\n```\n\n```javascript\n// mode can be 'esm', 'sjs', or 'amd'\nconst { code, errors, warnings, dependencies } = await uimport(bundle, mode, specs);\n```\n\n-   specs:\n\n```typescript\ninterface specs {\n\tcwd?: string; // The working directory where the local NPM modules are installed\n\ttemp?: string; // A required folder to save temporary files. Default: join(cwd, '.uimport/temp')\n\tcache?: string; // Bundles are saved in cache. Default: join(cwd, '.uimport/cache');\n\tdependencies?: boolean; // Build the dependencies of the bundle or not\n}\n```\n\n```typescript\ninterface output {\n\tcode: string;\n\terrors?: string[];\n\twarnings?: string[];\n\tdependencies?: string[];\n}\n```\n\n# Pre-generated bundles and static resources\n\nNPM packages were born essentially in order to host packages to be consumed by nodejs applications. Its use has spread\nand currently the packages hosted on NPM can be consumed by environments such as the Browser or Deno thanks to CDNs such\nas skypack, jsdelivr, jspm, unpkg.\n\nHowever, package compatibility is dependent on a process of packaging and converting to ES modules. In the future this\ncould change, simply if the authors specify in the package.json the input to the pre-built ES modules.\n\nUImport currently skips the bundle generation process if it finds the uimport property in the package.json.\n\n## UImport property\n\nPackage.json example:\n\n```json5\n{\n\tname: 'your-package',\n\tuimport: {\n\t\tbundles: {\n\t\t\t'./store': './store/index.js'\n\t\t}\n\t}\n}\n```\n\n```typescript\ninterface uimport {\n\tbundles: Record\u003cstring, string\u003e;\n\tassets: Record\u003cstring, string\u003e;\n}\n```\n\nWhere:\n\n-   `.bundles` Specifies the ES module to be returned for each entry point.\n-   `.assets` Similar to the .bundles property, but defining general purpose files such as images.\n\n# About uimport\n\nUImport was created and it is being maintained by the [BeyondJS](https://www.npmjs.com/package/beyond) team. BeyondJS is\nan open source fullstack universal typescript framework, based on a modular project creation design where each project\ncan be published (or not) in NPM packages that can in turn be universally consumed by any ESM environment.\n\n## Motivation\n\nWe have observed that CDNs like skypack, jsdelivr, jspm or unpkg, as well as frameworks like vite are implementing their\nown NPM package packaging strategy. We believe that there should be an open source solution that should be easy to use\nand embraced by the developer community.\n\nWe have seen that the results of packages generated by CDNs in multiple cases vary. In some cases, some packages\ndirectly return an error on one CDN, and the processed code on another CDN.\n\nCDNs are very important in our opinion. They can for example speed up the web thanks to the cross site cache. More and\nmore client libraries emerge (such as vue, svelte, react, etc), they are widely used, but generally hosted individually\nin each project.\n\n# Feedback and collaboration\n\n-   If you know of an alternative solution to `uimport`, please let us know.\n-   If `uimport` is useful to you, maybe you can collaborate with us to join efforts.\n\n\u003e [hello@beyondjs.com](mailto:hello@beyondjs.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyondjs%2Fuimport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeyondjs%2Fuimport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyondjs%2Fuimport/lists"}