Quikdev-JS Library Development Utility

To build web applications with JavaScript, use Quikdev-Web instead.

Quikdev-JS is a build tool and test runner for developers who create JavaScript libraries for multiple runtimes. This primarily (but not exclusively) caters to ES Module libraries.

Supported Runtimes:

• Node.js
• Deno
• Chromium (V8)
• Firefox (SpiderMonkey)
• Safari (JavaScriptCore)

Quikdev-JS itself is designed to be used in a Node.js working environment. It is an npm/CLI tool that can easily be used in npm scripts to automate build and test processes.

Behind the scenes, Quikdev-JS uses esbuild to bundle/build JavaScript. It configures and launches temporary Docker containers for testing, assuring tests run in an isolated environment. Browser-based runtimes leverage Microsoft's Playwright container to simulate browser environments.

Requirements

• Docker Desktop (or just the Docker daemon on servers)
• Node.js 16+

These tools are readily accessbile in Github Actions.

Example Output

Build

quikdev-js build --pack --external crypto --external os --outdir ./.dist/@ngnjs/libcrypto

Example Test Output:

quikdev-js test --platform deno --verbose --output pretty --external crypto --external os --sourcemap --entry ./tests

(pretty results)

Setup

Add Quikdev-JS to your project: npm install @quikdev/js --save-dev.

In the project's package.json file, add scripts to automate your build and test processes. For example:

{
  "scripts": {
    "build": "quikdev-ds build --outdir dist/@myorg/mylibrary",
    "test": "npm run build && quikdev-js test --platform [email protected] --platform deno --output pretty --entry ./tests"
  }
}

Using the configuration above, running npm run build will bundle the library into a directory called dist/@myorg/mylibrary. By default, the entry point (i.e. main file to bundle) will be extracted from package.json. There are several flags available to configure the output (described later in this document).

Running npm test (or npm run test) first runs the build process, then launches the tests found in the ./tests directory. Two runtimes (Node.js v18.0.0 and Deno's latest version) are specified, so the tests will be run in both of these runtimes.

Global CLI

It is also possible to install Quikdev-JS globally: npm install -g @quikdev/js. This will make the quikdev-js command (and qdjs alias) available for use from a terminal/console window.

Usage (CLI Documentation)

quikdev-js [COMMAND]

  A build and test utility for JavaScript libraries.

Commands:

  build               build the library
  test                build the library and run tests

quikdev-js build

quikdev-js build [FLAGS]

  build the library

Flags:

  --aliases       [-a]        map import names to file paths | example: -a
                              "mymodule:/path/to/entry.js" Can be used multiple
                              times.
  --displayexports[-de]
  --entry         [-in,       display bundle's generated exports in the results
                              the entry point/source file (Default: ./src/index.
                  -source]    js)
  --outdir        [-out, -o]  the output directory (Default: ./.dist)
  --minify        [-m]        minify output
  --sourcemap     [-map]      generate sourcemaps
                              external libraries to ignore in build Can be used
  --external      [-e]        multiple times.
                              embed library in the build Can be used multiple
  --embed         [-i]        times.
                              bundle output format Options: esm, iife, cjs. (
  --format                    Default: esm)
                              configuration attribute in package.json file (
  --config        [-c, -cfg]  Default: quikdev-js)
                              platform to run the test on - this can be node,
                              deno, or browser. The specific version can be
                              specified using @ syntax, such as node@18, node@18.
                              0, [email protected], node@lts, node@latest, or
                              node@current; all of which correspond to Docker
                              containers. Can be used multiple times. (Default:
  --platform      [-p]        node@lts)
                              environment variable to pass to build/test process.
                              ex: --env myvar=value or --env DEBUG. If no value
                              is specified, the value of the host environment
                              variable of that same name will be used. Can be
  --env                       used multiple times.
                              replace a string. ex: --replace "string=newvalue"
  --replace       [-r]        Can be used multiple times.
                              the output type Options: pretty, tap. (Default:
  --output                    pretty)
  --verbose       [-v]        verbose output (displays docker commands)
                              forcibly stop processing after this duration is
  --timeout       [-to]       exceeded (milliseconds) (Default: 60000)
                              mount a directory or file to the test image - ex:
                              -v "/path/to/dir:/mapped/dir" Can be used multiple
  --volumes       [-v]        times.
                              the type of documentation to produce Options: md,
                              markdown, json. Can be used multiple times. (
  --type          [-t]        Default: md)

quikdev-js test

quikdev-js test [FLAGS]

  build the library and run tests

Flags:

  --aliases       [-a]        map import names to file paths | example: -a
                              "mymodule:/path/to/entry.js" Can be used multiple
                              times.
  --displayexports[-de]
  --entry         [-in,       display bundle's generated exports in the results
                              the entry point/source file (Default: ./src/index.
                  -source]    js)
  --outdir        [-out, -o]  the output directory (Default: ./.dist)
  --minify        [-m]        minify output
  --sourcemap     [-map]      generate sourcemaps
                              external libraries to ignore in build Can be used
  --external      [-e]        multiple times.
                              embed library in the build Can be used multiple
  --embed         [-i]        times.
                              bundle output format Options: esm, iife, cjs. (
  --format                    Default: esm)
                              configuration attribute in package.json file (
  --config        [-c, -cfg]  Default: quikdev-js)
                              platform to run the test on - this can be node,
                              deno, or browser. The specific version can be
                              specified using @ syntax, such as node@18, node@18.
                              0, [email protected], node@lts, node@latest, or
                              node@current; all of which correspond to Docker
                              containers. Can be used multiple times. (Default:
  --platform      [-p]        node@lts)
                              environment variable to pass to build/test process.
                              ex: --env myvar=value or --env DEBUG. If no value
                              is specified, the value of the host environment
                              variable of that same name will be used. Can be
  --env                       used multiple times.
                              replace a string. ex: --replace "string=newvalue"
  --replace       [-r]        Can be used multiple times.
                              the output type Options: pretty, tap. (Default:
  --output                    pretty)
  --verbose       [-v]        verbose output (displays docker commands)
                              forcibly stop processing after this duration is
  --timeout       [-to]       exceeded (milliseconds) (Default: 60000)
                              mount a directory or file to the test image - ex:
                              -v "/path/to/dir:/mapped/dir" Can be used multiple
  --volumes       [-v]        times.
                              the type of documentation to produce Options: md,
                              markdown, json. Can be used multiple times. (
  --type          [-t]        Default: md)

Flags/Arguments

|Flag|Purpose|Examples| |-|-|-| |*aliases [-a]|Map aliases. This helps the build tool identify where other code sources can be found.| -a "chalk:./node_modules/chalk/index.js"-a "mod:/path/to/entry.js"| |displayexports [-de]|Displays the exported elements on the console during the build process.| |entry [-in,-source]|The main file to bundle. If this is not specified, the entrypoint is retrieved from package.json. If no package.json file is available, Quikdev will attempt to locate an index.js file.| -in ./src/index.js| |outdir [-out,-o]|The location where output will be written to.|-o /.dist| |minify [-m]|Minify the bundle.|--minify| |sourcemap [-map]|Produce sourcemaps (only applicable when minification is enabled.|--sourcemap| |*external [-e]|Ignore modules, treating them as runtime dependencies/externally loaded.|--external fs| |*embed [-i]|Embed a library in the build (i.e. include it, even if it is an external library)| --embed /path/to/module.js| |format|The output format.| - esm: ECMAScript Module (default/recommended)- iife: Immediately invoked function expression- cjs: CommonJS| |config [-c,-cfg]|This specifies an attribute in a package.json file containing a Quikdev-JS configuration|See configuration section below| |*platform [-p]|Specify which platform/runtime to run tests in|--platform node--platform [email protected]--platform [email protected]--platform node@18See below for more options.| |*env|Specify environment variables to pass to the build/test process. When an environment variable is specified with no value, the local computer's value for that variable will be passed through to the build/test process.|--env myvar=value--env DEBUG| |*replace [-r]|Find/replace values in the code. Package.json attributes can also be specified, such as package.version, which will use the value of the package.json version attribute.|--replace "string=newvalue"--replace "myversion=package.version"| |output|Output types for test results. Valid options include pretty and tap. The pretty option outputs tap-spec results|| |verbose [-v]|Display the Docker command used to launch the environment.|| |timeout [-to]|Forcibly stop processing after the specified duration. Defined in milliseconds|-to 60000 (one minute)| |*volumes [-v]|Map directories (volumes) to the build/test process.|-v "/path/to/dir:/mapped/dir"| |package [-pack]|Package for npm. Copy package.json, README.md, LICENSE.md (or LICENSE), and .npmignore to the output directory. All files except package.json are skipped if they do not exist.||

*Flag can be specified multiple times.

Configuring Flags Automatically With package.json

If a package.json file is available, Quikdev-JS can automatically extract configuration properties from it.

For example:

{
  "name": "@my/lib",
  "version": "1.0.1",
  "type": "module",
  "main": "./src/index.js",
  "exports": {
    ".": {
      "import": "./index.js"
    },
  },
  "scripts": {
    "build": "quikdev-ds build --outdir dist/@myorg/mylibrary",
    "test": "npm run build && quikdev-js test --platform [email protected] --platform deno --output pretty --entry ./tests"
  },
  "quikdev-js": {
    "replace": {
      "<#REPLACE_VERSION#>": "package.version"
    },
    "alias": {
      "ngn": "./node_modules/ngn/index.js",
      "rfc4648": "./node_modules/rfc4648/lib/index.mjs"
    },
    "embed": [
      "tappedout"
    ]
  }
}

Notice the quikdev-js attribute. It contains several Quikdev-JS flags that will be applied to any quikdev command.

For example, running npm test would first run the Quikdev-JS build process as:

quikdev-ds build \
  --replace "<#REPLACE_VERSION#>=package.version" \
  --alias "ngn:./node_modules/ngn/index.js" \
  --alias "rfc4648:./node_modules/rfc4648/lib/index.mjs" \
  --embed tappedout
  --outdir dist/@myorg/mylibrary

Remember, package.<attribute> will be replaced with the corresponding package.json value, so the command above will actually work like:

quikdev-ds build \
  --replace "<#REPLACE_VERSION#>=1.0.1" \
  --alias "ngn:./node_modules/ngn/index.js" \
  --alias "rfc4648:./node_modules/rfc4648/lib/index.mjs" \
  --embed tappedout
  --outdir dist/@myorg/mylibrary

Once the build is complete, the remaining command would be executed as the equivalent of:

quikdev-js test \
  --replace "<#REPLACE_VERSION#>=1.0.1" \
  --alias "ngn:./node_modules/ngn/index.js" \
  --alias "rfc4648:./node_modules/rfc4648/lib/index.mjs" \
  --embed tappedout
  --platform [email protected] \
  --platform deno \
  --output pretty \
  --entry ./tests
  --outdir ./.dist

This command will first launch a Node.js 18.0.0 Docker container, running the code found in ./.dist. It repeats the same process in a Deno container.

Unit Tests

This tool supports TAP (Test Anything Protocol) output. Any test runner capable of outputting TAP output is supported, but the author's of this tool also created tappedout, a cross-runtime test runner that requires no special transpilation (works in all runtimes, including Node, Deno, and browsers). Naturally, we recommend using it.

Roadmap/Wishlist

This tool currently has an experimental documentation feature for producing markdown docs for a library. It is very limited in its current state. We hope to produce a more robust documentation generator capable of markdown and JSON output.

• Test Coverage Reports
• File Size Reports
• Better ESLint Support