From de3a86b5531375deb2b5779cfc00deae39a80e6e Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sat, 5 Mar 2022 23:43:29 +0100
Subject: [PATCH] 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>
---
 doc/api/http2.md | 35 +++++++++++++++++++++++++++++++++++
 doc/api/https.md | 37 +++++++++++++++++++++++++++++++++++++
 doc/api/tls.md   | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 109 insertions(+)

diff --git a/doc/api/http2.md b/doc/api/http2.md
index 5bd91a5719c89a..54d5c8aee26930 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -30,6 +30,41 @@ can be accessed using:
 const http2 = require('http2');
 ```
 
+## 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 `http2` or
+calling `require('http2')` will result in an error being thrown.
+
+When using CommonJS, the error thrown can be caught using try/catch:
+
+```cjs
+let http2;
+try {
+  http2 = require('http2');
+} catch (err) {
+  console.log('http2 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 http2;
+try {
+  http2 = await import('http2');
+} catch (err) {
+  console.log('http2 support is disabled!');
+}
+```
+
 ## Core API
 
 The Core API provides a low-level interface designed specifically around
diff --git a/doc/api/https.md b/doc/api/https.md
index a8155384077a5e..3a28f3b0f00bfc 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
diff --git a/doc/api/tls.md b/doc/api/tls.md
index d082ed3c80587a..ad0f5d013cc683 100644
--- a/doc/api/tls.md
+++ b/doc/api/tls.md
@@ -14,6 +14,43 @@ The module can be accessed using:
 const tls = require('tls');
 ```
 
+## 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 `tls` or
+calling `require('tls')` will result in an error being thrown.
+
+When using CommonJS, the error thrown can be caught using try/catch:
+
+<!-- eslint-skip -->
+
+```cjs
+let tls;
+try {
+  tls = require('tls');
+} catch (err) {
+  console.log('tls 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 tls;
+try {
+  tls = await import('tls');
+} catch (err) {
+  console.log('tls support is disabled!');
+}
+```
+
 ## TLS/SSL concepts
 
 TLS/SSL is a set of protocols that rely on a public key infrastructure (PKI) to