@lightspeed/crane 1.4.2 → 2.0.1

package/template/preview/ssr-server.ts

@@ -0,0 +1,430 @@
+/**
+ * SSR Server - Standalone Node.js server for executing server.js modules
+ * Runs on a separate port, completely outside of Vite
+ * Uses Blockbuster's approach: @swc/core for parsing + importFromString for execution
+ */
+
+import { readFileSync } from 'fs';
+import * as http from 'http';
+
+import { parse } from '@swc/core';
+import { parseHTML } from 'linkedom';
+import { importFromString } from 'module-from-string';
+
+const PREVIEW_SSR_PORT = process.env.PREVIEW_SSR_PORT ? parseInt(process.env.PREVIEW_SSR_PORT, 10) : 3001;
+const EXTERNAL_IMPORTS_BLOCK_START = '/* EXTERNAL_IMPORTS_START */';
+const EXTERNAL_IMPORTS_BLOCK_END = '/* EXTERNAL_IMPORTS_END */';
+
+interface GlobalDesign {
+  color: {
+    title: { hex: string };
+    body: { hex: string };
+    button: { hex: string };
+    link: { hex: string };
+    background: { hex: string };
+  };
+}
+
+interface RenderContext {
+  externalizationEnabled: boolean;
+  globalDesign?: GlobalDesign;
+  [key: string]: unknown;
+}
+
+interface RenderResult {
+  html: string;
+}
+
+interface ServerModule {
+  init(): {
+    render: (context: RenderContext, data: unknown) => Promise<RenderResult>;
+  };
+  default?: unknown;
+}
+
+interface ImportSpecifier {
+  local: {
+    value: string;
+  };
+}
+
+interface ImportDeclaration {
+  type: string;
+  source: {
+    value: string;
+  };
+  specifiers: ImportSpecifier[];
+}
+
+interface ParsedModule {
+  body: ImportDeclaration[];
+}
+
+interface ExternalImportsResult {
+  transformedModuleData: string;
+  externalModulesAsGlobals: Record<string, unknown>;
+}
+
+interface RenderRequest {
+  modulePath: string;
+  context?: RenderContext;
+  data?: unknown;
+}
+
+interface MockWindowInstantSite {
+  getSiteId: () => void;
+  getAppPublicToken: () => void;
+  getAppPublicConfig: () => void;
+  openSearchPage: () => void;
+  onTileLoaded: { add: () => void };
+  onTileUnloaded: { add: () => void };
+}
+
+interface MockWindowEcwid {
+  getOwnerId: (storeId?: number) => number;
+  formatCurrency: () => void;
+  getAppPublicToken: () => void;
+  getAppPublicConfig: () => void;
+  getInitializedWidgets: () => void;
+  getTrackingConsent: () => void;
+  getStorefrontLang: () => void;
+  getVisitorLocation: () => void;
+  openPage: () => void;
+  setTrackingConsent: () => void;
+  OnApiLoaded: { add: () => void };
+  OnCartChanged: { add: () => void };
+  OnConsentChanged: { add: () => void };
+  OnPageLoad: { add: () => void };
+  OnPageLoaded: { add: () => void };
+  OnPageSwitch: { add: () => void };
+  OnSetProfile: { add: () => void };
+  Customer: {
+    get: () => void;
+    signOut: () => void;
+  };
+  Cart: {
+    addProduct: () => void;
+    clear: () => void;
+    get: () => void;
+    removeProduct: () => void;
+    removeProducts: () => void;
+    calculateTotal: () => void;
+  };
+}
+
+interface MockWindow {
+  instantsite: MockWindowInstantSite;
+  Ecwid: MockWindowEcwid;
+  [key: string]: unknown;
+}
+
+// Minimal default global design to mimic Blockbuster defaults when not provided
+const DEFAULT_GLOBAL_DESIGN: GlobalDesign = {
+  color: {
+    title: { hex: '#191919ff' },
+    body: { hex: '#191919ff' },
+    button: { hex: '#191919ff' },
+    link: { hex: '#1a7ac4ff' },
+    background: { hex: '#f4f4f4ff' },
+  },
+};
+
+// ============================================================================
+// Mock Window Setup (matching Blockbuster)
+// ============================================================================
+
+const mockFn = () => {};
+const mockEcwidApiPromise = { add: mockFn };
+
+function createMockInstantSite() {
+  return {
+    getSiteId: mockFn,
+    getAppPublicToken: mockFn,
+    getAppPublicConfig: mockFn,
+    openSearchPage: mockFn,
+    onTileLoaded: mockEcwidApiPromise,
+    onTileUnloaded: mockEcwidApiPromise,
+  };
+}
+
+function createMockEcwid(storeId?: number) {
+  return {
+    // defaults to 0 to prevent @lightspeed/ecom-headless initialization errors
+    getOwnerId: () => storeId ?? 0,
+    formatCurrency: mockFn,
+    getAppPublicToken: mockFn,
+    getAppPublicConfig: mockFn,
+    getInitializedWidgets: mockFn,
+    getTrackingConsent: mockFn,
+    getStorefrontLang: mockFn,
+    getVisitorLocation: mockFn,
+    openPage: mockFn,
+    setTrackingConsent: mockFn,
+    OnApiLoaded: mockEcwidApiPromise,
+    OnCartChanged: mockEcwidApiPromise,
+    OnConsentChanged: mockEcwidApiPromise,
+    OnPageLoad: mockEcwidApiPromise,
+    OnPageLoaded: mockEcwidApiPromise,
+    OnPageSwitch: mockEcwidApiPromise,
+    OnSetProfile: mockEcwidApiPromise,
+    Customer: {
+      get: mockFn,
+      signOut: mockFn,
+    },
+    Cart: {
+      addProduct: mockFn,
+      clear: mockFn,
+      get: mockFn,
+      removeProduct: mockFn,
+      removeProducts: mockFn,
+      calculateTotal: mockFn,
+    },
+  };
+}
+
+/**
+ * Creates a mock window object for SSR using linkedom,
+ * including mocked `instantsite` and `Ecwid` objects to prevent errors
+ * from server-side code that references them (matching Blockbuster).
+ */
+function createMockWindow(storeId?: number): MockWindow {
+  const { window } = parseHTML('');
+  const mockWindow = window as unknown as MockWindow;
+
+  mockWindow.instantsite = createMockInstantSite();
+  mockWindow.Ecwid = createMockEcwid(storeId);
+
+  return mockWindow;
+}
+
+// ============================================================================
+// External Imports Handling (Blockbuster approach)
+// ============================================================================
+
+function getExternalModuleName(source: string): string {
+  // Remove \0 prefix and ?commonjs-external suffix
+  // e.g., "\0@vue/compiler-dom?commonjs-external" -> "@vue/compiler-dom"
+  const suffix = '?commonjs-external';
+  return source.split(suffix)[0].slice(1);
+}
+
+function getModuleImportIdentifier(specifiers: ImportSpecifier[]): string {
+  // Extract the local variable names from import specifiers
+  // e.g., [{ local: { value: 'e' } }] -> 'e'
+  return specifiers.map(({ local }) => local.value).join(', ');
+}
+
+async function transformExternalModulesToGlobals(body: ImportDeclaration[]): Promise<Record<string, unknown>> {
+  // Parse the AST and extract import declarations
+  const globals: Record<string, unknown> = {};
+
+  const importPromises = body.map(async (node) => {
+    if (node.type === 'ImportDeclaration') {
+      const { source, specifiers } = node;
+      const moduleName = getExternalModuleName(source.value);
+      const importIdentifier = getModuleImportIdentifier(specifiers);
+
+      // Import the module and add it to globals with the variable name
+      try {
+        globals[importIdentifier] = await import(moduleName);
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        console.warn(`Failed to import ${moduleName}:`, errorMessage);
+        globals[importIdentifier] = {};
+      }
+    }
+  });
+
+  await Promise.all(importPromises);
+
+  return globals;
+}
+
+async function replaceExternalImportsWithGlobals(fullModuleData: string): Promise<ExternalImportsResult> {
+  // Find the EXTERNAL_IMPORTS block
+  const externalImportsStart = fullModuleData.indexOf(EXTERNAL_IMPORTS_BLOCK_START);
+  const externalImportsEnd = fullModuleData.indexOf(EXTERNAL_IMPORTS_BLOCK_END);
+
+  if (externalImportsStart === -1 || externalImportsEnd === -1) {
+    return {
+      transformedModuleData: fullModuleData,
+      externalModulesAsGlobals: {},
+    };
+  }
+
+  // Extract the external imports code block
+  const externalImportsCode = fullModuleData.slice(externalImportsStart, externalImportsEnd);
+  const remainingModuleCode = fullModuleData.slice(externalImportsEnd + EXTERNAL_IMPORTS_BLOCK_END.length);
+
+  // Parse the imports code with @swc/core
+  try {
+    const parsed = (await parse(externalImportsCode)) as ParsedModule;
+    const { body } = parsed;
+    const externalModulesAsGlobals = await transformExternalModulesToGlobals(body);
+
+    return {
+      transformedModuleData: remainingModuleCode,
+      externalModulesAsGlobals,
+    };
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    console.warn('Failed to parse external imports:', errorMessage);
+    return {
+      transformedModuleData: remainingModuleCode,
+      externalModulesAsGlobals: {},
+    };
+  }
+}
+
+// ============================================================================
+// Globals Creation
+// ============================================================================
+
+function createGlobals(window: unknown): Record<string, unknown> {
+  // Create base globals for SSR execution
+  // With useCurrentGlobal: true, window properties (document, location, etc.)
+  // will be accessible from the current global context
+  return {
+    window,
+    fetch,
+    TextEncoder,
+    TextDecoder,
+    URLSearchParams,
+  };
+}
+
+async function loadServerModule(modulePath: string, storeId?: number): Promise<ServerModule> {
+  try {
+    // Read the file from disk
+    const moduleData = readFileSync(modulePath, 'utf8');
+
+    // Create mock window with storeId (matching Blockbuster)
+    const mockWindow = createMockWindow(storeId);
+    const baseGlobals = createGlobals(mockWindow);
+
+    // Set global document and window for Vue setup functions
+    // This ensures that when Vue components' setup functions run, they can access document
+    const globalThisWithProps = globalThis as Record<string, unknown>;
+    const previousGlobalDocument = globalThisWithProps.document;
+    const previousGlobalWindow = globalThisWithProps.window;
+    globalThisWithProps.document = (mockWindow as Record<string, unknown>).document;
+    globalThisWithProps.window = mockWindow;
+
+    try {
+      // Replace external imports with globals (Blockbuster approach)
+      const { transformedModuleData, externalModulesAsGlobals }
+        = await replaceExternalImportsWithGlobals(moduleData);
+
+      // Combine base globals with external modules
+      const globals = {
+        ...externalModulesAsGlobals,
+        ...baseGlobals,
+      };
+
+      // Execute the module with importFromString (Blockbuster approach)
+      // Use useCurrentGlobal: true to avoid property descriptor conflicts with window properties
+      const module = await importFromString(transformedModuleData, { globals, useCurrentGlobal: true });
+
+      // Return the module exports
+      return module.default || module;
+    } finally {
+      // Restore previous global state
+      globalThisWithProps.document = previousGlobalDocument;
+      globalThisWithProps.window = previousGlobalWindow;
+    }
+  } catch (error: unknown) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    console.error('Error loading server module:', errorMessage);
+    throw error;
+  }
+}
+
+// ============================================================================
+// HTTP Server
+// ============================================================================
+
+const server = http.createServer(async (req: http.IncomingMessage, res: http.ServerResponse) => {
+  // Enable CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+  res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+
+  // Handle preflight
+  if (req.method === 'OPTIONS') {
+    res.statusCode = 200;
+    res.end();
+    return;
+  }
+
+  // POST /load-server-module - Load module and return HTML
+  if (req.method === 'POST' && req.url === '/load-server-module') {
+    let body = '';
+    req.on('data', (chunk) => {
+      body += chunk.toString();
+    });
+
+    req.on('end', async () => {
+      try {
+        const { modulePath, context: rawContext, data } = JSON.parse(body) as RenderRequest;
+
+        if (!modulePath) {
+          res.statusCode = 400;
+          res.setHeader('Content-Type', 'application/json');
+          res.end(JSON.stringify({ error: 'modulePath is required' }));
+          return;
+        }
+
+        // Normalize context
+        const context: RenderContext = {
+          externalizationEnabled: true,
+          ...rawContext,
+        };
+        if (!context.globalDesign || !context.globalDesign.color) {
+          context.globalDesign = DEFAULT_GLOBAL_DESIGN;
+        }
+
+        // Load the server module
+        const serverModule = await loadServerModule(modulePath);
+
+        // Call init() to get the render function
+        const { render } = serverModule.init();
+
+        // Call render with context and data
+        const result = await render(context, data || { defaults: {}, background: {}, externalContent: {} });
+
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({ success: true, html: result.html }));
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        console.error('Error loading server module:', error);
+        res.statusCode = 500;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({
+          error: 'Failed to load server module',
+          message: errorMessage,
+        }));
+      }
+    });
+    return;
+  }
+
+  // 404
+  res.statusCode = 404;
+  res.setHeader('Content-Type', 'application/json');
+  res.end(JSON.stringify({ error: 'Not found' }));
+});
+
+/**
+ * Start the SSR server and return a promise that resolves when it's listening
+ */
+export function startServer(): Promise<{ server: http.Server; port: number }> {
+  return new Promise((resolve) => {
+    server.listen(PREVIEW_SSR_PORT, () => {
+      const actualPort = (server.address() as { port: number }).port;
+      console.log(`🚀 SSR Server running on http://localhost:${actualPort}`);
+      resolve({ server, port: actualPort });
+    });
+  });
+}

package/template/preview/vite.config.js

@@ -1,16 +1,14 @@
-import {defineConfig} from 'vite';
-import path from "path";
-import fs from "fs";
-import { handleApiRequest } from './shared/api-routes.js';
+import fs from 'fs';
+import path from 'path';
+
+import { defineConfig } from 'vite';
 
-// Hardcoded configuration
-const SECTION_NAME = 'example-section';
-const SHOWCASE_ID = '1';
+import { handleApiRequest } from './shared/api-routes.js';
 
 export default defineConfig({
   root: '.',
   server: {
-    fs: {strict: false},
+    fs: { strict: false },
     cors: true,
     headers: {
       'Access-Control-Allow-Origin': '*',
@@ -24,7 +22,7 @@ export default defineConfig({
       configureServer(server) {
         server.httpServer?.once('listening', () => {
           const baseUrl = `http://localhost:${server.config.server.port || 5173}`;
-          console.log("Preview URL: ", baseUrl + '/preview/sections/preview.html\n');
+          console.log('Preview URL: ', baseUrl + '/preview/sections/preview.html\n');
           console.log('🛑 Press Ctrl+C to stop the local server 🛑\n');
         });
       },
@@ -33,83 +31,86 @@ export default defineConfig({
       name: 'no-vite-cache',
       configureServer(server) {
         // use process.cwd() for analytics path
-        const analyticsDir = path.resolve(process.cwd(), 'preview', 'shared')
-        const analyticsFile = path.resolve(analyticsDir, 'analytics.json')
+        const analyticsDir = path.resolve(process.cwd(), 'preview', 'shared');
+        const analyticsFile = path.resolve(analyticsDir, 'analytics.json');
 
         // ensure analytics folder & file exist
-        fs.mkdirSync(analyticsDir, {recursive: true})
+        fs.mkdirSync(analyticsDir, { recursive: true });
         if (!fs.existsSync(analyticsFile)) {
-          fs.writeFileSync(analyticsFile, JSON.stringify({}, null, 2), 'utf-8')
+          fs.writeFileSync(analyticsFile, JSON.stringify({}, null, 2), 'utf-8');
         }
 
         // helper to bump and persist counter for a given section
         function bumpSectionCount(section) {
-          const raw = fs.readFileSync(analyticsFile, 'utf-8')
-          const data = JSON.parse(raw)
-          const next = (data[section] || 0) + 1
-          data[section] = next
-          fs.writeFileSync(analyticsFile, JSON.stringify(data, null, 2), 'utf-8')
-          return next
+          const raw = fs.readFileSync(analyticsFile, 'utf-8');
+          const data = JSON.parse(raw);
+          const next = (data[section] || 0) + 1;
+          data[section] = next;
+          fs.writeFileSync(analyticsFile, JSON.stringify(data, null, 2), 'utf-8');
+          return next;
         }
 
         server.middlewares.use((req, res, next) => {
-            const url = req.url || ''
-
-            // Skip HMR and internal Vite requests
-            if (url.startsWith('/@') || url.includes('__vite') || url.includes('.hot-update.')) {
-              return next()
-            }
-
-            // Add CORS headers and disable caching for our API responses
-            if (url.startsWith('/api/') || url.startsWith('/chosen-section')) {
-              res.setHeader('Access-Control-Allow-Origin', '*')
-              res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS')
-              res.setHeader('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept, Authorization')
-              res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate')
-              res.setHeader('Pragma', 'no-cache')
-              res.setHeader('Expires', '0')
-            }
-
-            // Handle preflight OPTIONS requests
-            if (req.method === 'OPTIONS') {
-              res.statusCode = 200
-              return res.end()
-            }
-
-            // Let Vite handle all non-API requests for proper HMR
-            if (!url.startsWith('/api/') && !url.startsWith('/chosen-section')) {
-              return next()
-            }
-
-            if (url.startsWith('/chosen-section')) {
-              // extract "sectionName" from "/chosen-section/<sectionName>"
-
-              const sectionName = req.url.replace(/\/$/, '').split('/').filter(Boolean).pop()
-              const newCount = bumpSectionCount(sectionName)
-
-              res.statusCode = 200
-              res.setHeader('Content-Type', 'application/json')
-              return res.end(JSON.stringify({
-                section: sectionName,
-                count: newCount
-              }))
-            }
-
-            // Handle API routes
-            if (url.startsWith('/api/v1/')) {
-              const sectionName = SECTION_NAME;
-              const showcaseId = SHOWCASE_ID;
-
-              // Delegate to API router
-              (async () => {
-                await handleApiRequest(req, res, sectionName, showcaseId);
-              })();
-              return; // Exit early for async handling
-            }
-
-            // all other requests
-            next()
+          // Invalidate all caches so we fetch most recent sections data
+          server.moduleGraph.invalidateAll();
+
+          const url = req.url || '';
+
+          // Skip HMR and internal Vite requests
+          if (url.startsWith('/@') || url.includes('__vite') || url.includes('.hot-update.')) {
+            return next();
           }
+
+          // Add CORS headers and disable caching for our API responses
+          if (url.startsWith('/api/') || url.startsWith('/chosen-section')) {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept, Authorization');
+            res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate, proxy-revalidate');
+            res.setHeader('Pragma', 'no-cache');
+            res.setHeader('Expires', '0');
+          }
+
+          // Handle preflight OPTIONS requests
+          if (req.method === 'OPTIONS') {
+            res.statusCode = 200;
+            return res.end();
+          }
+
+          // Let Vite handle all non-API requests for proper HMR
+          if (!url.startsWith('/api/') && !url.startsWith('/chosen-section')) {
+            return next();
+          }
+
+          if (url.startsWith('/chosen-section')) {
+            // extract "sectionName" from "/chosen-section/<sectionName>"
+
+            const sectionName = req.url.replace(/\/$/, '').split('/').filter(Boolean).pop();
+            const newCount = bumpSectionCount(sectionName);
+
+            res.statusCode = 200;
+            res.setHeader('Content-Type', 'application/json');
+            return res.end(JSON.stringify({
+              section: sectionName,
+              count: newCount,
+            }));
+          }
+
+          // Handle API routes
+          if (url.startsWith('/api/v1/')) {
+            // Extract auth header from request
+            const authHeader = req.headers['authorization'] || '';
+
+            // Delegate to API router
+            (async () => {
+              await handleApiRequest(req, res, authHeader);
+            })();
+            return; // Exit early for async handling
+          }
+
+          // all other requests
+          next();
+        },
         );
       },
     },

package/template/reference/sections/about-us/AboutUs.vue

@@ -15,7 +15,7 @@
 </template>
 
 <script setup lang="ts">
-import { useBackgroundElementDesign } from '@lightspeed/crane';
+import { useBackgroundElementDesign } from '@lightspeed/crane-api';
 import { computed, CSSProperties } from 'vue';
 
 import Image from './component/Image.vue';

package/template/reference/sections/about-us/client.ts

@@ -1,4 +1,4 @@
-import { createVueClientApp } from '@lightspeed/crane';
+import { createVueClientApp } from '@lightspeed/crane-api';
 
 import ExampleSection from './AboutUs.vue';
 import type { Content, Design } from './type.ts';

package/template/reference/sections/about-us/component/Image.vue

@@ -20,7 +20,7 @@ import {
   useImageElementContent,
   useImageElementDesign,
   useLayoutElementDesign,
-} from '@lightspeed/crane';
+} from '@lightspeed/crane-api';
 import { computed, CSSProperties } from 'vue';
 
 import type { Content, Design } from '../type.ts';

package/template/reference/sections/about-us/component/Stats.vue

@@ -30,14 +30,14 @@
 </template>
 
 <script setup lang="ts">
-import type { Card, InputBoxContent, ButtonContent } from '@lightspeed/crane';
+import type { Card, InputBoxContent, ButtonContent } from '@lightspeed/crane-api';
 import {
   useTextElementDesign,
   EditorTypes,
   useDeckElementContent,
   useButtonElementContent,
   useButtonElementDesign,
-} from '@lightspeed/crane';
+} from '@lightspeed/crane-api';
 import { computed, CSSProperties } from 'vue';
 
 import type { Content, Design } from '../type.ts';

package/template/reference/sections/about-us/component/Title.vue

@@ -8,7 +8,7 @@
 </template>
 
 <script setup lang="ts">
-import { useInputboxElementContent, useTextElementDesign } from '@lightspeed/crane';
+import { useInputboxElementContent, useTextElementDesign } from '@lightspeed/crane-api';
 import { computed, CSSProperties } from 'vue';
 
 import type { Content, Design } from '../type.ts';

package/template/reference/sections/about-us/server.ts

@@ -1,4 +1,4 @@
-import { createVueServerApp } from '@lightspeed/crane';
+import { createVueServerApp } from '@lightspeed/crane-api';
 
 import ExampleSection from './AboutUs.vue';
 import type { Content, Design } from './type.ts';

package/template/reference/sections/about-us/util/visibility-provider.ts

@@ -4,7 +4,7 @@ import {
   useImageElementDesign,
   useInputboxElementContent,
   useTextElementDesign,
-} from '@lightspeed/crane';
+} from '@lightspeed/crane-api';
 import { computed } from 'vue';
 
 import type { Content, Design } from '../type.ts';