Add esbuild and Nuxt2 bundling issue with JS SDK v3.7.0 installat…

…ion to FAQ

Esbuild issue: evanw/esbuild#2692
Nuxt2/Webpackv4 issue: #2498 (comment)

docs/modules/faqs.html

@@ -156,10 +156,15 @@ <h3>I cannot join meeting in Firefox with no audio and video permission due to <
 					<a href="#known-build-issues" id="known-build-issues" style="color: inherit; text-decoration: none;">
 						<h2>Known Build Issues</h2>
 					</a>
-					<a href="#why-is-my-build-with-rollup-failing-after-upgrading-to-amazon-chime-sdk-for-javascript-370" id="why-is-my-build-with-rollup-failing-after-upgrading-to-amazon-chime-sdk-for-javascript-370" style="color: inherit; text-decoration: none;">
-						<h3>Why is my build with rollup failing after upgrading to Amazon Chime SDK for JavaScript 3.7.0?</h3>
+					<a href="#why-is-my-build-failing-after-upgrading-to-amazon-chime-sdk-for-javascript-370" id="why-is-my-build-failing-after-upgrading-to-amazon-chime-sdk-for-javascript-370" style="color: inherit; text-decoration: none;">
+						<h3>Why is my build failing after upgrading to Amazon Chime SDK for JavaScript 3.7.0?</h3>
+					</a>
+					<p>Amazon Chime SDK for JavaScript 3.7.0 included a bug fix to mitigate messaging session reconnection issue. Check <a href="https://github.com/aws/amazon-chime-sdk-js/commit/bce872c353edbb50908c5a0298f8113f1e8dcc82#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519">MessagingSession reconnects with refreshed endpoint and credentials if needed</a> for more information on the fix. We added <code>@aws-sdk/client-chime-sdk-messaging</code> dependency necessary to mitigate the fix. <code>@aws-sdk/client-chime-sdk-messaging</code> pulls in <code>aws-sdk</code> v3 dependency and its dependencies cause the build to fail in all cases.</p>
+					<p>Depending on the bundler you use, certain additional configuration changes may be required to help the build to succeed. This is actually not an issue with Amazon Chime SDK for JavaScript rather an issue on how bundlers do module resolution and what distributions <code>@aws-sdk/client-chime-sdk-messaging</code>&#39;s dependencies provide when bundlers try to resolve the imported modules.</p>
+					<p>As of now, builders have reported issues with rollup, esbuild, Nuxt2 framework and Webpack v4. In the following sections each issue is described separately and suggests certain configuration changes for the build to succeed.</p>
+					<a href="#rollup" id="rollup" style="color: inherit; text-decoration: none;">
+						<h4>Rollup</h4>
 					</a>
-					<p>Amazon Chime SDK for JavaScript 3.7.0 included a bug fix to mitigate messaging session reconnection issue. Check <a href="https://github.com/aws/amazon-chime-sdk-js/commit/bce872c353edbb50908c5a0298f8113f1e8dcc82#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519">MessagingSession reconnects with refreshed endpoint and credentials if needed</a> for more information on the fix. We added <code>@aws-sdk/client-chime-sdk-messaging</code> dependency necessary to mitigate the fix. This may further result into rollup bundling failures with certain configurations.</p>
 					<p>When a builder makes use of the rollup plugin: <code>rollup-plugin-includepaths</code> they may run into build issues where node modules and their methods are not found. For example, in the following warnings / errors the Node.js built-ins and the <code>createHash</code> method from <code>crypto</code> is not found.</p>
 					<pre><code><span style="color: #000000">(!) </span><span style="color: #001080">Missing</span><span style="color: #000000"> </span><span style="color: #001080">shims</span><span style="color: #000000"> </span><span style="color: #001080">for</span><span style="color: #000000"> </span><span style="color: #001080">Node</span><span style="color: #000000">.</span><span style="color: #001080">js</span><span style="color: #000000"> </span><span style="color: #001080">built</span><span style="color: #000000">-</span><span style="color: #001080">ins</span>
 <span style="color: #001080">Creating</span><span style="color: #000000"> </span><span style="color: #001080">a</span><span style="color: #000000"> </span><span style="color: #001080">browser</span><span style="color: #000000"> </span><span style="color: #001080">bundle</span><span style="color: #000000"> </span><span style="color: #001080">that</span><span style="color: #000000"> </span><span style="color: #001080">depends</span><span style="color: #000000"> </span><span style="color: #001080">on</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;os&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;path&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;url&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;buffer&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;http&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;https&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;stream&quot;</span><span style="color: #000000">, </span><span style="color: #A31515">&quot;process&quot;</span><span style="color: #000000"> </span><span style="color: #001080">and</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;util&quot;</span><span style="color: #000000">. </span><span style="color: #001080">You</span><span style="color: #000000"> </span><span style="color: #001080">might</span><span style="color: #000000"> </span><span style="color: #001080">need</span><span style="color: #000000"> </span><span style="color: #001080">to</span><span style="color: #000000"> </span><span style="color: #001080">include</span><span style="color: #000000"> https:</span><span style="color: #008000">//github.com/FredKSchott/rollup-plugin-polyfill-node</span>
@@ -171,6 +176,43 @@ <h3>Why is my build with rollup failing after upgrading to Amazon Chime SDK for
 					<p>This node / browser incompatibility issue happens due to bundlers not using the right <code>runtimeConfig</code> defined in AWS JS SDK client&#39;s <code>package.json</code>. Clients in AWS JS SDK have defined a runtime config alias in their <code>package.json</code> like this: <a href="https://github.com/aws/aws-sdk-js-v3/blob/main/clients/client-chime-sdk-messaging/package.json#L91">Chime SDK Messaging client package.json</a>. If your bundler does not follow the <code>runtimeConfig</code> alias, you can get some incompatibility errors.</p>
 					<p>If the builder is using <a href="https://github.com/dot-build/rollup-plugin-includepaths">rollup-plugin-includepaths</a> to use relative paths in their project. It is recommended that you use <a href="https://github.com/rollup/plugins/tree/master/packages/alias">rollup-plugin-alias</a> to define an alias for relative paths.</p>
 					<p>You can find more information about this build error in GitHub issue: <a href="https://github.com/aws/amazon-chime-sdk-js/issues/2455">3.7.0 broke build with Rollup</a>. If you still have questions about rollup alias and plugin settings please reach out to the plugin / rollup author.</p>
+					<a href="#esbuild" id="esbuild" style="color: inherit; text-decoration: none;">
+						<h4>Esbuild</h4>
+					</a>
+					<p>When bundling an application using <code>esbuild</code>, it checks for dependency distributions depending on whether the imported package follows <code>require</code> that is CommonJS or <code>import</code> that is EcmaScript Module (ESM) approach. The dependency package can have its own dependencies which <code>esbuild</code> will try to resolve using the CommonJS or ESM distributions provided by the dependency package. Each package has to provide a link to the distribution path in their <code>package.json</code> using <code>main</code>, <code>module</code> or <code>browser</code> fields. In <code>@aws-sdk/client-chime-sdk-messaging</code> case, the <code>esbuild</code> runs into an issue where it cannot pick the distribution for <code>browser</code> specifially for one of the dependencies, thus, failing to build with below error:</p>
+					<pre><code><span style="color: #A31515">&quot;../node_modules/@aws-sdk/smithy-client&quot;</span>
+<span style="color: #000000">          </span><span style="color: #001080">Attempting</span><span style="color: #000000"> </span><span style="color: #001080">to</span><span style="color: #000000"> </span><span style="color: #001080">load</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;../node_modules/@aws-sdk/smithy-client/dist-es/index.js&quot;</span><span style="color: #000000"> </span><span style="color: #AF00DB">as</span><span style="color: #000000"> </span><span style="color: #267F99">a</span><span style="color: #000000"> </span><span style="color: #267F99">file</span>
+<span style="color: #000000">            </span><span style="color: #001080">Checking</span><span style="color: #000000"> </span><span style="color: #001080">for</span><span style="color: #000000"> </span><span style="color: #001080">file</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;index.js&quot;</span>
+<span style="color: #000000">            </span><span style="color: #001080">Found</span><span style="color: #000000"> </span><span style="color: #001080">file</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;index.js&quot;</span>
+<span style="color: #000000">        </span><span style="color: #001080">Found</span><span style="color: #000000"> </span><span style="color: #001080">main</span><span style="color: #000000"> </span><span style="color: #001080">field</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;main&quot;</span><span style="color: #000000"> </span><span style="color: #AF00DB">with</span><span style="color: #000000"> </span><span style="color: #001080">path</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;./dist-cjs/index.js&quot;</span>
+<span style="color: #000000">          </span><span style="color: #001080">No</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;browser&quot;</span><span style="color: #000000"> </span><span style="color: #001080">map</span><span style="color: #000000"> </span><span style="color: #001080">found</span><span style="color: #000000"> </span><span style="color: #0000FF">in</span><span style="color: #000000"> </span><span style="color: #001080">directory</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;../node_modules/@aws-sdk/smithy-client&quot;</span>
+<span style="color: #000000">          </span><span style="color: #001080">Attempting</span><span style="color: #000000"> </span><span style="color: #001080">to</span><span style="color: #000000"> </span><span style="color: #001080">load</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;../node_modules/@aws-sdk/smithy-client/dist-cjs/index.js&quot;</span><span style="color: #000000"> </span><span style="color: #AF00DB">as</span><span style="color: #000000"> </span><span style="color: #267F99">a</span><span style="color: #000000"> </span><span style="color: #267F99">file</span>
+<span style="color: #000000">            </span><span style="color: #001080">Checking</span><span style="color: #000000"> </span><span style="color: #001080">for</span><span style="color: #000000"> </span><span style="color: #001080">file</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;index.js&quot;</span>
+<span style="color: #000000">            </span><span style="color: #001080">Found</span><span style="color: #000000"> </span><span style="color: #001080">file</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;index.js&quot;</span>
+<span style="color: #000000">        </span><span style="color: #001080">Resolved</span><span style="color: #000000"> </span><span style="color: #001080">to</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;../node_modules/@aws-sdk/smithy-client/dist-cjs/index.js&quot;</span><span style="color: #000000"> </span><span style="color: #001080">because</span><span style="color: #000000"> </span><span style="color: #0000FF">of</span><span style="color: #000000"> </span><span style="color: #A31515">&quot;require&quot;</span>
+</code></pre>
+					<p>To resolve this, add <code>--main-fields=browser,module,main</code> when you bundle your application using <code>esbuild</code>. For more information, check <a href="https://github.com/evanw/esbuild/issues/2692">this issue</a> we reported to <code>esbuild</code>.</p>
+					<a href="#using-amazon-chime-sdk-for-javascript-in-nuxt2-framework" id="using-amazon-chime-sdk-for-javascript-in-nuxt2-framework" style="color: inherit; text-decoration: none;">
+						<h4>Using Amazon Chime SDK for JavaScript in Nuxt2 framework</h4>
+					</a>
+					<p>You can use Amazon Chime SDK for JavaScript in Nuxt2 framework. Nuxt2 framework uses Webpack v4 bundler for bundling the application. Webpack v4 has a known issue when bundling applications that use optional chaining operator. This is resolved in Webpack v5, but, Nuxt2 has not upgraded to use Webpack v5.</p>
+					<p>Thus, when bundling a Nuxt2 application which imports Amazon Chime SDK for JavaScript v3.7.0 and above, it runs into below error:</p>
+					<pre><code><span style="color: #0070C1">ERROR</span><span style="color: #000000"> </span><span style="color: #0000FF">in</span><span style="color: #000000"> .</span><span style="color: #811F3F">/node_modules/</span><span style="color: #000000">@</span><span style="color: #001080">aws</span><span style="color: #000000">-</span><span style="color: #001080">sdk</span><span style="color: #000000">/</span><span style="color: #001080">signature</span><span style="color: #000000">-</span><span style="color: #001080">v4</span><span style="color: #000000">/</span><span style="color: #001080">dist</span><span style="color: #000000">-</span><span style="color: #001080">es</span><span style="color: #000000">/</span><span style="color: #001080">getCanonicalHeaders</span><span style="color: #000000">.</span><span style="color: #001080">js</span><span style="color: #000000"> </span><span style="color: #098658">10</span><span style="color: #000000">:</span><span style="color: #098658">30</span>
+<span style="color: #001080">Module</span><span style="color: #000000"> </span><span style="color: #001080">parse</span><span style="color: #000000"> failed: </span><span style="color: #001080">Unexpected</span><span style="color: #000000"> </span><span style="color: #795E26">token</span><span style="color: #000000"> (</span><span style="color: #098658">10</span><span style="color: #000000">:</span><span style="color: #098658">30</span><span style="color: #000000">)</span>
+<span style="color: #001080">You</span><span style="color: #000000"> </span><span style="color: #001080">may</span><span style="color: #000000"> </span><span style="color: #001080">need</span><span style="color: #000000"> </span><span style="color: #001080">an</span><span style="color: #000000"> </span><span style="color: #001080">appropriate</span><span style="color: #000000"> </span><span style="color: #001080">loader</span><span style="color: #000000"> </span><span style="color: #001080">to</span><span style="color: #000000"> </span><span style="color: #001080">handle</span><span style="color: #000000"> </span><span style="color: #0000FF">this</span><span style="color: #000000"> </span><span style="color: #001080">file</span><span style="color: #000000"> </span><span style="color: #001080">type</span><span style="color: #000000">, </span><span style="color: #001080">currently</span><span style="color: #000000"> </span><span style="color: #001080">no</span><span style="color: #000000"> </span><span style="color: #001080">loaders</span><span style="color: #000000"> </span><span style="color: #001080">are</span><span style="color: #000000"> </span><span style="color: #001080">configured</span><span style="color: #000000"> </span><span style="color: #001080">to</span><span style="color: #000000"> </span><span style="color: #001080">process</span><span style="color: #000000"> </span><span style="color: #0000FF">this</span><span style="color: #000000"> </span><span style="color: #001080">file</span><span style="color: #000000">. </span><span style="color: #001080">See</span><span style="color: #000000"> https:</span><span style="color: #008000">//webpack.js.org/concepts#loaders</span>
+<span style="color: #000000">|         </span><span style="color: #0000FF">const</span><span style="color: #000000"> </span><span style="color: #0070C1">canonicalHeaderName</span><span style="color: #000000"> = </span><span style="color: #001080">headerName</span><span style="color: #000000">.</span><span style="color: #795E26">toLowerCase</span><span style="color: #000000">();</span>
+<span style="color: #000000">|         </span><span style="color: #AF00DB">if</span><span style="color: #000000"> (</span><span style="color: #001080">canonicalHeaderName</span><span style="color: #000000"> </span><span style="color: #0000FF">in</span><span style="color: #000000"> </span><span style="color: #0070C1">ALWAYS_UNSIGNABLE_HEADERS</span><span style="color: #000000"> ||</span>
+<span style="color: #000000">&gt;             </span><span style="color: #001080">unsignableHeaders</span><span style="color: #000000">?.</span><span style="color: #795E26">has</span><span style="color: #000000">(</span><span style="color: #001080">canonicalHeaderName</span><span style="color: #000000">) ||</span>
+<span style="color: #000000">|             </span><span style="color: #0070C1">PROXY_HEADER_PATTERN</span><span style="color: #000000">.</span><span style="color: #795E26">test</span><span style="color: #000000">(</span><span style="color: #001080">canonicalHeaderName</span><span style="color: #000000">) ||</span>
+<span style="color: #000000">|             </span><span style="color: #0070C1">SEC_HEADER_PATTERN</span><span style="color: #000000">.</span><span style="color: #795E26">test</span><span style="color: #000000">(</span><span style="color: #001080">canonicalHeaderName</span><span style="color: #000000">)) {</span>
+<span style="color: #000000"> @ .</span><span style="color: #811F3F">/node_modules/</span><span style="color: #000000">@</span><span style="color: #001080">aws</span><span style="color: #000000">-</span><span style="color: #001080">sdk</span><span style="color: #000000">/</span><span style="color: #001080">signature</span><span style="color: #000000">-</span><span style="color: #001080">v4</span><span style="color: #000000">/</span><span style="color: #001080">dist</span><span style="color: #000000">-</span><span style="color: #001080">es</span><span style="color: #000000">/</span><span style="color: #001080">index</span><span style="color: #000000">.</span><span style="color: #001080">js</span><span style="color: #000000"> </span><span style="color: #098658">2</span><span style="color: #000000">:</span><span style="color: #098658">0</span><span style="color: #000000">-</span><span style="color: #098658">60</span><span style="color: #000000"> </span><span style="color: #098658">2</span><span style="color: #000000">:</span><span style="color: #098658">0</span><span style="color: #000000">-</span><span style="color: #098658">60</span>
+</code></pre>
+					<p>To resolve this, you have to override the <code>build</code> configuration in <code>nuxt.config.js</code> like below:</p>
+					<pre><code><span style="color: #000000">build: {</span>
+<span style="color: #000000">  transpile: [</span><span style="color: #A31515">&quot;aws-sdk&quot;</span><span style="color: #000000">]</span>
+<span style="color: #000000">}</span>
+</code></pre>
+					<p>Check <a href="https://github.com/aws/amazon-chime-sdk-js/issues/2498#issuecomment-1362279568">this issue comment</a> for more information on the issue.</p>
 					<a href="#meetings" id="meetings" style="color: inherit; text-decoration: none;">
 						<h2>Meetings</h2>
 					</a>