nestarz/heritage

Tiny Package Manager for the Web

heritage

Tiny Package Manager for the Web based on the WICG/import-maps spec. No lock-in.

• Depends only on two packages, acorn for AST parsing and node-fetch to request packages.
• Customize to any registry, CDN or filesystems... It's up to you
• Default to Pika and Unpkg registries
• Only retrive ES6 browser compatible assets and modules
• TypeScript definition resolution can be achieve using yarn/npm
• Easy-to-use

Use

1. Install Heritage

yarn add -D @eliaspourquoi/heritage

2. Manage Dependencies, feels like Yarn...

# Add Dependencies
heritage add three three/examples/jsm/loaders/GLTFLoader.js [email protected] react react-dom es-module-shims

# Remove Dependencies
heritage remove vue

# Install Dependencies
heritage       

3. Add the generated import-map.json to your index.html.

<script type="importmap" src="web_modules/import-map.json"></script>

4. Optional. For now you may need to polyfill the WICG/import-maps spec. Here a working example:

heritage add es-module-shims

<script defer src="web_modules/es-module-shims/0.4.6/es-module-shims.js"></script>
<script type="importmap-shim" src="web_modules/import-map.json"></script>
<script type="module-shim">
  import React from "react"; // If you have installed react for example...
</script>

That's all.

Information

Heritage use package.json to register required packages under the webDependencies field, exactly like Snowpack. The lock file is the generated import-map.json used to manage imports by the browser. Default use of the the Pika CDN and fallback to Unpkg if target not found.

To have the command heritage available you need to have yarn binor npm bin in your PATH like so:

export PATH=$(yarn bin):$PATH

Otherwise you need to use this command ./node_modules/.bin/heritage from the root of your package.

Custom Registry

Place a heritage.config.js at the root of your project using this API:

module.exports = [{
  registryName<String>,
  entrypoint<Function>: (name: String, target: String, version: String) => String,
  resolveImport<Function>: (importValue: String) => <Object {
    pkgName<String>,
    pkgTarget<String>,
    pkgVersion<String>,
  }>,
  exists<Function>: (name: String, target: String, version: String) => <Boolean>,
  version<Function>: (name: String, target: String, version: String) => <String>,
  source<Function>: (entrypoint: String) => <String>,
 },
 ...
];

You can see the Pika Registry Resolver here https://github.com/nestarz/heritage/blob/master/src/registries/pika.js

heritage's Issues

Installation of dependency `es-module-shims` fails

Hi @nestarz

First I want to congratulate you, for such a great idea on package management, I saw your post on reddit an immediately started to play around with heritage. I'm writing a post on import maps and included a section dedicated to heritage.

As the title says the installation of es-module-shims fails, this is the only dependency I've installed that give me problems.

I'm working with node version v14.5.0 and yarn

I'm doing the following

npx heritage add es-module-shims

Which trows the error

Heritage Package Manager
Installing [email protected] from pika registry.
(node:18925) UnhandledPromiseRejectionWarning: SyntaxError: Unexpected token (1:3)
    at Parser.pp$4.raise (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:2927:15)
    at Parser.pp.unexpected (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:698:10)
    at Parser.pp.semicolon (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:675:66)
    at Parser.pp$1.parseExpressionStatement (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:1154:10)
    at Parser.pp$1.parseStatement (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:889:26)
    at Parser.pp$1.parseTopLevel (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:755:23)
    at Parser.parse (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:555:17)
    at Function.parse (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:578:37)
    at Object.parse (/media/diego/Windows/Users/diego/Documents/Web Development/WebComponents/heritage/node_modules/acorn/dist/acorn.js:5143:19)
    at detective (file:///media/diego/Windows/Users/diego/Documents/Web%20Development/WebComponents/heritage/node_modules/@eliaspourquoi/heritage/src/walker.js:76:21)
(Use `node --trace-warnings ...` to show where the warning was created)
(node:18925) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 2)
(node:18925) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Any hints on why it might be failing?
Has it happened to you?

Thanks in advance.

Installation of multiple versions of a package

I'm trying to understand why heritage sometimes installs multiple version of a package. When I install prosemirror-inputrules with heritage (after completely deleting web_modules):

$ rm -Rf web_modules
$ npx heritage add prosemirror-inputrules
Heritage Package Manager
Installing [email protected] from pika registry.

I get this in my import-map.json:

{
  "imports": {
    "prosemirror-inputrules": "./prosemirror-inputrules/1.1.3/prosemirror-inputrules.js"
  },
  "scopes": {
    "./prosemirror-inputrules/1.1.3/": {
      "prosemirror-state": "./prosemirror-state/1.3.4/prosemirror-state.js",
      "prosemirror-transform": "./prosemirror-transform/1.3.3/prosemirror-transform.js",
      "prosemirror-model": "./prosemirror-model/1.15.0/prosemirror-model.js",
      "orderedmap": "./orderedmap/1.1.1/orderedmap.js"
    },
    "./prosemirror-state/1.3.4/": {
      "prosemirror-model": "./prosemirror-model/1.15.0/prosemirror-model.js",
      "prosemirror-transform": "./prosemirror-transform/1.3.3/prosemirror-transform.js"
    },
    "./prosemirror-transform/1.3.2/": {
      "prosemirror-model": "./prosemirror-model/1.15.0/prosemirror-model.js"
    },
    "./prosemirror-transform/1.3.3/": {
      "prosemirror-model": "./prosemirror-model/1.15.0/prosemirror-model.js"
    },
    "./prosemirror-model/1.15.0/": {
      "orderedmap": "./orderedmap/1.1.1/orderedmap.js"
    }
  }
}

I'm getting two prosemirror-transform versions installed, and I can't figure out why. As far as I can tell, none of the packages express a dependency on a specific verseion of prosemirror-transform.

Is there any way I can debug why this is happening? Or is there some reason heritage might be doing this?