Dbux CLI

• Getting Started
• Run
• Run Recipes
  • esnext + verbose + cache + pw
  • Mocha
  • Jest
• Instrument
• Config

@dbux/cli is a tool for easily running Node applications [with Dbux enabled](/dbux/features/enable-dbux).

Getting Started

1. Install @dbux/cli locally:
   • npm install -D @dbux/cli or
   • yarn add --dev @dbux/cli
   • NOTE: this also installs several other tools that it depends on, such as @dbux/babel-plugin and several babel packages.
2. Run
   • E.g.: npx dbux run ./test.js

The CLI currently supports two commands: run and instrument (code here).

Run

This command executes a given JavaScript application with Dbux enabled.

• Usage: npx dbux run app.js
  • Alias = r: npx dbux r ...

Run someFile.js with Dbux enabled:

• npx dbux r ./someFile.js

Run Recipes

esnext + verbose + cache + pw

These are some useful default settings.

• The --esnext flag adds all kinds of esnext syntax support and proposals.

  • (TODO: We need to review and better explain this. We also might want to replace our self-maintained list of plugins with preset-env (now that preset-env is a lot more mature), or at least update the list of added plugins.)

• The --verbose flag adds more verbose information about what Dbux does.

• The --cache flag provides big performance benefits when running large applications multiple times.

  • (NOTE: We forked (copied) @babel/register and implemented our own caching for this, as explained in this comment.)

• The --pw flag is one type of module filter. It whitelists 3rd party packages (from node_modules) to also be instrumented and traced.

  • More explanations on module filters can be found in the trace guide.

• npx dbux r --esnext --verbose=1 --cache --pw=* ./someFile.js

Caution: --pw=*

pw=* leads to all packages being traced. While this can work in many settings, it can also wreak havoc on performance, or even lead to some really naughty behavior, where libraries are instrumented which themselves aim to instrument, such as v8-compile-cache. For example, we came across bugs caused by Dbux trying to instrument the instrumenters when tracing webpack as well as Jest.

Mocha

Run a mocha test files myTest1.js and myTest2.js:

• node --stack-trace-limit=100 --enable-source-maps "./node_modules/@dbux/cli/bin/dbux.js" run --esnext --verbose=1 --cache --pw=* ./node_modules/mocha/bin/_mocha -- --no-exit -- myTest1.js myTest2.js

Explanations:

• node options: --stack-trace-limit=100 --enable-source-maps
• dbux options: --verbose=1 --esnext
• mocha options: --no-exit (between the two --'s)
• Target files: myTest1.js myTest2.js (following the last --)

note

While of course entirely possible, we generally do not recommend running *all tests with Dbux enabled, since that can be extremely slow. What you want to do instead is only run failing tests with Dbux.

We already know about the importance of being able to do so, and hopefully will provide an easier solution in the near future. Please contact us on Discord, if better test-/CI-integration is of great import to you or your team.

Jest

TODO

Instrument

• Usage: npx dbux instrument app.js
  • Alias: npx dbux i ...

This is mostly used for internal development purposes. It allows developers to inspect the instrumented version of their applications.

Examples:

• Show instrumented code result of someFile.js in a new VSCode window: npx dbux i someFile.js | code -

Config

run and instrument commands both share (for the most part) these command options.

TODO: extract a pretty table of configuration options here.