(DOCSP-10493): require() for playgrounds (mongodb#17)

* (DOCSP-10539): require() for playgrounds

* fix typo in example

Author: jeff-allen-mongo

source/playgrounds.txt

@@ -52,7 +52,7 @@ Tutorials
 - To learn how to use MongoDB Playgrounds for CRUD operations, see
   :ref:`vsce-crud`.
 
-- To learn how to use MonogDB Playgrounds to run aggregation
+- To learn how to use MongoDB Playgrounds to run aggregation
   pipelines, see :ref:`vsce-aggregation`.
 
 Consideration for Authentication
@@ -67,3 +67,4 @@ Consideration for Authentication
 
       /crud-ops
       /run-agg-pipelines
+      /require-modules

source/require-modules.txt

@@ -0,0 +1,122 @@
+.. _vsce-require:
+
+=============================================
+Use ``require()`` to Include External Modules
+=============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. include:: /includes/fact-vsce-preview.rst
+
+.. important::
+
+   A complete description of Node.js, modules, and the
+   `require() <https://nodejs.org/api/modules.html#modules_require_id>`__
+   function is out of scope for this tutorial. To learn more, refer to
+   the `Node.js Documentation <https://nodejs.org/api/modules.html>`__.
+
+You can use the
+`require() <https://nodejs.org/api/modules.html#modules_require_id>`__
+function in your MongoDB Playgrounds to
+include modules which exist in separate files.
+
+Require Native Modules
+----------------------
+
+You can ``require()`` native Node modules (such as
+`fs <https://nodejs.org/api/fs.html#fs_file_system>`__) in your
+Playground without any additional setup or configuration.
+
+.. example::
+
+   The following Playground uses the ``fs`` module to write a document
+   from the ``test.employees`` collection to a file named
+   ``employee.txt``:
+
+   .. code-block:: javascript
+
+      const fs = require('fs');
+
+      use("test");
+
+      const document = db.employees.findOne();
+
+      fs.writeFileSync('employee.txt', JSON.stringify(document));
+
+   .. seealso::
+
+      - `fs.writeFileSync
+        <https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options>`__
+
+      - `require()
+        <https://nodejs.org/api/modules.html#modules_require_id>`__
+
+Require Non-Native Modules
+--------------------------
+
+To ``require()`` non-native Node modules (such as those downloaded from
+`npm <https://www.npmjs.com/>`__) you must install the module in one of
+the following folders based on your operating system:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40
+
+   * - Operating System
+     - Module Location
+
+   * - macOS and Linux
+     - One of either:
+
+       - ``$HOME/.node_modules``
+     
+       - ``$HOME/node_modules``
+
+       - ``$HOME/.vscode/extensions/node_modules``
+
+       - ``$HOME/.vscode/extensions/mongodb.mongodb-vs-code-<version>\node_modules``
+
+   * - Windows
+     - One of either:
+
+       - ``C:\Users\.node_modules``
+
+       - ``C:\Users\node_modules``
+
+       - ``C:\Users\<user>\node_modules``
+       
+       - ``C:\Users\<user>\.vscode\extensions\node_modules``
+       
+       - ``C:\Users\<user>\.vscode\extensions\mongodb.mongodb-vscode-<version>\node_modules``
+
+Once you install or copy your desired package to one of the module
+directories, you can ``require()`` that package.
+
+.. example::
+
+   The following Playground uses the
+   `moment <https://www.npmjs.com/package/moment>`__ package to write
+   the current date to a file called ``date.txt``:
+
+   .. code-block:: javascript
+
+      const moment = require('moment');
+      const fs = require('fs');
+
+      const currentDate = moment().format("MMMM DD YYYY");
+
+      fs.writeFileSync('date.txt', currentDate);
+
+   .. seealso::
+
+      - `fs.writeFileSync
+        <https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options>`__
+
+      - `require()
+        <https://nodejs.org/api/modules.html#modules_require_id>`__