diff options
author | Antoine du Hamel <duhamelantoine1995@gmail.com> | 2022-03-06 01:43:29 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-03-06 01:43:29 +0300 |
commit | de3a86b5531375deb2b5779cfc00deae39a80e6e (patch) | |
tree | cdfd14b299c48898deba7851aefa5b94e61da65f /doc/api/https.md | |
parent | 91cc4fa32d98952312b5bc543b4f0cd43246112b (diff) |
doc: clarify that some modules don't work when compiled without ssl
PR-URL: https://github.com/nodejs/node/pull/42198
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Richard Lau <rlau@redhat.com>
Reviewed-By: Mestery <mestery@protonmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Diffstat (limited to 'doc/api/https.md')
-rw-r--r-- | doc/api/https.md | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/doc/api/https.md b/doc/api/https.md index a8155384077..3a28f3b0f00 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -9,6 +9,43 @@ HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a separate module. +## Determining if crypto support is unavailable + +It is possible for Node.js to be built without including support for the +`crypto` module. In such cases, attempting to `import` from `https` or +calling `require('https')` will result in an error being thrown. + +When using CommonJS, the error thrown can be caught using try/catch: + +<!-- eslint-skip --> + +```cjs +let https; +try { + https = require('https'); +} catch (err) { + console.log('https support is disabled!'); +} +``` + +When using the lexical ESM `import` keyword, the error can only be +caught if a handler for `process.on('uncaughtException')` is registered +_before_ any attempt to load the module is made (using, for instance, +a preload module). + +When using ESM, if there is a chance that the code may be run on a build +of Node.js where crypto support is not enabled, consider using the +`import()` function instead of the lexical `import` keyword: + +```mjs +let https; +try { + https = await import('https'); +} catch (err) { + console.log('https support is disabled!'); +} +``` + ## Class: `https.Agent` <!-- YAML |