CLI Autocomplete Prompt (Standalone)

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use an `import` statement for `inquirer-autocomplete-standalone` in a CommonJS project without proper ESM configuration.
  fix Add `"type": "module"` to your `package.json` to make your project an ESM module, or use dynamic import for this package in CommonJS: `const { default: autocomplete } = await import('inquirer-autocomplete-standalone');`

• TypeError: autocomplete is not a function

  cause Occurs when attempting to use `require('inquirer-autocomplete-standalone')` and treating the result as a function, which is incorrect for an ESM default export when dynamically imported in CJS, or when `require` fails to resolve the module.
  fix For CommonJS, ensure you are using dynamic import and correctly accessing the default export: `const { default: autocomplete } = await import('inquirer-autocomplete-standalone');`. Verify the package is correctly installed.

• Error: Cannot find module 'inquirer-autocomplete-standalone'

  cause The package `inquirer-autocomplete-standalone` is not installed or the `inquirer-autocomplete-prompt` (legacy) package was installed instead.
  fix Run `npm install inquirer-autocomplete-standalone`. If `inquirer-autocomplete-prompt` was mistakenly installed, uninstall it first with `npm uninstall inquirer-autocomplete-prompt`.

Warnings

• breaking The `inquirer-autocomplete-standalone` package is fundamentally an ECMAScript Module (ESM). It does not support direct `require()` calls in CommonJS environments. Attempting to use `require()` will result in import errors.
  Fix: Ensure your project is configured for ESM (add `"type": "module"` to `package.json` and use `import` statements), or use dynamic `await import()` for CommonJS environments: `const { default: autocomplete } = await import('inquirer-autocomplete-standalone');`
• gotcha There are two similarly named packages: `inquirer-autocomplete-standalone` (this package, recommended, ESM-first, standalone) and `inquirer-autocomplete-prompt` (the legacy package, which has CJS v2 and ESM v3). Installing the wrong package is a common mistake that leads to import errors or unexpected behavior.
  Fix: Always verify you are installing `inquirer-autocomplete-standalone` for the modern, standalone prompt experience. If you need the legacy `inquirer-autocomplete-prompt` for Inquirer v9 or older, install that specifically.
• gotcha When using `inquirer-autocomplete-standalone` (an ESM package) within a TypeScript project that is configured to emit CommonJS, you may encounter module resolution issues. Specific `tsconfig.json` settings are often required for correct compilation and runtime behavior.
  Fix: Consult the official TypeScript documentation or examples (e.g., the `import-esm-in-typescript-examples` repository linked in the package README) for guidance on configuring `tsconfig.json` with settings like `"esModuleInterop": true` and `"moduleResolution": "bundler"` or `"node16"`.
• gotcha While designed to integrate seamlessly with Inquirer.js, `inquirer-autocomplete-standalone` functions as a decoupled prompt. Users migrating from the legacy `inquirer-autocomplete-prompt` might need to adapt their Inquirer.js registration or usage patterns (e.g., `inquirer.registerPrompt`) to utilize this standalone version effectively.
  Fix: Refer to the usage examples for `inquirer-autocomplete-standalone` and the latest Inquirer.js documentation on integrating custom or standalone prompts.

Install

• npm install inquirer-autocomplete-standalone npm
• yarn add inquirer-autocomplete-standalone yarn
• pnpm add inquirer-autocomplete-standalone pnpm

Imports

• autocomplete
  wrong:

  const autocomplete = require('inquirer-autocomplete-standalone');

  correct:

  import autocomplete from 'inquirer-autocomplete-standalone';

  This package is an ES module. For CommonJS, use dynamic import: `const { default: autocomplete } = await import('inquirer-autocomplete-standalone');`
• Separator
  wrong:

  const { Separator } = require('inquirer-autocomplete-standalone');

  correct:

  import { Separator } from 'inquirer-autocomplete-standalone';

  Named exports are also ESM-only. For CommonJS, use dynamic import: `const { Separator } = await import('inquirer-autocomplete-standalone');`
• Type (generic)

  import autocomplete, { Separator, Choice } from 'inquirer-autocomplete-standalone';

  Types like `Choice` and `Separator` are available for TypeScript users directly from the package. Ensure your `tsconfig.json` supports ESM imports if emitting CommonJS.

Quickstart

Demonstrates a basic asynchronous autocomplete prompt, allowing users to select a country from a dynamically filtered list, simulating an external API call.

import autocomplete from 'inquirer-autocomplete-standalone';

interface CountryChoice {
  value: string;
  description: string;
}

// Mock an asynchronous search function that simulates an API call
async function searchCountries(input?: string): Promise<string[]> {
  const allCountries = [
    'Norway', 'Sweden', 'Denmark', 'Finland', 'Iceland',
    'Germany', 'France', 'Spain', 'Italy', 'Portugal',
    'United Kingdom', 'Ireland', 'Canada', 'United States',
    'Mexico', 'Brazil', 'Argentina', 'Australia', 'New Zealand',
    'Japan', 'China', 'India', 'South Africa'
  ];
  const normalizedInput = (input || '').toLowerCase();
  await new Promise(resolve => setTimeout(resolve, 100)); // Simulate API delay
  return allCountries.filter(country =>
    country.toLowerCase().includes(normalizedInput)
  ).slice(0, 10); // Limit results to 10 for display
}

async function runPrompt() {
  console.log('Starting autocomplete prompt...');
  const answer = await autocomplete<string>({ // Specify the type for the selected value
    message: 'Travel from what country?',
    source: async (input) => {
      const filteredCountries = await searchCountries(input);
      return filteredCountries.map(country => ({
        value: country,
        description: `${country} is a great place to visit`,
      }));
    },
    // Optional settings:
    // default: 'Norway', // Pre-select a default value
    // suggestOnly: false, // If true, allows arbitrary input not in the list
  });

  console.log(`\nYou selected: ${answer}`);
  process.exit(0); // Ensure the process exits cleanly after prompt interaction
}

runPrompt().catch(console.error);