@jvdx/core

jvdx is a minimal set of tools to help maintain and build better applications.
It is a single dependency to bundle, lint, format and test your library.

Installation & Usage

(1) Install @jvdx/core:

# Using npm
$ npm i -D @jvdx/core

# Using yarn
$ yarn add -D @jvdx/core

(2) Setup your package.json

{
	"name": "my-package", // Your package name
	"type": "module",
	"source": "src/index.js", // Your source code
	"main": "./dist/my-package.cjs", // Where to generate the CommonJS bundle
	"umd:main": "./dist/my-package.umd.js", // Where to generate the UMD bundle (also aliased as "unpkg")
	"module": "./dist/my-package.module.js", // Where to generate the ESM bundle
  "exports": {
    "types": "./dist/my-package.d.ts", // TypeScript typings for NodeNext modules
		"require": "./dist/my-package.cjs", // Used for require() in Node 12+
		"default": "./dist/my-package.modern.js" // Where to generate the modern bundle (see below)
	},
  "types": "dist/my-package.d.ts", // TypeScript typings
	"scripts": {
		"build": "jvdx build", // Compiles "source" to "main"/"module"/"unpkg"
		"dev": "jvdx build --watch", // Re-build when source files change
		"format": "jvdx format", // Format sources using prettier
		"lint": "jvdx lint" // Lint source using ESLint
	}
}

(3) Build your application

# Using npm
$ npm run build

# Using yarn
$ yarn build

Starter templates

We also provide some starter templates that you can initialize with the help of degit.

• joelvoss/jvdx-templates/google-cloud-function
• joelvoss/jvdx-templates/google-cloud-run
• joelvoss/jvdx-templates/next-app
• joelvoss/jvdx-templates/node-lib
• joelvoss/jvdx-templates/node-rest-api
• joelvoss/jvdx-templates/react-lib

$ npx degit joelvoss/jvdx-templates/<template-name> my-package
$ cd my-package

# Using npm
$ npm install

# Using yarn
$ yarn

Output Formats

jvdx produces esm (ECMAScript Modules, e.g. import / export), cjs (CommonJS, e.g. Node-style module.exports) and umd (Universal Module Definition) bundles with your code compiled to syntax that works pretty much everywhere.

While it's possible to customize the browser or Node versions you wish to support using a browserslist configuration, the default setting is optimal and strongly recommended.

Modern Mode

In addition to the above formats, jvdx also outputs a modern bundle specially designed to work in all modern browsers. This bundle preserves most modern JS features when compiling your code, but ensures the result runs in 95% of web browsers without needing to be transpiled. Specifically, it uses Babel's "bugfixes" mode (previously known as preset-modules) to target the set of browsers that support <script type="module"> - that allows syntax like async/await, tagged templates, arrow functions, destructured and rest parameters, etc. The result is generally smaller and faster to execute than the plain esm bundle.

This is enabled by default. All you have to do is add an "exports" field to your package.json

Usage & Configuration

jvdx comes with a variaty of commands, but the most notable are build, lint, format, test and clean. Neither require any options/flags, but they can be tailored to suit your needs if need be.

Each command does exactly what you would expect from it's name.

jvdx build

Builds your code once, it also enables minification and sets the NODE_ENV=production environment variable.
Unless overridden via the command line, jvdx uses the source property in your package.json to determine which of your JavaScript files to start bundling from (your "entry module"). The filenames and paths for generated bundles in each format are defined by the main, umd:main, module and exports properties in your package.json.

{
	"type": "module",
	"source": "src/index.js", // Your source code
	"exports": {
		"require": "./dist/my-package.cjs", // Used for require() in Node 12+
		"default": "./dist/my-package.modern.js" // Where to generate the modern bundle
	},
	"main": "./dist/my-package.cjs", // Where to generate the CommonJS bundle
	"module": "./dist/my-package.module.js", // Where to generate the ESM bundle
	"unpkg": "./dist/my-package.umd.js", // Where to generate the UMD bundle (also aliased as "umd:main")
	"types": "dist/foo.d.ts" // TypeScript typings directory
}

When deciding which bundle to use, Node.js 12+ and webpack 5+ will prefer the exports property, while older Node.js releases use the main property, and other bundlers prefer the module field.

For more information about the meaning of the different properties, refer to the Node.js documentation.

For UMD builds, jvdx will use a camelCase version of the name field in your package.json as export name. This can be customized using an "amdName" key in your package.json or the --name command line argument.

jvdx lint

Statically analyzes your code using ESLint.
Unless overridden via the command line, jvdx lints .js,.jsx,.ts, and .tsx files inside the ./src directory.

For a full list of options see the ESLint documentation.

jvdx format

Formats your code in-place using Prettier.
Unless overridden via the command line, jvdx uses the following glob pattern to format all matching files in place:
./src/**/*.+(js|json|less|css|ts|tsx|md)

For a full list of options see the Prettier documentation.

jvdx test

Runs your test suite using Jest. Unless overridden via the command line, jvdx uses @jvdx/jest-preset as base configuration.

You can extend this base configuration by creating a jest.config.json at the root of your repository with the following content:

{
	"preset": "jvdx/jest-preset",
	"verbose": true
}

In the example above we're extending the base preset with verbose=true.

To apply this configuration, run jvdx test with the --config <path-to-config> flag.

For a full list of options see the Jest documentation.

jvdx typecheck

Checks the types of your code using the TypeScript compile. In essence this is a thin wrapper around tsc --noEmit.

For a full list of options see the TypeScript compiler documentation.

jvdx clean

Cleans your source repository using rimraf. Unless overridden via the command line, jvdx removes both ./node_modules and ./dist folders relative to the package root.

# Removes ./build
$ jvdx clean ./build

Using with TypeScript

Just point the input to a .ts file through either the cli or the source key in your package.json and you’re done. Under the hood jvdx uses the rollup-plugin-typescript2 plugin to transpile your TypeScript sources.

jvdx will generally respect your TypeScript config defined in a tsconfig.json file with notable exceptions being the "target" and "module" settings. To ensure your TypeScript configuration matches the configuration that jvdx uses internally it's strongly recommended that you set "module": "ESNext" and "target": "ESNext" in your tsconfig.json.

To ensure jvdx does not process extraneous files, by default it only includes your entry point. If you want to include other files for compilation, such as ambient declarations, make sure to add either "files" or "include" into your tsconfig.json.

If you're using CSS Modules, set "include": ["node_modules/@jvdx/core/index.d.ts"] in your tsconfig.json to enable type annotations of your CSS Module imports.

To ensure that your module's .d.ts type info is visible to other TypeScript projects that use moduleResolution: 'NodeNext', add a types key to your package.json's corresponding exports mapping.

CSS and CSS Modules

Importing CSS files is supported via import "./foo.css". By default, generated CSS output is written to disk. The --css inline command line option will inline generated CSS into your bundles as a string, returning the CSS string from the import:

// with the default external CSS:
import './foo.css'; // generates a minified .css file in the output directory

// with `jvdx build --css inline`:
import css from './foo.css';
console.log(css); // the generated minified stylesheet

CSS Modules: CSS files with names ending in .module.css are treated as a CSS Modules. To instead treat imported .css files as modules, run jvdx with --css-modules true. To disable CSS Modules for your project, pass --no-css-modules or --css-modules false.

The default scope name for CSS Modules is_[name]__[local]__[hash:base64:5] in watch mode, and _[hash:base64:5] for production builds. This can be customized by passing the command line argument --css-modules "[name]_[hash:base64:7]", using these fields and naming conventions.

| flag | import | is css module? | | ----- | -------------------------------- | :------------: | | null | import './my-file.css'; | ❌ | | null | import './my-file.module.css'; | ✅ | | false | import './my-file.css'; | ❌ | | false | import './my-file.module.css'; | ❌ | | true | import './my-file.css'; | ✅ | | true | import './my-file.module.css'; | ✅ |

Usage with {"type":"module"} in package.json

Node.js 12.16+ adds ESM support, which can be enabled by adding {"type":"module"} to your package.json. This property changes the default source type of .js files to be ES Modules instead of CommonJS, thus requiring you to change the file extension to .cjs for CommonJS bundles generated by jvdx.

{
	"type": "module",
	"module": "dist/foo.js", // ES Module bundle
	"main": "dist/foo.cjs" // CommonJS bundle
}

Additional build configuration options

You can override the build configuration using the publishConfig property in your package.json.

{
	"main": "src/index.ts", // Used in local dev environment
	"publishConfig": {
		"source": "src/index.js", // Input
		"main": "dist/my-library.js" // Output
	},
	"scripts": {
		"build": "jvdx build"
	}
}

Building a single bundle with a fixed output name

By default jvdx outputs multiple bundles, one bundle per format. A single bundle with a fixed output name can be built like this:

$ jvdx -i lib/main.js -o dist/bundle.js --no-pkg-main -f umd

Mangling Properties

To achieve the smallest possible bundle size, libraries often wish to rename internal object properties or class members to smaller names - transforming this._internalIdValue to this._i. jvdx doesn't do this by default, however it can be enabled by creating a mangle.json file (or a "mangle" property in your package.json). Within that file, you can specify a regular expression pattern to control which properties should be mangled. For example: to mangle all property names beginning an underscore:

{
	"mangle": {
		"regex": "^_"
	}
}

It's also possible to configure repeatable short names for each mangled property, so that every build of your library has the same output.

Defining build-time constants

The --define option can be used to inject or replace build-time constants when bundling. In addition to injecting string or number constants, prefixing the define name with @ allows injecting JavaScript expressions.

| Build command | Source code | Output | | ------------------------------------- | ---------------------- | ----------------------- | | jvdx --define VERSION=2 | console.log(VERSION) | console.log(2) | | jvdx --define API_KEY='abc123' | console.log(API_KEY) | console.log("abc123") | | jvdx --define @assign=Object.assign | assign(a, b) | Object.assign(a, b) |

Building Module Workers

jvdx is able to detect and bundle Module Workers when generating bundles in the esm and modern formats. To use this feature, instantiate your Web Worker as follows:

worker = new Worker(new URL('./worker.js', import.meta.url), {
	type: 'module',
});
// or simply:
worker = new Worker('./worker.js', { type: 'module' });

... then add the --workers flag to your build command:

microbundle --workers

For more information see @surma/rollup-plugin-off-main-thread.

All CLI Options

Usage
  $ jvdx <command> [options]

Available Commands
  clean     Cleans repository and removes `./node_modules` and `./dist`.
  lint      Statically analyzes your code using ESLint.
  format    Formats your code in-place using prettier.
  test      Runs your test suite using Jest.
  build     Builds the assets once, it also enabled minification and sets the NODE_ENV=production environment variable

For more info, run any command with the `--help` flag
  $ jvdx clean --help
  $ jvdx lint --help

Options
  -v, --version    Displays current version
  -h, --help       Displays this message

build

Usage
  $ jvdx build [...entries] [options]

Options
  -c, --clean        Clean output directory before building.
  -i, --entry        Entry module(s)
  -o, --output       Directory to place build files into
  -f, --format       Only build specified formats (any of modern,esm,cjs,umd or iife) (default modern,esm,cjs,umd)
  -w, --watch        Rebuilds on any change  (default false)
  --pkg-main         Outputs files analog to package.json main entries  (default true)
  --target           Specify your target environment (node or web)  (default web)
  --external         Specify external dependencies, or 'none' (default peerDependencies and dependencies in package.json)
  --globals          Specify globals dependencies, or 'none'
  --define           Replace constants with hard-coded values (use @key=exp to replace an expression)
  --alias            Map imports to different modules
  --compress         Compress output using Terser (default true when --target is web, false when --target is node)
  --strict           Enforce undefined global context and add "use strict"
  --name             Specify name exposed in UMD and IIFE builds
  --cwd              Use an alternative working directory  (default .)
  --sourcemap        Generate source map  (default true)
  --jsx              Enable @babel/preset-react
  --tsconfig         Specify the path to a custom tsconfig.json
  --generateTypes    Whether or not to generate types, if `types` or `typings` is set in `package.json` then it will default to be `true`
  --css              Where to output CSS: "inline" or "external" (default "external")
  --css-modules      Configures .css to be treated as modules (default null)
  --workers          Bundle module workers - see https://github.com/surma/rollup-plugin-off-main-thread#auto-bundling  (default false)
  -h, --help         Displays this message

Examples
  $ jvdx build
  $ jvdx build --clean
  $ jvdx build --globals react=React,jquery=$
  $ jvdx build --define API_KEY=1234
  $ jvdx build --alias react=preact
  $ jvdx build --no-sourcemap # don't generate sourcemaps
  $ jvdx build --tsconfig tsconfig.build.json

lint

Usage
  $ jvdx lint [...files|dir|glob] [options]

Options
  -h, --help    Displays this message

Examples
  $ jvdx lint

format

Usage
  $ jvdx format [...files|dir|glob] [options]

Options
  -h, --help    Displays this message

Examples
  $ jvdx format

test

Usage
  $ jvdx test [options]

Options
  -h, --help    Displays this message

Examples
  $ jvdx test

clean

Usage
  $ jvdx clean [...files|dir|glob] [options]

Options
  -h, --help    Displays this message

Examples
  $ jvdx clean