npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@swimlane/airdrop-cli

v1.0.0

Published

package-server

Downloads

43

Readme

airdrop-cli

airdrop-cli is a package delivery tool for ES modules from npm 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 proposal (and shims).
  • Provides a method to archive and merge downloaded packages and import-maps between systems.

Installation

$ npm install @swimlane/airdrop-cli -g

Or use npx @swimlane/airdrop-cli in place of airdrop in the examples below.

CLI Usage

Adding Packages

airdrop add <package> [<package>] [--force] [--bundle] [--optimize] [--clean]

The add command is optional; the default airdrop command is add.

  • <package>: 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 airdrop add lit-element [email protected] will install the latest version of lit-element and an exact version of es-module-shims.

Packages added using airdrop <package> are downloaded into a <package_path>/<name>@<version>/ directory. The same happens for each dependency of <package>. An import-map in the <package_path> directory is added or updated.

For example, running airdrop [email protected] results in a <package_path> directory structure of:

<package_path>
├── [email protected]/
├── [email protected]/
└── importmap.json

and an import-map of:

{
  "imports": {
    "[email protected]": "<package_root>[email protected]/lit-element.js",
    "[email protected]/": "<package_root>[email protected]/",
    "lit-element@2": "<package_root>[email protected]/lit-element.js",
    "lit-element@2/": "<package_root>[email protected]/"
  },
  "scopes": {
    "[email protected]": {
      "lit-html": "<package_root>[email protected]/lit-html.js",
      "lit-html/": "<package_root>[email protected]/"
    },
    "[email protected]": {}
  }
}

The <package_path> directory is configurable via the package_path property in airdrop.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 <package> into a esm bundle (and with inlined dependencies) at <package_path>/<name>@<version>.bundle.js. The import-map is updated to resolve <name>@<version> to the bundle.

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

<package_path>
├── <d3 deps>
├── [email protected]/
├── [email protected]
└── importmap.json

and an import-map of:

{
  "imports": {
    "[email protected]": "<package_root>[email protected]",
    "d3@5": "<package_root>[email protected]"
  },
  "scopes": {}
}

Note that airdrop adds an import of the form <name>@<major-version> 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 <package_path> 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:

  • airdrop pack [<filename>] - Creates a tarball from the <package_path> directory. The <filename> is optional and defaults to using a timestamp.
  • airdrop merge <filename> - Unpacks a tarball to the <package_path> directory, merging the packed import-map with the existing import-map.

Other commands

  • airdrop init - Adds an airdrop.config.js to the current directory and an empty import-map.
  • airdrop version - Outputs the version number.
  • airdrop config - Displays current configuration.
  • airdrop clean - Cleans the output directory.
  • airdrop resolve <package> - 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.

  • /<package_root>/<name>@<version>[/file-path]

Use airdrop resolve <package> to find the resolved path.

<script type="module">
  import { html, render } from '/-/[email protected]/lit-html.js';
</script>

Or with the dynamic import():

<script type="module">
  import('/-/[email protected]/lit-html.js')
    .then(({ html, render }) => {
      console.log(html, render);
    });
</script>

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.

Note: import-maps are still an experimental specification. Use es-module-shims to polyfill most of the newer modules specifications. SystemJS also supports import-maps. However, SystemJS only loads System.register modules or AMD modules via extras.

<script type="module" src="/-/[email protected]/dist/es-module-shims.js"></script>
<script type="importmap-shim" src="/-/importmap.json"></script>
<script type="module-shim">
  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);
</script>

Bundles

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

<script type="module">
  import * as d3 from '/-/[email protected]';
  d3.select('#hello').text('Hello World!!');
</script>
<script type="module" src="/-/[email protected]/dist/es-module-shims.js"></script>
<script type="importmap-shim" src="/-/importmap.json"></script>
<script type="module-shim">
    import * as d3 from '[email protected]';
    d3.select('#hello').text('Hello World!!');
</script>

Examples

  • lit-element project (with shims and import-map): https://gist.github.com/Hypercubed/6a2c7e5c21355bc109f0c06e6a5a62c8
  • d3 project (bundled, no shims or import-map necessary): https://gist.github.com/Hypercubed/e6f198ff61f5d2d9ec3a540a0ac3b9ca

Credits

airdrop is a Swimlane 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.