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 node@18.0.0 --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, node@18.0.0, 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, node@18.0.0, 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 node@18.0.0 --platform node@18.0 --platform node@18 See 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.
package.json
Configuring Flags Automatically With 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 node@18.0.0 --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 node@18.0.0 \
--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