Balena CLI Form Interpreter

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

  cause Attempting to use CommonJS `require()` to import `resin-cli-form`, which is now an ES Module.
  fix Change `const form = require('resin-cli-form');` to `import * as form from 'resin-cli-form';` or `import { run, ask } from 'resin-cli-form';`.

• TypeError: form.run is not a function

  cause Incorrect import syntax (e.g., trying to use `form.run` after a default import of a non-object, or a CJS import in an ESM context).
  fix Ensure you are using `import * as form from 'resin-cli-form';` or `import { run, ask } from 'resin-cli-form';` for named exports, and that your file is treated as an ESM module (e.g., `.mjs` extension or `"type": "module"` in `package.json`).

• Error: The 'engines' field in package.json specifies an unsupported Node.js version. Required: '>=20.0.0'. Found: 'v18.17.0'.

  cause Running `resin-cli-form` v5.x on an unsupported Node.js version.
  fix Upgrade your Node.js runtime to version 20.0 or higher. You can use `nvm` (Node Version Manager) to easily switch Node.js versions.

Warnings

• breaking Version 5.0.0 converted the entire library to TypeScript and ES Modules. CommonJS `require()` syntax is no longer supported. All imports must use ESM `import` statements.
  Fix: Migrate all `require()` calls to `import` statements. For example, `const form = require('resin-cli-form')` becomes `import * as form from 'resin-cli-form'` or `import { run, ask } from 'resin-cli-form'`.
• breaking Version 5.0.0 dropped the Bluebird promise library and switched to native `async/await` for asynchronous operations. While the public API still returns Promises, internal code and any direct Bluebird interactions in calling code will need adjustment.
  Fix: Ensure your environment supports `async/await`. If you were relying on Bluebird-specific Promise features, refactor to use native Promise methods or compatible utility libraries.
• breaking Node.js version requirements have progressively increased. Version 3.0.0 dropped support for Node.js versions below 18. Version 4.0.0 dropped support for Node.js 18. Version 5.0.0 and above now require Node.js 20.0 or higher.
  Fix: Upgrade your Node.js runtime to version 20.0 or newer to use resin-cli-form v5.x.x.
• gotcha The `when` property for conditional questions expects an object where keys are answer names and values are the required answer for the condition to be true. Complex logical operations (AND, OR) are handled by defining multiple key-value pairs (AND) or structuring forms differently.
  Fix: Carefully define `when` conditions; for 'OR' logic or more complex scenarios, consider using multiple questions or re-evaluating the form structure dynamically.
• breaking The project updated its GitHub organization from `resin-io-modules` to `balena-io-modules`. While npm package name remains `resin-cli-form`, be aware of updated repository and homepage URLs for contributions or issue reporting.
  Fix: Update any saved repository URLs or links to `https://github.com/balena-io-modules/resin-cli-form` for the latest information and contributions.

Install

• npm install resin-cli-form npm
• yarn add resin-cli-form yarn
• pnpm add resin-cli-form pnpm

Imports

• form
  wrong:

  const form = require('resin-cli-form');

  correct:

  import * as form from 'resin-cli-form';

  Since v5.0.0, the library is ESM-only. The main functions `run` and `ask` are exposed as properties of a default or namespace import, typically accessed as `form.run` or `form.ask`.
• run
  wrong:

  import form from 'resin-cli-form'; // then trying form.run()

  correct:

  import { run } from 'resin-cli-form';

  While `import * as form` is common, direct named imports for `run` and `ask` are also supported in v5.0.0 and later. Ensure you use named imports for individual functions.
• ask
  wrong:

  const { ask } = require('resin-cli-form');

  correct:

  import { ask } from 'resin-cli-form';

  Similar to `run`, `ask` is available as a named export. Avoid CommonJS `require` syntax as it will fail due to the library being ESM-only since v5.

Quickstart

Demonstrates how to run a declarative CLI form with conditional questions using `form.run`, including an example of the `when` property.

import { run } from 'resin-cli-form';

async function configureDevice() {
  try {
    const answers = await run([
      {
        message: 'Network Type',
        name: 'network',
        type: 'list',
        choices: ['ethernet', 'wifi']
      },
      {
        message: 'WiFi SSID',
        name: 'wifiSsid',
        type: 'input',
        when: { network: 'wifi' }
      },
      {
        message: 'WiFi Key',
        name: 'wifiKey',
        type: 'input',
        when: { network: 'wifi' }
      }
    ], {
      override: {
        // Example: pre-fill a value to skip the question
        // wifiSsid: process.env.DEFAULT_WIFI_SSID ?? ''
      }
    });
    console.log('Configuration complete. Answers:', answers);

    if (answers.network === 'wifi') {
      console.log(`Connecting to WiFi network: ${answers.wifiSsid} with key ${answers.wifiKey ? '*********' : '[no key provided]'}`);
    }

  } catch (error) {
    console.error('Form execution failed:', error);
  }
}

configureDevice();