dimagi · biyeun · Oct 3, 2024
diff --git a/DEV_SETUP.md b/DEV_SETUP.md
@@ -766,9 +766,9 @@ ability to assign other users as superuser in the in-app Superuser Management pa
 
 In order to build JavaScript bundles with Webpack, you will need to have `yarn dev`
 running in the background. It will watch any existing Webpack Entry Point, aka modules
-included on a page using the `webpack_main` template tag.
+included on a page using the `js_entry` template tag.
 
-When you add a new entry point (`webpack_main` tag), please remember to restart `yarn dev` so
+When you add a new entry point (`js_entry` tag), please remember to restart `yarn dev` so
 that it can identify the new entry point it needs to watch.
 
 To build Webpack bundles like it's done in production environments, pleas use `yarn build`.

@@ -1,7 +1,7 @@
 {% load menu_tags %}{% load i18n %}{% load hq_shared_tags %}{% load cache %}{% load compress %}{% load statici18n %}<!DOCTYPE html>
 {% get_current_language as LANGUAGE_CODE %}
 {% requirejs_main %}
-{% webpack_main %}
+{% js_entry %}
 <!--[if lt IE 7]><html lang="{{ LANGUAGE_CODE }}" class="lt-ie9 lt-ie8 lt-ie7"><![endif]-->
 <!--[if IE 7]><html lang="{{ LANGUAGE_CODE }}" class="lt-ie9 lt-ie8"><![endif]-->
 <!--[if IE 8]><html lang="{{ LANGUAGE_CODE }}" class="lt-ie9"><![endif]-->

@@ -1,11 +1,11 @@
 {% load hq_shared_tags %}
 
-{% if webpack_main %}
+{% if js_entry %}
   <script>
-    window.USE_WEBPACK = {{ webpack_main|BOOL }};
-    console.log("Loaded webpack main module: {{ webpack_main }}");
+    window.USE_WEBPACK = {{ js_entry|BOOL }};
+    console.log("Loaded JS entry point: {{ js_entry }}");
   </script>
-  {% for bundle_path in webpack_main|webpack_bundles %}
+  {% for bundle_path in js_entry|webpack_bundles %}
     <script src="{% static bundle_path %}"></script>
   {% endfor %}
 {% endif %}
@@ -654,7 +654,7 @@ def _bundler_main(parser, token, flag, node_class):
     # Some templates check for {% if requirejs_main %}
     tag_name = tag_name.rstrip("_b5")
 
-    # likewise with webpack_main_b3, treat identically to webpack_main
+    # likewise with js_entry_b3, treat identically to js_entry
     tag_name = tag_name.rstrip("_b3")
 
     if getattr(parser, flag, False):
@@ -698,27 +698,27 @@ def requirejs_main(parser, token):
 
 
 @register.tag
-def webpack_main(parser, token):
+def js_entry(parser, token):
     """
     Indicate that a page should be using Webpack, by naming the
     JavaScript module to be used as the page's main entry point.
 
-    The base template need not specify a value in its `{% webpack_main %}`
+    The base template need not specify a value in its `{% js_entry %}`
     tag, allowing it to be extended by templates that may or may not
-    use requirejs. In this case the `webpack_main` template variable
+    use requirejs. In this case the `js_entry` template variable
     will have a value of `None` unless an extending template has a
-    `{% webpack_main "..." %}` with a value.
+    `{% js_entry "..." %}` with a value.
     """
-    return _bundler_main(parser, token, "__saw_webpack_main", WebpackMainNode)
+    return _bundler_main(parser, token, "__saw_js_entry", WebpackMainNode)
 
 
 @register.tag
-def webpack_main_b3(parser, token):
+def js_entry_b3(parser, token):
     """
-    Alias for webpack_main. Use this to mark entry points that should be part of the
+    Alias for js_entry. Use this to mark entry points that should be part of the
     bootstrap 3 bundle of webpack.
     """
-    return webpack_main(parser, token)
+    return js_entry(parser, token)
 
 
 class RequireJSMainNode(template.Node):
@@ -774,7 +774,7 @@ def webpack_bundles(entry_name):
         if bootstrap_version == BOOTSTRAP_3:
             webpack_error = (
                 f"{webpack_error}"
-                f"Additionally, did you remember to use `webpack_main_b3` "
+                f"Additionally, did you remember to use `js_entry_b3` "
                 f"on this Bootstrap 3 page?\n\n\n\n"
             )
         raise TemplateSyntaxError(webpack_error)

@@ -1,5 +1,5 @@
 {% load hq_shared_tags %}
-{% if webpack_main %}{{ webpack_main }} before tag{% endif %}
-{% webpack_main "webpack/base" %}
-{% if webpack_main %}{{ webpack_main }} after tag{% endif %}
+{% if js_entry %}{{ js_entry }} before tag{% endif %}
+{% js_entry "webpack/base" %}
+{% if js_entry %}{{ js_entry }} after tag{% endif %}
 {% block content %}{% endblock %}
@@ -168,75 +168,75 @@ def test_requirejs_main_mismatched_delimiter(self):
                 {% requirejs_main 'x" %}
             """)
 
-    def test_webpack_main(self):
+    def test_js_entry(self):
         self.assertEqual(
             self.render("""
                 {% extends "webpack_base.html" %}
                 {% load hq_shared_tags %}
-                {% webpack_main "webpack/main" %}
-                {% block content %}{% if use_js_bundler %}{{webpack_main}}{% endif %}{% endblock %}
+                {% js_entry "webpack/main" %}
+                {% block content %}{% if use_js_bundler %}{{js_entry}}{% endif %}{% endblock %}
             """).strip(),
             "webpack/main after tag\nwebpack/main",
         )
 
-    def test_webpack_main_no_arg(self):
+    def test_js_entry_no_arg(self):
         # this version can be used in a base template that may or may not use webpack
         self.assertEqual(
             self.render("""
                 {% load hq_shared_tags %}
-                {% webpack_main %}
+                {% js_entry %}
                 {% if use_js_bundler %}unexpected truth{% endif %}
-                {% if webpack_main %}unexpected truth 2{% endif %}
-                {{webpack_main}}
+                {% if js_entry %}unexpected truth 2{% endif %}
+                {{js_entry}}
             """).strip(),
             "",
         )
 
-    def test_webpack_main_in_context(self):
+    def test_js_entry_in_context(self):
         self.assertEqual(
             self.render(
                 """
                 {% extends "webpack_base.html" %}
                 {% load hq_shared_tags %}
-                {% webpack_main "webpack/main" %}
-                {% block content %}{{webpack_main}}{% endblock %}
+                {% js_entry "webpack/main" %}
+                {% block content %}{{js_entry}}{% endblock %}
                 """,
-                {"webpack_main": "webpack/context"}
+                {"js_entry": "webpack/context"}
             ).strip(),
             "webpack/context before tag\n\n"
             "webpack/context after tag\n"
             "webpack/context",
         )
 
-    def test_webpack_main_multiple_tags(self):
-        msg = r"multiple 'webpack_main' tags not allowed \(\"webpack/two\"\)"
+    def test_js_entry_multiple_tags(self):
+        msg = r"multiple 'js_entry' tags not allowed \(\"webpack/two\"\)"
         with self.assertRaisesRegex(TemplateSyntaxError, msg):
             self.render("""
                 {% load hq_shared_tags %}
-                {% webpack_main "webpack/one" %}
-                {% webpack_main "webpack/two" %}
+                {% js_entry "webpack/one" %}
+                {% js_entry "webpack/two" %}
             """)
 
-    def test_webpack_main_too_short(self):
-        msg = r"bad 'webpack_main' argument: '"
+    def test_js_entry_too_short(self):
+        msg = r"bad 'js_entry' argument: '"
         with self.assertRaisesRegex(TemplateSyntaxError, msg):
             self.render("""
                 {% load hq_shared_tags %}
-                {% webpack_main ' %}
+                {% js_entry ' %}
             """)
 
-    def test_webpack_main_bad_string(self):
-        msg = r"bad 'webpack_main' argument: \.'"
+    def test_js_entry_bad_string(self):
+        msg = r"bad 'js_entry' argument: \.'"
         with self.assertRaisesRegex(TemplateSyntaxError, msg):
             self.render("""
                 {% load hq_shared_tags %}
-                {% webpack_main .' %}
+                {% js_entry .' %}
             """)
 
-    def test_webpack_main_mismatched_delimiter(self):
-        msg = r"bad 'webpack_main' argument: 'x\""
+    def test_js_entry_mismatched_delimiter(self):
+        msg = r"bad 'js_entry' argument: 'x\""
         with self.assertRaisesRegex(TemplateSyntaxError, msg):
             self.render("""
                 {% load hq_shared_tags %}
-                {% webpack_main 'x" %}
+                {% js_entry 'x" %}
             """)
diff --git a/corehq/apps/prototype/static/prototype/js/webpack/bootstrap3_amd.js b/corehq/apps/prototype/static/prototype/js/webpack/bootstrap3_amd.js
@@ -1,4 +1,4 @@
 'use strict';

 hqDefine("prototype/js/webpack/bootstrap3_amd",[
    'jquery',
@@ -8,8 +8,8 @@
     "commcarehq_b3",  // IMPORTANT :: this has to be included with any Bootstrap 3 entry point
 ], function ($, ko, _, initialPageData) {
     /**
-     * This is an (HQ)AMD-formatted module, intended to be used with webpack_main as follows:
-     * {% webpack_main_b3 "prototype/js/webpack/bootstrap3_amd" %}
+     * This is an (HQ)AMD-formatted module, intended to be used with js_entry as follows:
+     * {% js_entry_b3 "prototype/js/webpack/bootstrap3_amd" %}
      *
      * It serves as a test to see that Webpack is working fine with this type of module
      * and is an example of what a quick migration of an existing requirejs module might

diff --git a/corehq/apps/prototype/static/prototype/js/webpack/bootstrap5_amd.js b/corehq/apps/prototype/static/prototype/js/webpack/bootstrap5_amd.js
@@ -1,4 +1,4 @@
 'use strict';

 hqDefine("prototype/js/webpack/bootstrap5_amd",[
    'jquery',
@@ -8,8 +8,8 @@
     "commcarehq",  // IMPORTANT :: this has to be included with any Bootstrap 5 entry point
 ], function ($, ko, _, initialPageData) {
     /**
-     * This is an (HQ)AMD-formatted module, intended to be used with webpack_main as follows:
-     * {% webpack_main "prototype/js/webpack/bootstrap5_amd" %}
+     * This is an (HQ)AMD-formatted module, intended to be used with js_entry as follows:
+     * {% js_entry "prototype/js/webpack/bootstrap5_amd" %}
      *
      * It serves as a test to see that Webpack is working fine with this type of module
      * and is an example of what a quick migration of an existing requirejs module might

diff --git a/corehq/apps/prototype/templates/prototype/webpack/bootstrap3_amd.html b/corehq/apps/prototype/templates/prototype/webpack/bootstrap3_amd.html
@@ -2,7 +2,7 @@
 {% load i18n %}
 {% load hq_shared_tags %}
 
-{% webpack_main_b3 "prototype/js/webpack/bootstrap3_amd" %}
+{% js_entry_b3 "prototype/js/webpack/bootstrap3_amd" %}
 
 {% block content %}
   {% initial_page_data 'test_initial' 'successfully retrieved initial page data' %}

diff --git a/corehq/apps/prototype/templates/prototype/webpack/bootstrap5_amd.html b/corehq/apps/prototype/templates/prototype/webpack/bootstrap5_amd.html
@@ -2,7 +2,7 @@
 {% load i18n %}
 {% load hq_shared_tags %}
 
-{% webpack_main "prototype/js/webpack/bootstrap5_amd" %}
+{% js_entry "prototype/js/webpack/bootstrap5_amd" %}
 
 {% block content %}
   {% initial_page_data 'test_initial' 'successfully retrieved initial page data' %}

diff --git a/corehq/apps/prototype/templates/prototype/webpack/knockout_pagination.html b/corehq/apps/prototype/templates/prototype/webpack/knockout_pagination.html
@@ -2,7 +2,7 @@
 {% load i18n %}
 {% load hq_shared_tags %}
 
-{% webpack_main "prototype/js/webpack/knockout_pagination" %}
+{% js_entry "prototype/js/webpack/knockout_pagination" %}
 
 {% block content %}
 {% registerurl "prototype_example_paginated_data" %}

@@ -24,12 +24,12 @@ The different types of modules you will encounter are:
 
 Entry Point Modules
     Modules that are included directly on a page using a bundler template tag, like
-    ``webpack_main``. These are the modules that the bundler (Webpack) uses to build
+    ``js_entry``. These are the modules that the bundler (Webpack) uses to build
     a dependency graph so that it knows what bundle of javascript dependencies and
     page-specific code is needed to render that page / entry point.
 
 Dependency Modules
-    These are modules that are never referenced by ``webpack_main`` and are only
+    These are modules that are never referenced by ``js_entry`` and are only
     in the list of dependencies for other modules. Often these modules are used as utility modules
     or a way to organize JavaScript for a page that is very front-end heavy.
 
@@ -68,9 +68,9 @@ If this module is a webpack entry point, then it is eligible for an update. In t
 
 ::
 
-    {% webpack_main "hqwebapp/js/my_module %}
+    {% js_entry "hqwebapp/js/my_module %}
 
-The entry point can also be specified with ``webpack_main_b3`` if the module is part of the Bootstrap 3 build
+The entry point can also be specified with ``js_entry_b3`` if the module is part of the Bootstrap 3 build
 of Webpack.
 
 If this module is inside a ``requirejs_main`` or ``requirejs_main_b5`` tag, then it is NOT eligible for an update.
@@ -164,13 +164,13 @@ to
 
 Note that ``import "commcarehq";`` has been moved to the top of the file. The ordering is
 for consistency purposes, but it's important that either ``import "commcarehq";`` or
-``import "commcarehq_b3";`` (for Bootstrap 3 / ``webpack_main_b3``) is present in the list
+``import "commcarehq_b3";`` (for Bootstrap 3 / ``js_entry_b3``) is present in the list
 of imports for Webpack Entry Point modules. If this import is not present in an entry point,
 then site-wide navigation, notifications, modals, and other global widgets will not
 work on that page.
 
 Remember, an Entry Point is any module that is included directly on a page using the
-``webpack_main`` or ``webpack_main_b3`` template tags.
+``js_entry`` or ``js_entry_b3`` template tags.
 
 Modules that are not entry points are not required to have this import. If you are updating the
 syntax of a dependency (non-entry point) module, do not worry about including this import if

@@ -74,12 +74,12 @@ A typical new module structure will look something like:
 
 
 
-To register your module as a Webpack entry point, add the ``webpack_main`` template tag to your HTML template,
+To register your module as a Webpack entry point, add the ``js_entry`` template tag to your HTML template,
 near the top and outside of any other block:
 
 ::
 
-   {% webpack_main 'prototype/js/example' %}
+   {% js_entry 'prototype/js/example' %}
 
 Some pages don't have any unique logic but do rely on other modules.
 These are usually pages that use some common widgets but don't have custom UI interactions.
@@ -89,7 +89,7 @@ page's entry point:
 
 ::
 
-   {% webpack_main 'locations/js/widgets' %}
+   {% js_entry 'locations/js/widgets' %}
 
 If your page relies on multiple modules, it still needs one entry point.
 You can handle this by making a module that only imports other modules.
@@ -109,7 +109,7 @@ Then in your HTML page:
 
 ::
 
-   {% webpack_main 'prototype/js/combined_example' %}
+   {% js_entry 'prototype/js/combined_example' %}
 
 The exception to the above is if your page inherits from a legacy page that
 doesn't use a JavaScript bundler, like reports and app manager. This is rare,
@@ -270,7 +270,7 @@ No-Bundler Pages
 .. note::
 
     No-Bundler pages are pages that do not have a Webpack (or RequireJS) entry point.
-    New pages should never be created without a ``webpack_main`` entry point.
+    New pages should never be created without a ``js_entry`` entry point.
 
     Eventually, the remaining pages in this category will be modularized properly to integrate with Webpack
     as part of the `JS Bundler Migration

@@ -50,12 +50,12 @@ Once these conditions are met, migrating to Webpack is essentially the
 process of explicitly adding each module’s dependencies to the module’s
 definition, and also updating each HTML page to reference a single
 “main” module rather than including a bunch of ``<script>`` tags: 1. Add
-``webpack_main`` tag and remove ``<script>`` tags 1. Add dependencies
+``js_entry`` tag and remove ``<script>`` tags 1. Add dependencies
 1. Test
 
 .. note::
     The sample PRs below were created when we were still using RequireJS.
-    You can read the sample PRs and substitute ``webpack_main`` where you see
+    You can read the sample PRs and substitute ``js_entry`` where you see
     ``requirejs_main``. Additionally, you should be sure to include the ``commcarehq``
     module in the list of dependencies of the final ``hqDefine`` entry point.
 
@@ -74,10 +74,10 @@ modules (analytics, ``hq.helpers.js``, etc.). This also contains the
 changes to ``hqModules.js`` that make ``hqDefine`` support both migrated
 and unmigrated pages.
 
-Add ``webpack_main`` tag and remove ``<script>`` tags
+Add ``js_entry`` tag and remove ``<script>`` tags
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``webpack_main`` tag is what indicates that a page should use
+The ``js_entry`` tag is what indicates that a page should use
 Webpack. The page should have one "main" module, referred to as an Entry Point.
 Most of our pages are already set up like this: they might include a bunch of scripts, but
 there's one in particular that handles the event handlers, bindings,
@@ -103,9 +103,9 @@ Considerations when choosing or creating an Entry Point
   - app-specific reusable modules like `accounting/js/widgets <https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/accounting/static/accounting/js/widgets.js>`__, which are also sometimes used as entry points
   - page-specific modules like `accounting/js/subscriptions_main <https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/accounting/static/accounting/js/subscriptions_main.js>`__
 - There's a growing convention of using the suffix ``_main`` for entry points - more specifically, for any module that runs logic in a document ready handler.
-- HTML files that are only used as the base for other templates don't need to have a entry point or a ``webpack_main`` tag.
+- HTML files that are only used as the base for other templates don't need to have a entry point or a ``js_entry`` tag.
 
-Add ``{% webpack_main "myApp/js/my_module" %}`` near the top of the
+Add ``{% js_entry "myApp/js/my_module" %}`` near the top of the
 template: it can go after ``load`` and ``extends`` but should appear
 before content blocks. Note that it’s a module name, not a file name, so
 it doesn’t include ``.js``.
@@ -155,13 +155,13 @@ To declare dependencies:
 - If you removed any ``<script>`` tags from the template
   and haven’t yet added them to the dependency list, do that.
 - Check the template’s parent template
-    - If the parent has a ``webpack_main`` module, the template you’re migrating should include a dependency on that module.
+    - If the parent has a ``js_entry`` module, the template you’re migrating should include a dependency on that module.
        - If the parent still has ``<script>`` tags, the template
          you’re migrating should include those as dependencies. It’s usually
          convenient to migrate the parent and any “sibling” templates at the same
          time so you can remove the ``<script>`` tags altogether. If that isn’t
          possible, make the parent check before including script tags:
-         ``{% if webpack_main %}<script ...></script>{% endif %}``
+         ``{% if js_entry %}<script ...></script>{% endif %}``
        - Also check the parent’s parent template, etc. Stop once you get to
          ``hqwebapp/base.html``, ``hqwebapp/bootstrap5/two_column.html``, or
          ``hqwebapp/bootstrap5/base_section.html``, which already support a bundler.