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>
This commit is contained in:
Antoine du Hamel
2022-03-05 23:43:29 +01:00
committed by GitHub
parent 91cc4fa32d
commit de3a86b553
3 changed files with 109 additions and 0 deletions

View File

@@ -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