Ejecutar Scripts de Node.js en JavaScript

Cómo ejecutar archivos JavaScript planos con Node.js — ejecución directa, scripts de npm, líneas shebang, y análisis de argumentos de línea de comandos.

Recipe

Tarjeta de referencia rápida — lista para copiar y pegar.

# Ejecutar un script directamente
node script.js
 
# Ejecutar con reinicio automático cuando cambian archivos (Node 18.11+)
node --watch script.js
 
# Ejecutar con variables de entorno
NODE_ENV=production node script.js
 
# Pasar argumentos al script
node script.js --name Alice --verbose

// package.json — scripts de npm
{
  "name": "my-cli",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "my-cli": "./bin/cli.js"
  },
  "scripts": {
    "start": "node script.js",
    "dev": "node --watch script.js",
    "cli": "node bin/cli.js"
  }
}

// bin/cli.js — con shebang
#!/usr/bin/env node
import { parseArgs } from 'node:util';
 
const { values } = parseArgs({
  options: {
    name: { type: 'string', short: 'n' },
    verbose: { type: 'boolean', short: 'v' },
  },
});
 
console.log(`Hello, ${values.name ?? 'world'}!`);

# Hacer el script ejecutable (solo Unix/macOS)
chmod +x bin/cli.js
 
# Luego ejecutarlo directamente
./bin/cli.js --name Alice

Cuándo usarlo: Scripts de construcción, tareas de automatización, utilidades puntuales, herramientas CLI, o cualquier cosa que no quieras enviar a través de un navegador.

Ejemplo Completo

Una CLI de renombre de archivo completa que convierte nombres de archivo a minúsculas en un directorio.

#!/usr/bin/env node
// bin/rename-lower.js
import { readdir, rename } from 'node:fs/promises';
import { join } from 'node:path';
import { parseArgs } from 'node:util';
 
const { values, positionals } = parseArgs({
  options: {
    dry: { type: 'boolean', short: 'd' },
    help: { type: 'boolean', short: 'h' },
  },
  allowPositionals: true,
});
 
if (values.help || positionals.length === 0) {
  console.log('Usage: rename-lower <dir> [--dry]');
  process.exit(values.help ? 0 : 1);
}
 
const dir = positionals[0];
 
try {
  const files = await readdir(dir);
  for (const file of files) {
    const lower = file.toLowerCase();
    if (file === lower) continue;
    const from = join(dir, file);
    const to = join(dir, lower);
    if (values.dry) {
      console.log(`[dry] ${from} -> ${to}`);
    } else {
      await rename(from, to);
      console.log(`renamed ${from} -> ${to}`);
    }
  }
} catch (err) {
  console.error('Error:', err.message);
  process.exit(1);
}

// package.json
{
  "name": "rename-lower",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "rename-lower": "./bin/rename-lower.js"
  }
}

# Pruébalo localmente
npm link
rename-lower ./photos --dry
rename-lower ./photos

Lo que esto demuestra:

• Línea shebang para que el archivo se ejecute como un ejecutable independiente
• parseArgs de node:util para análisis de argv sin dependencias
• Argumentos posicionales y de bandera juntos
• Manejo de errores elegante con códigos de salida distintos de cero
• Campo bin en package.json para que npm link exponga el comando globalmente

Análisis Profundo

Cómo Funciona

Cuando escribes node script.js, Node.js:

1. Lee el archivo del disco.
2. Determina el tipo de módulo — ESM si "type": "module" está en package.json o el archivo termina en .mjs, de lo contrario CommonJS.
3. Compila y evalúa el módulo de nivel superior.
4. Expone los globales process, console, Buffer y compañía.
5. Sale cuando el event loop está vacío — o inmediatamente si llamas a process.exit().

Una línea shebang como #!/usr/bin/env node le dice al cargador del sistema operativo qué intérprete usar cuando el archivo se ejecuta directamente. La herramienta env busca node en PATH, que es más portátil que una ruta codificada /usr/local/bin/node.

process.argv es un array donde el índice 0 es la ruta del binario de Node.js, el índice 1 es la ruta del script, y el índice 2+ son los argumentos suministrados por el usuario. Por eso parseArgs omite los primeros dos por defecto.

Variaciones

# Pasar argumentos a través de un script de npm (nota el --)
npm run cli -- --name Alice
 
# Variables de entorno en línea
API_KEY=abc node script.js
 
# Modo watch (Node 18.11+)
node --watch script.js
 
# Modo watch con una entrada específica
node --watch --watch-path=./src script.js
 
# Modo inspeccionar/depurar
node --inspect-brk script.js
 
# Analizar args con la utilidad integrada
node -e "console.log(require('node:util').parseArgs({options:{n:{type:'string'}}}))" -- -n hi

Notas de TypeScript

Incluso para scripts JavaScript planos, puedes optar por type-checking sin agregar un paso de construcción habilitando // @ts-check en la parte superior del archivo y creando un jsconfig.json:

// jsconfig.json
{
  "compilerOptions": {
    "checkJs": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "lib": ["ES2022"]
  },
  "include": ["bin/**/*.js", "scripts/**/*.js"]
}

Agrega tipos JSDoc para parámetros y el editor — y tsc --noEmit — capturará errores:

// @ts-check
/** @param {string} name @returns {string} */
function greet(name) {
  return `Hello, ${name}!`;
}

Errores Comunes

1. Shebang faltante. Sin #!/usr/bin/env node, ejecutar el archivo directamente (./script.js) en shells Unix genera un error "exec format error" o ejecuta el archivo como un script de shell.
2. Olvidar chmod +x. Un shebang correcto es inútil si el archivo no es ejecutable. El permiso debe agregarse con chmod +x bin/cli.js y el bit debe ser confirmado en Git (git update-index --chmod=+x).
3. Confusión de extensión ESM vs CJS. Un archivo .js en un paquete con "type": "module" es ESM; el mismo archivo en un paquete CJS es CommonJS. Usa .mjs/.cjs para ser explícito y evitar ambigüedad.
4. __dirname es indefinido en ESM. En scripts ESM debes reconstruirlo: const __dirname = path.dirname(fileURLToPath(import.meta.url)).
5. Terminaciones de línea Windows en scripts. Un shebang con CRLF (\r\n) falla en Linux/macOS con "bad interpreter". Fuerza LF a través de .gitattributes: *.js text eol=lf.
6. Olvidar -- en scripts de npm. npm run cli --name Alice pasa --name Alice a npm, no a tu script. Usa npm run cli -- --name Alice.
7. Indexación de process.argv. El índice 0 y 1 son el binario de Node y la ruta del script — tus argumentos de usuario comienzan en el índice 2.

Alternativas

Preguntas Frecuentes

Relacionado

• Ejecutar Scripts de TypeScript
• ESM vs CommonJS Modules
• Variables de Entorno
• Comandos de Git Esenciales