...
Eroare Node.js · Versiuni Node: API-uri depreciate și eliminate

[DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

Pe scurt

Codul tău sau, mult mai des, un pachet din node_modules (tr46, whatwg-url, uri-js, versiuni vechi de node-fetch, ajv, eslint) încarcă modulul intern punycode, depreciat din Node 21. E doar un avertisment: actualizează pachetele; în codul tău folosește url.domainToASCII() sau new URL().

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

punycode transformă domeniile cu caractere speciale în forma ASCII folosită de DNS (magazin-ș.ro → xn--...). Node a avut mult timp propriul modul punycode, dar l-a depreciat, iar din Node 21 afișează avertismentul la rulare când e încărcat.

Avertismentul nu oprește programul. Apare o singură dată, cu (node:PID) în față. De cele mai multe ori nu vine din codul tău, ci dintr-o dependență (de exemplu tr46 și whatwg-url, folosite de node-fetch@2, jsdom sau mongodb, ori uri-js folosit de ajv și eslint).

Ca să afli de unde vine, rulează node --trace-deprecation index.js: primești stiva de apeluri până la require("punycode"). Apoi npm ls tr46 sau npm ls uri-js îți arată ce pachet îl aduce.

De ce apare: cauzele frecvente

1Codul tău folosește punycode pentru domenii

Greșit
JavaScript
const punycode = require("punycode");
console.log(punycode.toASCII("cafeneaua-ș.ro"));
Corect
JavaScript
const { domainToASCII } = require("url");
console.log(domainToASCII("cafeneaua-ș.ro"));

url.domainToASCII face aceeași conversie pentru domenii, fără modulul depreciat.

2O dependență veche

Greșit
JavaScript
"dependencies": { "node-fetch": "^2.6.7" }
Corect
JavaScript
// Node 18+ are fetch global: scoate node-fetch
const r = await fetch(url);

Actualizarea sau eliminarea pachetului care aduce tr46 / whatwg-url vechi elimină avertismentul.

3Ai nevoie de funcțiile complete punycode

Greșit
JavaScript
const punycode = require("punycode");
Corect
JavaScript
// npm install punycode
const punycode = require("punycode/");

Pachetul de pe npm cu același nume nu e depreciat. Slash-ul de la final forțează încărcarea lui din node_modules, nu a modulului intern.

Repară tu

Repară eroarea, direct în pagină

Funcția domeniuAscii transformă numele de domeniu cu diacritice în forma ASCII, dar folosește modulul intern punycode și primește [DEP0040] DeprecationWarning. Proiectul oprește programul la orice warning (primele rânduri). Fă aceeași conversie cu funcția din modulul url, ca programul să afișeze cele două domenii.

Codul care dă eroarea
JavaScript
// Proiectul tratează orice warning ca pe o eroare (ca în CI): îl afișează și oprește cu cod 1.
process.on("warning", (w) => {
  console.error(`${w.code ? `[${w.code}] ` : ""}${w.name}: ${w.message}`);
  process.exitCode = 1;
});

const punycode = require("punycode");

function domeniuAscii(domeniu) {
  return punycode.toASCII(domeniu);
}

console.log(domeniuAscii("cafea.ro"));
console.log(domeniuAscii("brânză.ro"));
După reparație, programul afișează
cafea.ro
xn--brnz-coa4r.ro
Indiciu

require("url").domainToASCII(domeniu) întoarce forma xn--....

Alte forme ale mesajului

  • (node:4120) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created)
  • DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
  • [DEP0040] DeprecationWarning: The `punycode` module is deprecated.

Cum o eviți pe viitor

  • Rulează npm outdated și actualizează periodic dependențele.
  • Când apare un avertisment nou, folosește node --trace-deprecation ca să vezi de unde vine.
  • În codul tău, pentru domenii folosește url.domainToASCII / url.domainToUnicode sau new URL(...).hostname.
  • Nu ascunde avertismentele cu --no-deprecation decât temporar: ele anunță ce se va strica la următoarele versiuni.

Întrebări frecvente

E periculos? Aplicația mea se va opri?

Deocamdată nu: e doar un avertisment, iar modulul încă funcționează. Merită totuși rezolvat, pentru că într-o versiune viitoare modulul poate dispărea.

Am actualizat tot și tot apare. Ce fac?

Uneori pachetul principal e la zi, dar trage o versiune veche printr-o dependență. Poți forța o versiune nouă cu overrides în package.json sau poți aștepta o actualizare a pachetului. Între timp avertismentul e inofensiv.

Erori înrudite

← Toate erorile Node.js

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață Node.js de la zero, cu exerciții la fiecare lecție

Curs Node.js: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 15 lecții sunt gratuite.