@embeddable.com/sdk-core 4.2.0 → 4.3.0-next.0

package/src/generate.test.ts

@@ -1,4 +1,7 @@
-import generate from "./generate";
+import generate, {
+  resetForTesting, TRIGGER_BUILD_ITERATION_LIMIT,
+  triggerWebComponentRebuild, generateDTS
+} from "./generate";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { checkNodeVersion } from "./utils";
@@ -52,6 +55,10 @@ vi.mock("node:fs/promises", () => ({
   rename: vi.fn(),
   cp: vi.fn(),
   rm: vi.fn(),
+  copyFile: vi.fn(),
+  stat: vi.fn(),
+  truncate: vi.fn(),
+  appendFile: vi.fn(),
 }));
 
 vi.mock("node:path", async () => {
@@ -69,6 +76,10 @@ vi.mock("@stencil/core/compiler", () => ({
 }));
 
 describe("generate", () => {
+  const watcherMock = vi.fn().mockResolvedValue({
+    hasError: false,
+    on: vi.fn(),
+  });
   beforeEach(() => {
     vi.mocked(checkNodeVersion).mockResolvedValue(true);
     vi.mocked(fs.readdir).mockResolvedValue([
@@ -86,6 +97,7 @@ describe("generate", () => {
         hasError: false,
       }),
       destroy: vi.fn(),
+      createWatcher: watcherMock,
     } as any);
 
     vi.mocked(getContentHash).mockReturnValue("hash");
@@ -124,7 +136,9 @@ describe("generate", () => {
       dev: {
         watch: true,
         logger: vi.fn(),
-        sys: vi.fn(),
+        sys: vi.mocked({
+          onProcessInterrupt: vi.fn(),
+        }),
       },
     };
 
@@ -134,6 +148,7 @@ describe("generate", () => {
     await generate(ctx as unknown as ResolvedEmbeddableConfig, "sdk-react");
 
     expect(createCompiler).toHaveBeenCalled();
+    expect(watcherMock).toHaveBeenCalled();
 
     expect(fs.writeFile).toHaveBeenCalledWith(
       "componentDir/component.tsx",
@@ -144,6 +159,7 @@ describe("generate", () => {
       config: {
         configPath: "webComponentRoot/stencil.config.ts",
         devMode: true,
+        watchIgnoredRegex: [/\.css$/, /\.d\.ts$/, /\.js$/],
         maxConcurrentWorkers: process.platform === "win32" ? 0 : 8,
         minifyCss: false,
         minifyJs: false,
@@ -161,7 +177,175 @@ describe("generate", () => {
       },
       initTsConfig: true,
       logger: expect.any(Function),
-      sys: expect.any(Function),
+      sys: {
+        onProcessInterrupt: expect.any(Function),
+      },
     });
   });
 });
+
+describe("triggerWebComponentRebuild", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    resetForTesting();
+  });
+
+  it("should store original file stats on first call and append file", async () => {
+    const mockStats = { size: 123 };
+    vi.mocked(fs.stat).mockResolvedValue(mockStats as any);
+
+    await triggerWebComponentRebuild(
+      config as unknown as ResolvedEmbeddableConfig,
+    );
+
+    const filePath = path.resolve(config.client.componentDir, "component.tsx");
+    expect(fs.stat).toHaveBeenCalledWith(filePath);
+    expect(fs.appendFile).toHaveBeenCalledWith(filePath, " ");
+  });
+
+  it("should append file and not call stat after first build", async () => {
+    const mockStats = { size: 123 };
+    vi.mocked(fs.stat).mockResolvedValue(mockStats as any);
+
+    for (let i = 0; i < 3; i++) {
+      await triggerWebComponentRebuild(
+        config as unknown as ResolvedEmbeddableConfig,
+      );
+    }
+
+    expect(fs.stat).toHaveBeenCalledTimes(1); // only once
+    expect(fs.appendFile).toHaveBeenCalledTimes(3);
+    expect(fs.truncate).not.toHaveBeenCalled();
+  });
+
+  it("should reset file using truncate on the 6th call and reset count", async () => {
+    const mockStats = { size: 321 };
+    vi.mocked(fs.stat).mockResolvedValue(mockStats as any);
+    vi.mocked(path.resolve).mockReturnValue("componentDir/component.tsx");
+
+    for (let i = 0; i < TRIGGER_BUILD_ITERATION_LIMIT; i++) {
+      await triggerWebComponentRebuild(
+        config as unknown as ResolvedEmbeddableConfig,
+      );
+    }
+
+    expect(fs.truncate).not.toHaveBeenCalled();
+
+    vi.mocked(fs.appendFile).mockClear();
+    vi.mocked(fs.truncate).mockClear();
+
+    // now truncate should be called
+    await triggerWebComponentRebuild(
+      config as unknown as ResolvedEmbeddableConfig,
+    );
+    const filePath = path.resolve(config.client.componentDir, "component.tsx");
+
+    expect(fs.truncate).toHaveBeenCalledWith(filePath, mockStats.size);
+    expect(fs.appendFile).not.toHaveBeenCalledWith(filePath, " ");
+  });
+});
+
+describe("generateDTS", () => {
+  beforeEach(() => {
+    vi.mocked(fs.readdir).mockResolvedValue([
+      "embeddable-wrapper.esm.js",
+    ] as any);
+    vi.mocked(path.resolve).mockImplementation((...args) => args.join("/"));
+    // Template contains both tokens so we can verify replacement
+    vi.mocked(fs.readFile).mockResolvedValue(
+      "replace-this-with-component-name {{RENDER_IMPORT}}",
+    );
+    vi.mocked(loadConfig).mockResolvedValue({ config: {} } as any);
+    vi.mocked(createCompiler).mockResolvedValue({
+      build: vi.fn().mockResolvedValue({ hasError: false }),
+      destroy: vi.fn(),
+      createWatcher: vi.fn(),
+    } as any);
+    vi.mocked(findFiles).mockResolvedValue([["", ""]]);
+    Object.defineProperties(process, { chdir: { value: vi.fn() } });
+  });
+
+  it("should write an empty style.css", async () => {
+    await generateDTS(config as unknown as ResolvedEmbeddableConfig);
+
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      "componentDir/style.css",
+      "",
+    );
+  });
+
+  it("should write component.tsx with stub render and embeddable-component tag", async () => {
+    await generateDTS(config as unknown as ResolvedEmbeddableConfig);
+
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      "componentDir/component.tsx",
+      expect.stringContaining("embeddable-component"),
+    );
+    expect(fs.writeFile).toHaveBeenCalledWith(
+      "componentDir/component.tsx",
+      expect.stringContaining("const render = () => {};"),
+    );
+  });
+
+  it("should call loadConfig with devMode=false and sourceMap=false", async () => {
+    await generateDTS(config as unknown as ResolvedEmbeddableConfig);
+
+    expect(loadConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: expect.objectContaining({
+          devMode: false,
+          sourceMap: false,
+          minifyJs: false,
+          minifyCss: false,
+        }),
+      }),
+    );
+  });
+
+  it("should not create a watcher (not watch mode)", async () => {
+    const createWatcherMock = vi.fn();
+    vi.mocked(createCompiler).mockResolvedValue({
+      build: vi.fn().mockResolvedValue({ hasError: false }),
+      destroy: vi.fn(),
+      createWatcher: createWatcherMock,
+    } as any);
+
+    await generateDTS(config as unknown as ResolvedEmbeddableConfig);
+
+    expect(createWatcherMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("generate stencil build error", () => {
+  beforeEach(() => {
+    vi.mocked(path.resolve).mockImplementation((...args) => args.join("/"));
+    vi.mocked(fs.readFile).mockResolvedValue("");
+    vi.mocked(fs.readdir).mockResolvedValue([] as any);
+    vi.mocked(loadConfig).mockResolvedValue({ config: {} } as any);
+    vi.mocked(findFiles).mockResolvedValue([["", ""]]);
+  });
+
+  it("should throw when Stencil build has errors", async () => {
+    vi.mocked(createCompiler).mockResolvedValue({
+      build: vi.fn().mockResolvedValue({
+        hasError: true,
+        diagnostics: [{ messageText: "type error" }],
+      }),
+      destroy: vi.fn(),
+      createWatcher: vi.fn(),
+    } as any);
+
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await expect(
+      generate(config as unknown as ResolvedEmbeddableConfig, "sdk-react"),
+    ).rejects.toThrow("Stencil build error");
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Stencil build error:",
+      expect.anything(),
+    );
+
+    consoleSpy.mockRestore();
+  });
+});

package/src/generate.ts

@@ -1,7 +1,11 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { createNodeLogger, createNodeSys } from "@stencil/core/sys/node";
-import { createCompiler, loadConfig } from "@stencil/core/compiler";
+import {
+  CompilerWatcher,
+  createCompiler,
+  loadConfig,
+} from "@stencil/core/compiler";
 import { PluginName, ResolvedEmbeddableConfig } from "./defineConfig";
 import {
   findFiles,
@@ -9,6 +13,8 @@ import {
 } from "@embeddable.com/sdk-utils";
 
 import * as sorcery from "sorcery";
+import { Stats } from "node:fs";
+import type { Logger } from "@stencil/core/internal";
 
 const STYLE_IMPORTS_TOKEN = "{{STYLES_IMPORT}}";
 const RENDER_IMPORT_TOKEN = "{{RENDER_IMPORT}}";
@@ -16,19 +22,92 @@ const RENDER_IMPORT_TOKEN = "{{RENDER_IMPORT}}";
 // stencil doesn't support dynamic component tag name, so we need to replace it manually
 const COMPONENT_TAG_TOKEN = "replace-this-with-component-name";
 
+let triggeredBuildCount = 0;
+/**
+ * Stencil watcher doesnt react on file metadata changes,
+ * so we have to change the file content to trigger a rebuild by appending a space character.
+ * This constant defines how many times the space character can be appended before the file is truncated back to its original size.
+ */
+export const TRIGGER_BUILD_ITERATION_LIMIT = 5;
+let originalFileStats: Stats | null = null;
+
+export function resetForTesting() {
+  triggeredBuildCount = 0;
+  originalFileStats = null;
+}
+
+/**
+ * Triggers a rebuild of a Stencil web component by modifying the `component.tsx` file.
+ *
+ * This function works by appending a space character to the file, which causes Stencil's watcher
+ * to detect a change and rebuild the component. After every TRIGGER_BUILD_ITERATION_LIMIT rebuilds, the file is truncated back
+ * to its original size to prevent indefinite growth and reset the internal rebuild counter.
+ *
+ *  Append and truncate are used instead of rewriting the file to ensure minimal I/O overhead and preserve file metadata.
+ */
+export async function triggerWebComponentRebuild(
+  ctx: ResolvedEmbeddableConfig,
+): Promise<void> {
+  const filePath = path.resolve(ctx.client.componentDir, "component.tsx");
+
+  if (triggeredBuildCount === 0) {
+    // store original file stats on the first build
+    originalFileStats = await fs.stat(filePath);
+  }
+
+  if (triggeredBuildCount === TRIGGER_BUILD_ITERATION_LIMIT && originalFileStats) {
+    await fs.truncate(filePath, originalFileStats.size);
+    triggeredBuildCount = 0; // reset the counter after resetting the file
+  } else {
+    await fs.appendFile(filePath, " ");
+    triggeredBuildCount++;
+  }
+}
+
 export default async (
   ctx: ResolvedEmbeddableConfig,
   pluginName: PluginName,
-) => {
+): Promise<void | CompilerWatcher> => {
   await injectCSS(ctx, pluginName);
 
   await injectBundleRender(ctx, pluginName);
 
-  await runStencil(ctx);
+  const watcher = await runStencil(ctx);
+
+  if (watcher) {
+    watcher.on("buildFinish", () => {
+      // stencil always changes the working directory to the root of the web component.
+      // We need to change it back to the client root directory
+      process.chdir(ctx.client.rootDir);
+      generateSourceMap(ctx, pluginName);
+    });
+  } else {
+    await generateSourceMap(ctx, pluginName);
+  }
 
-  await generateSourceMap(ctx, pluginName);
+  return watcher;
 };
 
+/**
+ * Generates only the d.ts type declaration files using Stencil, without performing a full build.
+ * Used in dev mode to pre-generate types before the watcher starts, avoiding a double-build
+ * triggered by the watcher reacting to freshly generated d.ts files.
+ *
+ * Key differences from the default generate function:
+ * - Writes an empty style.css stub (no real CSS injection needed for type generation)
+ * - Injects a no-op render stub instead of the real render import
+ * - Always creates a fresh sys (never reuses ctx.dev?.sys) to avoid watcher interference
+ */
+export async function generateDTS(
+  ctx: ResolvedEmbeddableConfig,
+): Promise<void> {
+  await injectEmptyCSS(ctx);
+
+  await injectBundleRenderStub(ctx);
+
+  await runStencil(ctx, { dtsOnly: true });
+}
+
 async function injectCSS(
   ctx: ResolvedEmbeddableConfig,
   pluginName: PluginName,
@@ -39,12 +118,14 @@ async function injectCSS(
   );
   const allFiles = await fs.readdir(CUSTOMER_BUILD);
 
+  const importFilePath = path.relative(
+    ctx.client.componentDir,
+    path.resolve(ctx.client.buildDir, ctx[pluginName].outputOptions.buildName),
+  );
+
   const imports = allFiles
     .filter((fileName) => fileName.endsWith(".css"))
-    .map(
-      (fileName) =>
-        `@import '../../${ctx[pluginName].outputOptions.buildName}/${fileName}';`,
-    );
+    .map((fileName) => `@import '${importFilePath}/${fileName}';`);
 
   const componentLibraries = ctx.client.componentLibraries;
   for (const componentLibrary of componentLibraries) {
@@ -76,7 +157,11 @@ async function injectBundleRender(
   ctx: ResolvedEmbeddableConfig,
   pluginName: PluginName,
 ) {
-  const importStr = `import render from '../../${ctx[pluginName].outputOptions.buildName}/${ctx[pluginName].outputOptions.fileName}';`;
+  const importFilePath = path.relative(
+    ctx.client.componentDir,
+    path.resolve(ctx.client.buildDir, ctx[pluginName].outputOptions.buildName),
+  );
+  const importStr = `import render from '${importFilePath}/${ctx[pluginName].outputOptions.fileName}';`;
 
   let content = await fs.readFile(
     path.resolve(ctx.core.templatesDir, "component.tsx.template"),
@@ -93,6 +178,27 @@ async function injectBundleRender(
   );
 }
 
+async function injectEmptyCSS(ctx: ResolvedEmbeddableConfig) {
+  await fs.writeFile(path.resolve(ctx.client.componentDir, "style.css"), "");
+}
+
+async function injectBundleRenderStub(
+  ctx: ResolvedEmbeddableConfig,
+) {
+  const stubStr = `const render = () => {};`;
+
+  let content = await fs.readFile(
+    path.resolve(ctx.core.templatesDir, "component.tsx.template"),
+    "utf8",
+  );
+
+  content = content.replace(COMPONENT_TAG_TOKEN, "embeddable-component");
+  await fs.writeFile(
+    path.resolve(ctx.client.componentDir, "component.tsx"),
+    content.replace(RENDER_IMPORT_TOKEN, stubStr),
+  );
+}
+
 async function addComponentTagName(filePath: string, bundleHash: string) {
   // find entry file with a name *.entry.js
   const entryFiles = await findFiles(path.dirname(filePath), /.*\.entry\.js/);
@@ -123,10 +229,20 @@ async function addComponentTagName(filePath: string, bundleHash: string) {
   ]);
 }
 
-async function runStencil(ctx: ResolvedEmbeddableConfig): Promise<void> {
-  const logger = ctx.dev?.logger || createNodeLogger();
-  const sys = ctx.dev?.sys || createNodeSys({ process });
-  const devMode = !!ctx.dev?.watch;
+async function runStencil(
+  ctx: ResolvedEmbeddableConfig,
+  options?: { dtsOnly?: boolean },
+): Promise<void | CompilerWatcher> {
+  const logger = (options?.dtsOnly ? createNodeLogger() : ctx.dev?.logger || createNodeLogger()) as Logger;
+  const sys = options?.dtsOnly ? createNodeSys({ process }) : (ctx.dev?.sys || createNodeSys({ process }));
+  const devMode = !!ctx.dev?.watch && !options?.dtsOnly;
+  if (options?.dtsOnly) {
+    logger.setLevel("error")
+    logger.createTimeSpan = () => ({
+      duration: () => 0,
+      finish: () => 0,
+    });
+  }
 
   const isWindows = process.platform === "win32";
 
@@ -137,6 +253,8 @@ async function runStencil(ctx: ResolvedEmbeddableConfig): Promise<void> {
     config: {
       devMode,
       maxConcurrentWorkers: isWindows ? 0 : 8, // workers break on windows
+      // we will trigger a rebuild by updating the component.tsx file (see triggerBuild function)
+      watchIgnoredRegex: [/\.css$/, /\.d\.ts$/, /\.js$/],
       rootDir: ctx.client.webComponentRoot,
       configPath: path.resolve(
         ctx.client.webComponentRoot,
@@ -145,9 +263,9 @@ async function runStencil(ctx: ResolvedEmbeddableConfig): Promise<void> {
       tsconfig: path.resolve(ctx.client.webComponentRoot, "tsconfig.json"),
       namespace: "embeddable-wrapper",
       srcDir: ctx.client.componentDir,
-      sourceMap: true, // always generate source maps in both dev and prod
-      minifyJs: !devMode,
-      minifyCss: !devMode,
+      sourceMap: !options?.dtsOnly, // always generate source maps in both dev and prod
+      minifyJs: !devMode && !options?.dtsOnly,
+      minifyCss: !devMode && !options?.dtsOnly,
       outputTargets: [
         {
           type: "dist",
@@ -158,17 +276,23 @@ async function runStencil(ctx: ResolvedEmbeddableConfig): Promise<void> {
   });
 
   const compiler = await createCompiler(validated.config);
+
+  if (devMode) {
+    sys.onProcessInterrupt(() => {
+      compiler.destroy();
+    });
+    return await compiler.createWatcher();
+  }
+
   const buildResults = await compiler.build();
 
-  if (!devMode) {
-    if (buildResults.hasError) {
-      console.error("Stencil build error:", buildResults.diagnostics);
-      throw new Error("Stencil build error");
-    } else {
-      await handleStencilBuildOutput(ctx);
-    }
-    await compiler.destroy();
+  if (buildResults.hasError) {
+    console.error("Stencil build error:", buildResults.diagnostics);
+    throw new Error("Stencil build error");
+  } else {
+    await handleStencilBuildOutput(ctx);
   }
+  await compiler.destroy();
 
   process.chdir(ctx.client.rootDir);
 }

package/src/utils/dev.utils.test.ts

@@ -0,0 +1,126 @@
+import {
+  createWatcherLock,
+  preventContentLength,
+  waitUntilFileStable,
+} from "./dev.utils";
+import { ServerResponse } from "http";
+import * as fs from "node:fs/promises";
+import {createReadStream} from "node:fs";
+import { Readable } from "node:stream";
+
+vi.mock("node:fs/promises", async () => {
+  let size = 100;
+  return {
+    stat: vi.fn().mockImplementation(() => ({ size })),
+  };
+});
+
+vi.mock("node:fs", async () => ({
+  createReadStream: vi.fn()
+}));
+
+describe("preventContentLength", () => {
+  it("should not allow setting 'content-length' header", () => {
+    const headers: Record<string, string> = {};
+    const res = {
+      setHeader: (key: string, value: any) => {
+        headers[key.toLowerCase()] = value;
+      },
+    } as unknown as ServerResponse;
+
+    preventContentLength(res);
+    res.setHeader("content-length", "1234");
+    res.setHeader("x-custom-header", "abc");
+
+    expect(headers["content-length"]).toBeUndefined();
+    expect(headers["x-custom-header"]).toBe("abc");
+  });
+});
+
+describe("createWatcherLock", () => {
+  it("should block and unblock correctly", async () => {
+    const lock = createWatcherLock();
+
+    lock.lock();
+    let unlocked = false;
+
+    const waiter = lock.waitUntilFree().then(() => {
+      unlocked = true;
+    });
+
+    // Still locked
+    expect(unlocked).toBe(false);
+
+    lock.unlock();
+
+    // Wait for Promise resolution
+    await waiter;
+    expect(unlocked).toBe(true);
+  });
+
+  it("should resolve immediately if not locked", async () => {
+    const lock = createWatcherLock();
+    await expect(lock.waitUntilFree()).resolves.toBeUndefined();
+  });
+
+  it("should not resolve until unlock is called", async () => {
+    const lock = createWatcherLock();
+    lock.lock();
+
+    let resolved = false;
+    lock.waitUntilFree().then(() => {
+      resolved = true;
+    });
+
+    await new Promise((r) => setTimeout(r, 20));
+    expect(resolved).toBe(false);
+
+    lock.unlock();
+    await new Promise((r) => setTimeout(r, 0)); // allow promise to resolve
+    expect(resolved).toBe(true);
+  });
+});
+
+describe("waitUntilFileStable", () => {
+  it("should resolve when file becomes stable and has the expected tail", async () => {
+    const filePath = "mock/path.js";
+    const expectedTail = "sourceMappingURL";
+    let size = 10;
+
+    const mockStat = vi.fn().mockImplementation(() => {
+      return Promise.resolve({ size });
+    });
+
+    vi.mocked(fs.stat).mockImplementation(mockStat);
+
+    const streamData = "some data\n// sourceMappingURL=something.js";
+
+    vi.mocked(createReadStream).mockImplementation(() => {
+      return Readable.from([streamData]) as any;
+    });
+
+    await expect(waitUntilFileStable(filePath, expectedTail, {
+      maxAttempts: 5,
+    })).resolves.toBeUndefined();
+
+    expect(fs.stat).toHaveBeenCalled();
+    expect(createReadStream).toHaveBeenCalled();
+  });
+
+  it("should throw if file never stabilizes", async () => {
+    const filePath = "mock/path.js";
+    const expectedTail = "sourceMappingURL";
+
+    vi.mocked(fs.stat).mockResolvedValue({ size: 0 } as any);
+
+    vi.mocked(createReadStream).mockImplementation(() => {
+      return Readable.from([""]) as any;
+    });
+
+    await expect(waitUntilFileStable(filePath, expectedTail, {
+      maxAttempts: 3,
+    })).rejects.toThrow("File did not stabilize");
+
+    expect(fs.stat).toHaveBeenCalled();
+  });
+});