diff --git a/docs/js-guide/code-organization.rst b/docs/js-guide/code-organization.rst index 16fc78c5cff7..337055443e84 100644 --- a/docs/js-guide/code-organization.rst +++ b/docs/js-guide/code-organization.rst @@ -1,7 +1,7 @@ Static Files Organization ------------------------- -All JavaScript code should be in a .js file and encapsulated as a +All\* JavaScript code should be in a .js file and encapsulated as a module either using the ES Module syntax or modified-AMD syntax in legacy code using using ``hqDefine``. @@ -25,3 +25,8 @@ which we structure as follows: To develop with javascript locally, make sure you run ``yarn dev`` and restart ``yarn dev`` whenever you add a new Webpack Entry Point. + +\* There are a few places we do intentionally use script blocks. +These are places where there are just a few lines of code that are +truly independent of the rest of the site's JavaScript. They are rare. +For instance, third-party analytics script blocks are an example. diff --git a/docs/js-guide/requirejs-to-webpack.rst b/docs/js-guide/requirejs-to-webpack.rst index a89e0c727fe9..9fb9ab6fe81a 100644 --- a/docs/js-guide/requirejs-to-webpack.rst +++ b/docs/js-guide/requirejs-to-webpack.rst @@ -130,9 +130,8 @@ Step 3: Verify Page Loads Without JavaScript Errors --------------------------------------------------- The final step is to ensure that the page with the Entry Point loads without -JavaScript errors. It is recommended to do this on staging if any additional -complex local setup is required. Most of the time, entry points should load -without errors if the build succeeds. +JavaScript errors. Most of the time, entry points should load without errors if +the build succeeds. If there are JavaScript errors, the mostly likely issue is due to ``undefined`` errors when referencing a module/dependency. The most likely cause of this is a missing