From a90e80b0e75afd1a9a2392c72f7a93738da12434 Mon Sep 17 00:00:00 2001
From: Yanks Yoon <yangsoo.yoon@canonical.com>
Date: Wed, 22 Jan 2025 03:54:35 +0000
Subject: [PATCH] docs: expressjs explaination of different combinations

---
 .../extensions/expressjs-framework.rst        | 100 ++++++++++++++++++
 docs/explanation/extensions/index.rst         |  12 +++
 docs/explanation/index.rst                    |   1 +
 3 files changed, 113 insertions(+)
 create mode 100644 docs/explanation/extensions/expressjs-framework.rst
 create mode 100644 docs/explanation/extensions/index.rst

diff --git a/docs/explanation/extensions/expressjs-framework.rst b/docs/explanation/extensions/expressjs-framework.rst
new file mode 100644
index 000000000..b670d84c5
--- /dev/null
+++ b/docs/explanation/extensions/expressjs-framework.rst
@@ -0,0 +1,100 @@
+.. _expressjs-framework-explanation:
+
+expressjs-framework
+===================
+
+When using the expressjs-framework extension, there are four different cases for
+customizing the Ubuntu base and the Node version to be included.
+The main difference is
+- whether the bare base is used or the Ubuntu 24.04 base is used.
+- whether the Node is installed from Ubuntu packages or the NPM plugin.
+
+Ubuntu base and Node combinations
+---------------------------------
+
+Bare base and Node from Ubuntu packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    base: bare
+    build-base: ubuntu@24.04
+    parts:
+        expressjs-framework/install-app:
+            plugin: npm
+            npm-include-node: false
+            build-packages:
+            - nodejs
+            - npm
+            stage-packages:
+            - bash_bins
+            - coreutils_bins
+            - nodejs_bins
+        expressjs-framework/runtime:
+            plugin: nil
+            stage-packages:
+            - npm
+
+In this case, the ``npm`` package is installed in a separate ``expressjs-framework/runtime`` part.
+This is due to ``expressjs-framework/install-app > stage-packages`` part only being able to install
+slices rather than packages as a design choice of Rockcraft. See the comment
+https://github.com/canonical/rockcraft/issues/785#issuecomment-2572990545 for more explanation.
+
+Bare base and Node from NPM plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    base: bare
+    build-base: ubuntu@24.04
+    parts:
+        expressjs-framework/install-app:
+            plugin: npm
+            npm-include-node: true
+            npm-node-version: 20.12
+            stage-packages:
+            - bash_bins
+            - coreutils_bins
+            - nodejs_bins
+
+In this case, the ``expressjs-framework/install-app > build-packages`` part is empty. The
+application is is installed using Node and NPM installed by the NPM plugin. The application is run
+using the NPM installed by the NPM plugin.
+
+24.04 base and Node from Ubuntu packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    base: ubuntu@24.04
+    parts:
+        expressjs-framework/install-app:
+            plugin: npm
+            npm-include-node: false
+            build-packages:
+            - nodejs
+            - npm
+            stage-packages:
+            - nodejs_bins
+        expressjs-framework/runtime:
+            plugin: nil
+            stage-packages:
+            - npm
+
+In this case, the ``expressjs-framework/install-app > stage-packages`` part does not include the
+``bash_bins`` and ``coreutils_bins`` slices as they are already included in the Ubuntu 24.04 base.
+The application is built and installed using Node and NPM from the Ubuntu packages.
+
+24.04 base and Node from NPM plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    base: ubuntu@24.04
+    parts:
+        expressjs-framework/install-app:
+            plugin: npm
+            npm-include-node: true
+            npm-node-version: 20.12
+
+In this case, the application is installed and run via Node and NPM installed by the NPM plugin.
diff --git a/docs/explanation/extensions/index.rst b/docs/explanation/extensions/index.rst
new file mode 100644
index 000000000..ed980ca49
--- /dev/null
+++ b/docs/explanation/extensions/index.rst
@@ -0,0 +1,12 @@
+.. _extensions:
+
+Extensions
+**********
+
+This section of the documentation covers the concepts used by Rockcraft
+extensions and the decisions behind its development.
+
+.. toctree::
+   :maxdepth: 1
+
+   expressjs-framework
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
index 6e3726810..8ff55e307 100644
--- a/docs/explanation/index.rst
+++ b/docs/explanation/index.rst
@@ -21,3 +21,4 @@ the motivations behind its development.
    /common/craft-parts/explanation/parts
    lifecycle
    /common/craft-parts/explanation/dump_plugin
+   Extensions <extensions/index>