auto-importer Usage Guide

This version of the guide explains how to install and use the auto-importer package to automatically install and import npm packages at runtime.

Requirements

• Node.js >= 12 (or a version that supports async/await).
• Write permission to the project directory (node_modules and package.json if npm install --save is used).

Installation

Install auto-importer into your project as a dependency:

npm install auto-importer
# or (optional):
# yarn add auto-importer
# pnpm add auto-importer

Note: auto-importer itself will call npm install <package> when needed. If you use yarn/pnpm, see the "Advanced Tips" section below.

Basic Example (CommonJS)

The code you provided:

const { use } = require("auto-import-package");

(async () => {
    const chalk = await use("chalk");
    console.log(chalk.green("Hello world!"));
})();

Short explanation:

• use("chalk") will try to require("chalk") first.
• If the package is not present, auto-importer will run npm install chalk (in the current project folder), then require it again and return the module.
• use returns the required module, so you use it as normal (in the example: chalk.green(...)).

ESM Example (module)

If your project uses ESM (type: "module" in package.json) and Node supports top-level await:

import { use } from "auto-import-package";

const chalk = await use("chalk");
console.log(chalk.green("Hello world!"));

If you don't have top-level await, wrap in an async function:

import { use } from "auto-import-package";

async function main() {
  const chalk = await use("chalk");
  console.log(chalk.green("Hello world!"));
}

main();

Brief API

Note: this guide describes the basic API. If you use an advanced version with additional options, consult the package README.

use(packageName: string): Promise<any>

• packageName: the npm package name (for example: "axios" or "[email protected]" to specify a version).
• Returns: a Promise that resolves to the module that was required / imported.

Example:

const express = await use('express');
const _ = await use('[email protected]');

Advanced Tips

• Specify version: await use('[email protected]') will install that version.
• Scoped packages: await use('@scope/something') works normally.
• Preinstall: You can add important dependencies to the project's package.json to avoid runtime installs.
• Using with yarn/pnpm: By default auto-importer calls npm install. If you want to use yarn/pnpm, you need an auto-importer version that supports a pkgManager option or set up aliases (or have a compatible npm CLI). Currently it's recommended to use npm to avoid installation race conditions.

Security & Risks

• Be cautious when auto-installing packages at runtime: attackers can exploit this to install malicious code if you use() a package name provided by an untrusted user. Only use this pattern when you control package names or validate/sanitize them.
• Best practice: pin important dependencies in package.json before deployment.
• Permissions: npm install may require write permissions; in production environments (e.g., servers with restricted permissions) runtime auto-install may fail.

Common Error Handling

• EACCES / permission denied: run with appropriate permissions or grant write access to the project directory, or install the package manually.
• network / timeout: check network connectivity, the npm registry (npmjs.org), or proxy configuration.
• require not found after install: try restarting the Node process (usually not necessary because require can load the newly installed module); if the module is ESM or has a different entry, you might need dynamic import().

Practical Example — multiple packages

const { use } = require('auto-import-package');

(async () => {
  const axios = await use('axios');
  const lodash = await use('lodash');

  const res = await axios.get('https://api.github.com');
  console.log('Status:', res.status);
  console.log('Keys:', Object.keys(lodash));
})();

Development Suggestions (if you are the author)

• Support a pkgManager option (npm/yarn/pnpm).
• Provide dryRun / confirm options to warn before installing.
• Cache metadata (to avoid calling npm view excessively).
• Support dynamic import() for ESM-only packages.

License

Copyright © 2025 by Vienxamxi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.