ggoodman/rollup-plugin-velcro

README

rollup-plugin-velcro

👟 A Rollup plugin to to resolve and read dependencies straight from the cloud ☁ using Velcro.

Requirements

This plugin must be configured with an http request function having a signature of (href: string) => Promise<ArrayBuffer>.

When running in the browser or environments other than Node.js, an promisified fs-equivalent must be provided that implements:

type Dirent = {
  isFile(): boolean;
  isDirectory(): boolean;
  name: string;
};

interface FsInterface {
  readdir(
    path: string,
    options: {
      encoding: 'utf-8';
      withFileTypes: true;
    }
  ): Promise<Dirent[]>;
  readFile(path: string): Promise<ArrayBuffer>;
  realpath(path: string): Promise<string>;
}

Install

Using npm:

npm install rollup-plugin-velcro --save-dev

Usage

Create a rollup.config.js configuration file and import the plugin:

import velcro from 'rollup-plugin-velcro';

export default {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'cjs',
  },
  plugins: [velcro()],
};

Then call rollup either via the CLI or the API.

Options

`cdn`

Type: 'jsDelivr' | 'unpkg'
Default: 'jsDelivr'

Selects the CDN that will be used for resolving and reading the files.

`debug`

Type: boolean
Default: false

Opt into verbose logging of velcro resolver operations.

`extensions`

Type: string[]
Default: [".js", ".json", ".mjs", ".cjs"]

An ordered list of file extensions that will be consulted for resolving dependencies between modules that don't specify the extension.

`fs`

Type: import('fs')
Default: require('fs')

An implementation of the promisified fs interface that will be used for reading local files.

`packageMain`

Type: ('browser' | 'main' | 'module')[]
Default: ["module", "main"]

An ordered list of package.json fields that will be consulted when resolving the default file of an npm module.

Note: This should fully support the sementics of browser overrides and exclusions.

Using with @rollup/plugin-commonjs

Since most packages in your node_modules folder are probably legacy CommonJS rather than JavaScript modules, you may need to use @rollup/plugin-commonjs:

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'main.js',
  output: {
    file: 'bundle.js',
    format: 'iife',
    name: 'MyModule',
  },
  plugins: [resolve(), commonjs()],
};

Resolving Built-Ins (like `fs`)

This plugin won't resolve any builtins (e.g. fs). If you need to resolve builtins you can install local modules and set preferBuiltins to false, or install a plugin like rollup-plugin-node-polyfills which provides stubbed versions of these methods.

If you want to silence warnings about builtins, you can add the list of builtins to the externals option; like so:

import resolve from '@rollup/plugin-node-resolve';
import builtins from 'builtin-modules'
export default ({
  input: ...,
  plugins: [resolve()],
  external: builtins,
  output: ...
})