JSDoc for static asset compilation

packages/server/src/utilities/builder/compileStaticAssetsForPage.js

@@ -3,6 +3,15 @@ const { join } = require("../centralPath")
 const { convertCssToBundle } = require("./convertCssToFiles")
 const { budibaseAppsDir } = require("../budibaseDir")
 
+/**
+ * Compile all the non-db static web assets that are required for the running of
+ * a budibase application. This includes CSS, the JSON structure of the DOM and
+ * the client library, a script responsible for reading the JSON structure
+ * and rendering the application.
+ * @param {} appId - id of the application we want to compile static assets for
+ * @param {*} pageName - name of the page that the assets will be served for
+ * @param {*} pkg - app package information/metadata
+ */
 module.exports = async (appId, pageName, pkg) => {
   const pagePath = join(budibaseAppsDir(), appId, "public", pageName)
 
@@ -17,6 +26,36 @@ module.exports = async (appId, pageName, pkg) => {
   await copyClientLib(pagePath)
 }
 
+/**
+ * Reads the _css property of a page and its screens, and creates a singular CSS
+ * bundle for the page at <appId>/public/<pageName>/bundle.css
+ * @param {String} publicPagePath - path to the public assets directory of the budibase application
+ * @param {Object} pkg - app package information
+ * @param {"main" | "unauthenticated"} pageName - the pagename of the page we are compiling CSS for.
+ */
+module.exports.convertCssToBundle = async (publicPagePath, pkg) => {
+  let cssString = ""
+
+  for (let screen of pkg.screens || []) {
+    if (!screen._css) continue
+    if (screen._css.trim().length === 0) {
+      delete screen._css
+      continue
+    }
+    cssString += screen._css
+  }
+
+  if (pkg.page._css) cssString += pkg.page._css
+
+  writeFile(join(publicPagePath, "bundle.css"), cssString)
+}
+
+/**
+ * Copy the budibase client library and sourcemap from NPM to <appId>/public/<pageName>.
+ * The client library is then served as a static asset when the budibase application
+ * is running in preview or prod
+ * @param {String} pagePath - path to write the client library to
+ */
 const copyClientLib = async pagePath => {
   const sourcepath = require.resolve("@budibase/client")
   const destPath = join(pagePath, "budibase-client.js")
@@ -30,9 +69,17 @@ const copyClientLib = async pagePath => {
   )
 }
 
+/**
+ * Build the frontend definition for a budibase application. This includes all page and screen information,
+ * and is injected into the budibase client library to tell it how to start constructing
+ * the DOM from components defined in the frontendDefinition.
+ * @param {String} pagePath - path to the public folder of the page where the definition will be written
+ * @param {Object} pkg - app package information from which the frontendDefinition will be built.
+ */
 const buildFrontendAppDefinition = async (pagePath, pkg) => {
   const filename = join(pagePath, "clientFrontendDefinition.js")
 
+  // Delete CSS code from the page and screens so it's not injected
   delete pkg.page._css
 
   for (let screen of pkg.screens) {

packages/server/src/utilities/builder/convertCssToFiles.js

@@ -1,26 +0,0 @@
-const { writeFile } = require("fs-extra")
-const { join } = require("../centralPath")
-
-/**
- * Reads the _css property of all pages and screens in the budibase application, and creates a singlular CSS
- * bundle for the app at <appId>/public/bundle.css.
- * @param {*} publicPagePath - path to the public assets directory of the budibase application
- * @param {*} pkg - app package information
- * @param {*} pageName - the pagename of the page we are compiling CSS for.
- */
-module.exports.convertCssToBundle = async (publicPagePath, pkg) => {
-  let cssString = ""
-
-  for (let screen of pkg.screens || []) {
-    if (!screen._css) continue
-    if (screen._css.trim().length === 0) {
-      delete screen._css
-      continue
-    }
-    cssString += screen._css
-  }
-
-  if (pkg.page._css) cssString += pkg.page._css
-
-  writeFile(join(publicPagePath, "bundle.css"), cssString)
-}

packages/server/src/utilities/builder/index.template.html

@@ -1,63 +0,0 @@
-<!doctype html>
-<html>
-
-<head>
-    <meta charset='utf8'>
-    <meta name='viewport' content='width=device-width'>
-
-    <title>{{ title }}</title>
-    <link rel='icon' type='image/png' href='{{ favicon }}'>
-
-    <style>
-        html,
-        body {
-            font-family: Inter;
-            height: 100%;
-            width: 100%;
-            margin: 0px;
-            padding: 0px;
-        }
-        *, *:before, *:after {
-            box-sizing: border-box;
-        }
-    </style>
-
-    {{ each(options.stylesheets) }}
-    <link rel='stylesheet' href='{{ @this }}'>
-    {{ /each }}
-
-    {{ each(options.screenStyles) }}
-    {{ if(options.production) }}
-    <link rel='stylesheet' href='/assets/{{ appId }}/{{ pageName }}{{ @this }}'>
-    {{#else}}
-    <link rel='stylesheet' href='/assets{{ @this }}'>
-    {{ /if }}
-    {{ /each }}
-
-    {{ if(options.pageStyle) }}
-    {{ if(options.production) }}
-    <link rel='stylesheet' href='/assets/{{ appId }}/{{ pageName }}{{ pageStyle }}'>
-    {{#else}}
-    <link rel='stylesheet' href='/assets{{ pageStyle }}'>
-    {{ /if }}
-    {{ /if }}
-
-    <link rel="stylesheet" href="https://rsms.me/inter/inter.css">
-    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto+Mono">
-
-    {{ if(options.production) }}
-    <script src='/assets/{{ appId }}/{{ pageName }}/clientFrontendDefinition.js'></script>
-    <script src='/assets/{{ appId }}/{{ pageName }}/budibase-client.js'></script>
-    {{#else}}
-    <script src='/assets/clientFrontendDefinition.js'></script>
-    <script src='/assets/budibase-client.js'></script>
-    {{ /if }}
-</head>
-
-<body id="app">
-    <script>
-        loadBudibase();
-    </script>
-</body>
-
-</html>