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

vega-bundler

v0.0.1

Published

Compile optimized Vega and Vega-Lite bundles.

Downloads

9

Readme

vega-bundler

Utilities for pre-parsing Vega and Vega-Lite specifications and producing optimized module bundles.

Both and Vega and Vega-Lite have their own parser and compiler. A Vega-Lite specification compiles to a full Vega specification, which in turn is parsed to an intermediate dataflow specification that serves as input to a Vega View (for more, see How Vega Works). In addition, Vega provides a number of data and visual encoding transforms, but not all of them may be needed within a given a deployment.

To reduce both file size and loading time, this package pre-parses input specifications and generates optimized code bundles that omit the parsers and include only the underlying transforms that are actually used. This can result in substantial savings, especially when using Vega-Lite.

API Reference

# bundle(specs[, options]) <>

Returns bundled source code for browser use. The source code includes the Vega View constructor as an exported method.

By default the bundle also exports a method for each named specification in specs. The exported methods take Vega View constructor options as input and return an instantiated View. Set the specs to false to disable inclusion of runtime specifications in the output bundle.

  • specs: An object of key-value pairs where the key is a unique name (must be a valid JavaScript identifier) and the value is a Vega or Vega-Lite specification object. The specifications should include the $schema property indicating the Vega or Vega-Lite schema.
  • options: An object containing build options passed to the rollup bundler:
    • specs: A boolean flag (default true) indicating if parsed runtime dataflow specifications should be included in the bundle. If false, all specifications are excluded from the generated output code, in which case clients must directly pass runtime dataflow specifications to the exported View constructor.
    • transpile: A boolean flag (default true) indicating if the Vega code should be transpiled (using Babel) for greater browser compatibility.
    • targets: A string indicating the Babel transpilation target platforms (default 'defaults and not IE 11'). This option is ignored if the babel option is false.
    • name: The name of the output bundle (default 'vegaBundle'). This corresponds to the global variable name for the compiled bundle when loaded directly via the browser <script> tag.
    • format: The output format for the bundle (default 'umd'). Valid options are 'umd' (universal module definition), 'iife' (immediately-invoked function expression), and es (EcmaScript module).
    • minify: A boolean flag (default true) indicating if output code should be minified using terser.

# Bundle() <>

A class for generating custom builds. The bundle method is a convenient shorthand that calls Bundle class methods. Developers can use a Bundle directly to exert more control over the bundling process, including generation of module index code that can then be used in other projects and passed to bundlers other than rollup.

An instantiated Bundle includes the following methods:

# Bundle.add(name, spec) <>

Adds a Vega or Vega-Lite specification to the bundle along with a unique name, and returns this Bundle instance. This method is a convenience method that redirects to either addVegaSpec or addVegaLiteSpec. The type of the file will be determined by consulting the $schema property of the input spec object. If the $schema property is not defined or the Vega language variant can not be determined, the input spec is parsed as a Vega specification.

# Bundle.addVegaSpec(name, spec) <>

Adds a Vega specification to the bundle along with a unique name, and returns this Bundle instance. The input spec must be a valid Vega JSON specification.

# Bundle.addVegaLiteSpec(name, spec) <>

Adds a Vega-Lite specification to the bundle along with a unique name, and returns this Bundle instance. The input spec must be a valid Vega-Lite JSON specification.

# Bundle.addDataflowSpec(name, spec) <>

Adds a parsed Vega dataflow specification to the bundle along with a unique name, and returns this bundler instance. The input spec should be a valid Vega dataflow specification, such as those produced by vega.parse.

# Bundle.getDataflowSpec(name) <>

Get a named Vega dataflow specification in this bundle. This method retrieves a runtime dataflow specification for an added Vega or Vega-Lite specification.

# Bundle.getDataflowSpecs() <>

Get all Vega runtime dataflow specifications in this bundle. Returns an object with specification names for keys and Vega runtime dataflow specification as values.

# Bundle.codegen() <>

Returns generated JavaScript module index code for the current bundle, using ES module syntax. The generated code will import only the Vega transforms needed for the current set of specifications, and will export View constructor functions for each of the named specifications.

For example, a specification named 'barChart' will result in an exported method barChart(options) { ... } that takes Vega View constructor options as input and returns an instantiated View instance.

# Bundle.build(options) <>

Compiles a bundle using rollup and returns a Promise to the resulting JavaScript code. This method accepts the same options as bundle.

Command Line Utility

The vega_bundler command line utility generates optimized code bundles for input Vega or Vega-Lite specification files.

Usage

vega_bundler --help
Compile Vega or Vega-Lite specifications into an optimized bundle.
Usage: vega_bundler [options] spec_files
  If the "output" option is unspecified, writes generated code to stdout.
  For errors and log messages, writes to stderr.

Options:
  -o, --output     Output file to write bundled code. If omitted, writes to
                   standard output.                                     [string]
  -m, --manifest   JSON file mapping specification names to files. If omitted,
                   spec1, spec2, ...specN naming is used. If provided, the
                   spec_files input is ignored.                         [string]
      --include    Include Vega runtime dataflow specifications in the bundle.
                   If false, the dataflow specifications are omitted from the
                   bundle and written to individual files.
                                                       [boolean] [default: true]
      --minify     Minify output code using terser.    [boolean] [default: true]
      --format     The output bundle format. One of "umd" (default, universal
                   module definition), "iife" (immediately-invoked function
                   expression), or "es" (EcmaScript module).            [string]
      --name       The output bundle name. This is the global variable name for
                   the bundle when loaded via the <script> tag.         [string]
      --transpile  Transpile code using Babel.         [boolean] [default: true]
      --targets    Transpilation target platforms. Ignored if transpile is
                   false.                                               [string]
      --help       Show help                                           [boolean]
      --version    Show version number                                 [boolean]

Examples

vega_bundler -o bundle.min.js arc.vg.json bar.vg.json

Compiles the provided specifications into an optimized bundle. The bundle includes the methods spec1(opt) a spec2(opt) for instantiating View instances.

vega_bundler -m specs.json -o bundle.min.js

Compiles the specifications included in the manifest file specs.json into an optimized bundle. For example, the manifest file

{
  "arc": "specs/arc.vg.json",
  "bar": "specs/bar.vg.json"
}

will result in an optimized bundle with the methods arc(opt) and bar(opt) for instantiating View instances.

vega_bundler --no-includes -m specs.json -o bundle.min.js

Compiles an optimized bundle that exports the Vega View constructor but does not include parsed runtime dataflow specifications. Instead, the dataflow specifications are written to the separate files arc.json and bar.json, which can be loaded separately and passed to the View constructor.