Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/swimlane/pkgdrop

Easy deployment of ES modules without external connection needed at runtime
https://github.com/swimlane/pkgdrop

bare-imports es6 hacktoberfest modules

Last synced: 7 days ago
JSON representation

Easy deployment of ES modules without external connection needed at runtime

Host: GitHub
URL: https://github.com/swimlane/pkgdrop
Owner: swimlane
Created: 2019-04-01T23:36:22.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2023-10-02T19:09:52.000Z (about 1 year ago)
Last Synced: 2024-10-28T14:27:54.246Z (16 days ago)
Topics: bare-imports, es6, hacktoberfest, modules
Language: TypeScript
Homepage:
Size: 1.34 MB
Stars: 12
Watchers: 7
Forks: 1
Open Issues: 19
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md

Awesome Lists containing this project

README

        


  



pkgdrop

===========

`pkgdrop` is a package delivery tool for ES modules from [npm](https://www.npmjs.com/) packages.

Use it to deliver packages from npm to the browser with no external connection needed at runtime.

## Summary

- Downloads and extracts packages from npm, including dependencies, into a flat file structure.

- Optionally bundles packages, and dependencies, into a single ES module.

- Generates a import-map compatible with the [WICG import-maps](https://github.com/WICG/import-maps) proposal (and shims).

- Provides a method to archive and merge downloaded packages and import-maps between systems.

## Installation

```bash

$ npm install @swimlane/pkgdrop -g

```

> Or use `npx @swimlane/pkgdrop` in place of `pkgdrop` in the examples below.

## CLI Usage

### Adding Packages

```bash

pkgdrop add  [] [--force] [--bundle] [--optimize] [--clean]

```

> The `add` command is optional; the default `pkgdrop` command is `add`.

* ``: npm package(s) (with optional version or tag) to add

* `--force`: force add package(s) that have already been added

* `--bundle`: bundle the added package(s)

* `--optimize`: minify the generated bundle(s)

* `--clean`: clean output directory before adding new packages

* `--no-color`: disable CLI colors

> The cli supports multiple packages and semantic version ranges.  For example `pkgdrop add lit-element [email protected]` will install the latest version of `lit-element` and an exact version of `es-module-shims`.

Packages added using `pkgdrop ` are downloaded into a `/@/` directory.  The same happens for each dependency of ``.  An [import-map](https://github.com/WICG/import-maps) in the `` directory is added or updated.

For example, running `pkgdrop [email protected]` results in a `` directory structure of:

```

├── [email protected]/

├── [email protected]/

└── importmap.json

```

and an import-map of:

```json

{

  "imports": {

    "[email protected]": "[email protected]/lit-element.js",

    "[email protected]/": "[email protected]/",

    "lit-element@2": "[email protected]/lit-element.js",

    "lit-element@2/": "[email protected]/"

  },

  "scopes": {

    "[email protected]": {

      "lit-html": "[email protected]/lit-html.js",

      "lit-html/": "[email protected]/"

    },

    "[email protected]": {}

  }

}

```

> The `` directory is configurable via the `package_path` property in `pkgdrop.config.js`, the default is `./-/`.  In the generated import-maps, the package address is configurable via the `package_root` property, the default is `/-/`.  This value must start with `/`, `../`, or `./`, or be an absolute URL.

The `--bundle` flag adds and bundles each `` into a esm bundle (and with inlined dependencies) at `/@.bundle.js`.  The import-map is updated to resolve `@` to the bundle.

For example, running `pkgdrop [email protected] --bundle` results in a root directory structure of:

```

├── 

├── [email protected]/

├── [email protected]

└── importmap.json

```

and an import-map of:

```json

{

  "imports": {

    "[email protected]": "[email protected]",

    "d3@5": "[email protected]"

  },

  "scopes": {}

}

```

> Note that `pkgdrop` adds an import of the form `@` that resolves to the latest local version of the package.

### Moving packages

Adding packages requires a connection to the npm registry.  Once added an external connection is no longer required.  The `` directory can be deployed with other static assets or just manually copied between systems.

The following commands help move content from one system to another:

- `pkgdrop pack []` - Creates a tarball from the `` directory.  The `` is optional and defaults to using a timestamp.

- `pkgdrop merge ` - Unpacks a tarball to the `` directory, merging the packed import-map with the existing import-map.

### Other commands

- `pkgdrop init` - Adds an `pkgdrop.config.js` to the current directory and an empty import-map.

- `pkgdrop version` - Outputs the version number.

- `pkgdrop config` - Displays current configuration.

- `pkgdrop clean` - Cleans the output directory.

- `pkgdrop resolve ` - Prints the resolved url for package(s).

## In browser usage

### Fixed Versions

The added ES modules can be loaded in the browser using a absolute path and full version.

- `//@[/file-path]`

> Use `pkgdrop resolve ` to find the resolved path.

```html

  import { html, render } from '/-/[email protected]/lit-html.js';

```

Or with the dynamic `import()`:

```html

  import('/-/[email protected]/lit-html.js')

    .then(({ html, render }) => {

      console.log(html, render);

    });

```

### Bare imports

While most modern browsers include support for ES modules, bare package specifiers are explicitly forbidden.  In order to import bare package specifiers like `import "lit-html"` we need [import-maps](https://github.com/WICG/import-maps).

> Note: import-maps are still an experimental specification.  Use [es-module-shims](https://github.com/guybedford/es-module-shims) to polyfill most of the newer modules specifications.  [SystemJS](https://github.com/systemjs/systemjs) also supports import-maps.  However, `SystemJS` only loads `System.register` modules or AMD modules via extras.

```html

  import { LitElement, css } from '[email protected]';

  import { html } from '[email protected]';

  class MyElement extends LitElement {

  

    static get properties() {

      return {

        mood: {type: String}

      }

    }

    

    static get styles() {

      return css`.mood { color: green; }`;

    }

  

    render() {

      return html`Web Components are <span class="mood">${this.mood}</span>!`;

    }

  }

  customElements.define('my-element', MyElement);

```

### Bundles

Bundles can also be imported using fixed versions or bare imports when combined with the import-map.

```html

  import * as d3 from '/-/[email protected]';

  d3.select('#hello').text('Hello World!!');

```

```html

    import * as d3 from '[email protected]';

    d3.select('#hello').text('Hello World!!');

```

## Examples

- [lit-element](https://lit-element.polymer-project.org/) project (with shims and import-map): https://gist.github.com/Hypercubed/6a2c7e5c21355bc109f0c06e6a5a62c8

- [d3](https://d3js.org/) project (bundled, no shims or import-map necessary): https://gist.github.com/Hypercubed/e6f198ff61f5d2d9ec3a540a0ac3b9ca

## Credits

`pkgdrop` is a [Swimlane](http://swimlane.com) open-source project; we believe in giving back to the open-source community by sharing some of the projects we build for our application. Swimlane is an automated cyber security operations and incident response platform that enables cyber security teams to leverage threat intelligence, speed up incident response and automate security operations.

## License

  [MIT licensed](LICENSE).