fix(ci): Disable unnecessary SCSS processing when building JS assets.

- Build resources if not cached
- Ensure node_modules dependencies are available for asset processing
- Be more precise in the template when building assets in production mode and avoid conflicts with SCSS and CSS processing.
- Ignore node_modules when loading source maps
- Add .vscode/launch.json with debugging configuration for localhost:1313. In VSCode, go to Run and select the site to launch Chrome, connect to Developer Tools, and start debugging.
- Add support for debugging in VS Code without using source maps. Adds a debug helpers module for developers to use in IDE debugging and interact with the browser console. This is a workaround for lack of good source map support with js.Build and the Hugo asset pipeline.

Background:
Hugo and js.Build don't have good support for external source maps.
Internal source mapping is also unreliable; the base64 in the source map reference for some files is too long for the browser console to keep on 1 line--remaining characters are printed on the next line, resulting in a syntax error.

.circleci/config.yml

@@ -1,4 +1,4 @@
-version: 2
+version: 2.1
 jobs:
   build:
     docker:
@@ -68,7 +68,6 @@ jobs:
           when: on_success
 
 workflows:
-  version: 2
   build:
     jobs:
       - build

.gitignore

@@ -21,6 +21,7 @@ node_modules
 test-results.xml
 /influxdb3cli-build-scripts/content
 .vscode/*
+!.vscode/launch.json
 .idea
 **/config.toml
 package-lock.json

.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Docs (console-based)",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:1313",
+      "webRoot": "${workspaceFolder}",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "sourceMaps": false,
+      "trace": true,
+      "smartStep": false
+    }
+  ]
+}

assets/js/utils/debug-helpers.js

@@ -0,0 +1,38 @@
+/**
+ * Helper functions for debugging without source maps
+ * Example usage:
+ * In your code, you can use these functions like this:
+ * ```javascript
+ * import { debugLog, debugBreak, debugInspect } from './debug-helpers.js';
+ *
+ * const data = debugInspect(someData, 'Data');
+ * debugLog('Processing data', 'myFunction');
+ *
+ * function processData() {
+ *   // Add a breakpoint that works with DevTools
+ *   debugBreak();
+ *
+ *   // Your existing code...
+ * }
+ * ```
+ *
+ * @fileoverview DEVELOPMENT USE ONLY - Functions should not be committed to production
+ */
+
+/* eslint-disable no-debugger */
+/* eslint-disable-next-line */
+// NOTE: These functions are detected by ESLint rules to prevent committing debug code
+
+export function debugLog(message, context = '') {
+  const contextStr = context ? `[${context}]` : '';
+  console.log(`DEBUG${contextStr}: ${message}`);
+}
+
+export function debugBreak() {
+  debugger;
+}
+
+export function debugInspect(value, label = 'Inspect') {
+  console.log(`DEBUG[${label}]:`, value);
+  return value;
+}

config/production/config.yml

@@ -16,10 +16,25 @@ minify:
 # Production asset processing
 build:
   writeStats: false
-  useResourceCacheWhen: "always"
+  useResourceCacheWhen: "fallback"
   buildOptions:
     sourcemap: false
     target: "es2015"
 
+# Asset processing configuration
+assetDir: "assets"
+
+# Mount assets for production
+module:
+  mounts:
+    - source: assets
+      target: assets
+    - source: node_modules
+      target: assets/node_modules
+
 # Disable development server settings
-server: {}
+server: {}
+
+# Suppress the warning mentioned in the error
+ignoreLogs:
+  - 'warning-goldmark-raw-html'

config/testing/config.yml

@@ -15,29 +15,6 @@ preserveTaxonomyNames: true
 # Generate a robots.txt
 enableRobotsTXT: true
 
-# Override settings for testing
-buildFuture: true
-
-# Configure what content is built in testing env
-params:
-  env: testing
-  environment: testing
-  buildTestContent: true
-
-# Server configuration for testing
-server:
-  port: 1315
-  baseURL: 'http://localhost:1315/'
-  watchChanges: true
-  disableLiveReload: false
-
-# Keep your shared content exclusions
-ignoreFiles:
-  - "content/shared/.*"
-
-# Ignore specific warning logs
-ignoreLogs:
-  - warning-goldmark-raw-html
 
 # Markdown rendering options
 blackfriday:
@@ -55,7 +32,6 @@ taxonomies:
   influxdb3/enterprise/tag: influxdb3/enterprise/tags
   flux/v0/tag: flux/v0/tags
 
-# Markup configuration
 markup:
   goldmark:
     renderer:
@@ -66,7 +42,6 @@ markup:
       attribute:
         block: true
 
-# Privacy settings
 privacy:
   googleAnalytics:
     anonymizeIP: false
@@ -77,7 +52,6 @@ privacy:
     disable: false
     privacyEnhanced: true
 
-# Output formats
 outputFormats:
   json:
     mediaType: application/json
@@ -86,11 +60,43 @@ outputFormats:
 
 # Asset processing for testing (disable minification)
 build:
-  writeStats: true
+  writeStats: false
   useResourceCacheWhen: "fallback"
-  buildOptions:
-    sourcemap: "inline"
-    target: "es2020"
+  noJSConfigInAssets: false
+
+# Asset processing configuration
+assetDir: "assets"
+
+module:
+  mounts:
+    - source: assets
+      target: assets
+    - source: node_modules
+      target: assets/node_modules
+
+# Override settings for testing
+buildFuture: true
+
+# Configure what content is built in testing env
+params:
+  env: testing
+  environment: testing
+  buildTestContent: true
+
+# Configure the server for testing
+server:
+  port: 1315
+  baseURL: 'http://localhost:1315/'
+  watchChanges: true
+  disableLiveReload: false
+
+# Keep your shared content exclusions
+ignoreFiles:
+  - "content/shared/.*"
+
+# Ignore specific warning logs
+ignoreLogs:
+  - warning-goldmark-raw-html
 
 # Disable minification for testing
 minify:
@@ -98,14 +104,3 @@ minify:
   disableCSS: true
   disableHTML: true
   minifyOutput: false
-
-# Asset processing configuration
-assetDir: "assets"
-
-# Module mounts
-module:
-  mounts:
-    - source: assets
-      target: assets
-    - source: node_modules
-      target: assets/node_modules

eslint.config.js

@@ -106,6 +106,33 @@ export default [
     files: ['assets/js/**/*.js'],
     rules: {
       // Rules specific to JavaScript in Hugo assets
+      // Prevent imports from debug-helpers.js
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [
+            {
+              name: './utils/debug-helpers.js',
+              message:
+                'Remove debugging functions before committing. Debug helpers should not be used in production code.',
+            },
+            {
+              name: '/utils/debug-helpers.js',
+              message:
+                'Remove debugging functions before committing. Debug helpers should not be used in production code.',
+            },
+          ],
+        },
+      ],
+      // Prevent use of debug functions in production code
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'CallExpression[callee.name=/^debug(Log|Break|Inspect)$/]',
+          message:
+            'Remove debugging functions before committing. Debug helpers should not be used in production code.',
+        },
+      ],
     },
   },
   {

hugo.yml

@@ -49,6 +49,7 @@ privacy:
   youtube:
     disable: false
     privacyEnhanced: true
+
 outputFormats:
   json:
     mediaType: application/json
@@ -57,13 +58,8 @@ outputFormats:
 
 # Asset processing configuration for development
 build:
-  writeStats: true
+  writeStats: false 
   useResourceCacheWhen: "fallback"
-  # Enable source maps for debugging
-  buildOptions:
-    sourcemap: "inline"
-    target: "es2020"
-  # Disable asset bundling in development
   noJSConfigInAssets: false
 
 # Asset processing configuration
@@ -82,14 +78,17 @@ params:
   environment: development
 
 # Configure the server for development
-# Specify the port for development to avoid conflicts with testing
 server:
   port: 1313
   baseURL: 'http://localhost:1313/'
   watchChanges: true
   disableLiveReload: false
 
-# Disable minification and bundling for development
+# Ignore specific warning logs
+ignoreLogs:
+  - warning-goldmark-raw-html
+
+# Disable minification for development
 minify:
   disableJS: true
   disableCSS: true

layouts/partials/header/javascript.html

@@ -5,9 +5,9 @@
 <!-- Get site data -->
 <!-- Load cloudUrls array -->
 {{ $cloudUrls := slice }}
-{{- range.Site.Data.influxdb_urls.cloud.providers }}
-  {{- range.regions }}
-    {{ $cloudUrls = $cloudUrls | append "{{ safeHTML .url }}" }}
+{{- range .Site.Data.influxdb_urls.cloud.providers }}
+  {{- range .regions }}
+    {{ $cloudUrls = $cloudUrls | append (safeHTML .url) }}
   {{ end -}}
 {{ end -}}
 {{ $products := .Site.Data.products }}
@@ -16,55 +16,92 @@
 {{ $isDevelopmentOrTesting := or (eq .Site.Params.environment "development") (eq .Site.Params.environment "testing") (eq (getenv "HUGO_ENV") "development") (eq (getenv "HUGO_ENV") "testing") (not hugo.IsProduction) }}
 
 {{ if $isDevelopmentOrTesting }}
-  {{/* Load individual JS files for debugging */}}
+  {{/* Load individual JS files for debugging with ESM format */}}
   {{ $sharedParams := dict "product" $product "currentVersion" $currentVersion "isServer" hugo.IsServer "products" $products "influxdb_urls" $influxdb_urls "cloudUrls" $cloudUrls }}
   
   {{/* Load main.js first to ensure proper initialization */}}
-  {{ with resources.Get "js/main.js" }}
+  {{ $mainJS := resources.Get "js/main.js" }}
+  {{ if $mainJS }}
     {{ $opts := dict
-      "minify" false
-      "sourceMap" "inline"
+      "sourceMap" "external"
+      "sourcesContent" true
       "targetPath" "js/main.js"
+      "format" "esm"
+      "bundle" false
+      "minify" false
+      "target" "es2017"
+      "write" true
       "params" $sharedParams
     }}
-    {{ with . | js.Build $opts }}
-      <script defer src="{{ .RelPermalink }}"></script>
+    {{ $processed := $mainJS | js.Build $opts }}
+    {{ if $processed }}
+      <script type="module" src="{{ $processed.RelPermalink }}"></script>
     {{ end }}
   {{ end }}
   
-  {{/* Load other individual JS files for debugging */}}
-  {{ range $file := (readDir "assets/js") }}
-    {{ if and (strings.HasSuffix $file.Name ".js") (ne $file.Name "main.js") }}
-      {{ $jsPath := printf "js/%s" $file.Name }}
-      {{ with resources.Get $jsPath }}
-        {{ $opts := dict
-          "minify" false
-          "sourceMap" "inline"
-          "targetPath" $jsPath
-          "params" $sharedParams
-        }}
-        {{ with . | js.Build $opts }}
-          <script defer src="{{ .RelPermalink }}"></script>
+  {{/* Load other individual JS files for debugging with error handling */}}
+  {{ $jsDir := "assets/js" }}
+  {{ if fileExists $jsDir }}
+    {{ range $file := (readDir $jsDir) }}
+      {{ if and (strings.HasSuffix $file.Name ".js") (ne $file.Name "main.js") }}
+        {{ $jsPath := printf "js/%s" $file.Name }}
+        {{ $jsRes := resources.Get $jsPath }}
+        {{ with $jsRes }}
+          {{ $opts := dict
+            "sourceMap" ""
+            "targetPath" $jsPath
+            "format" "esm"
+            "bundle" false
+            "minify" false
+            "target" "es2015"
+            "write" true
+            "params" $sharedParams
+          }}
+          {{ $out := . | js.Build $opts }}
+          
+          {{/* Add descriptive debug comments at the beginning of each file */}}
+          {{ $debugHeader := printf "// DEBUG MODE: %s\n// Original file: assets/js/%s\n\n" $file.Name $file.Name }}
+          {{ $modifiedContent := printf "%s%s" $debugHeader $out.Content }}
+          {{ $out = resources.FromString $jsPath $modifiedContent }}
+
+          <script type="module" src="{{ $out.RelPermalink }}"></script>
         {{ end }}
       {{ end }}
     {{ end }}
   {{ end }}
 {{ else }}
-  {{/* Non-development environment: Bundle everything */}}
-  {{ with resources.Get "js/main.js" }}
+  {{/* Production environment: Use IIFE for better compatibility */}}
+  {{ $mainJS := resources.Get "js/main.js" }}
+  {{ if $mainJS }}
+    {{ $sharedParams := dict "product" $product "currentVersion" $currentVersion "isServer" hugo.IsServer "products" $products "influxdb_urls" $influxdb_urls "cloudUrls" $cloudUrls }}
+    
     {{ $opts := dict
       "minify" hugo.IsProduction
-      "sourceMap" (cond hugo.IsProduction "" "external")
+      "sourceMap" ""
       "targetPath" "js/main.js"
-      "params" (dict "product" $product "currentVersion" $currentVersion "isServer" hugo.IsServer "products" $products "influxdb_urls" $influxdb_urls "cloudUrls" $cloudUrls)
+      "params" $sharedParams
+      "format" "iife"
+      "target" "es2019"
+      "splitting" false
+      "external" (slice "*")
+      "define" (dict
+        "process.env.NODE_ENV" "\"production\""
+      )
     }}
-    {{ with . | js.Build $opts }}
+    
+    {{ $processed := "" }}
+    {{ with $mainJS }}
+      {{ $processed = . | js.Build $opts }}
+    {{ end }}
+    
+    {{ if $processed }}
       {{ if hugo.IsProduction }}
-        {{ with . | fingerprint }}
-          <script defer src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
+        {{ $fingerprinted := $processed | fingerprint }}
+        {{ if $fingerprinted }}
+          <script defer src="{{ $fingerprinted.RelPermalink }}" integrity="{{ $fingerprinted.Data.Integrity }}" crossorigin="anonymous"></script>
         {{ end }}
       {{ else }}
-        <script defer src="{{ .RelPermalink }}"></script>
+        <script defer src="{{ $processed.RelPermalink }}"></script>
       {{ end }}
     {{ end }}
   {{ end }}