handoff-app 1.1.0 → 1.1.2-0

package/docs/api.md

@@ -78,70 +78,65 @@ to generate only the integration code.
 
 ## Hooks
 
-Hooks allow a typescript or javascript app to interact with the pipeline.
-This is especially useful for modifying or extending the output of the pipeline.
-To use a hook in your project, once you've instantiated the handoff object, you
-can call one of the hook methods and pass a function to the method. The hook
-function will be called at the appropriate point in the pipeline.
-
-For example if you want to alter the integration output, you can do this -
+Hooks let you extend the build and preview pipeline. Configure them in
+`handoff.config.js` (or `.cjs`) under the top-level `hooks` object. Hook names
+use camelCase (for example `validateComponent`, `jsBuildConfig`,
+`registerHandlebarsHelpers`). The Handoff CLI and Node API load this config when
+the `Handoff` instance is created.
 
 ```js
-import Handoff from 'handoff-app';
+// handoff.config.js
+module.exports = {
+  // …
+  hooks: {
+    registerHandlebarsHelpers: ({ handlebars, componentId }) => {
+      handlebars.registerHelper('upperId', () => componentId.toUpperCase());
+    },
+  },
+};
+```
 
-const handoff = new Handoff({
-  // You can customize the configuration here
-});
+### registerHandlebarsHelpers
 
-handoff.postIntegration((documentationObject: DocumentationObject, data: HookReturn[]) => {
-  const colors = documentationObject.design.color.map((color) => {
-    return {
-      name: color.name,
-      value: color.value,
-    };
-  });
-  data.push({
-    filename: 'colors.json',
-    data: JSON.stringify(colors, null, 2),
-  });
-  return data;
-});
+Called immediately after Handoff registers built-in Handlebars helpers (`field`
+and `eq`) while rendering **Handlebars** component previews (static HTML per
+variation). Use it to call `handlebars.registerHelper` for custom helpers used
+in your `.hbs` templates.
 
-handoff.fetch();
-```
+**Arguments (single context object)**
 
-### postIntegration
+* `handlebars` — The Handlebars runtime (same as importing `handlebars`); use
+  `registerHelper`, `SafeString`, etc.
+* `componentId` — The current component’s id string.
+* `properties` — The component’s slot metadata map from the schema (same shape
+  as used by the `field` helper).
+* `injectFieldWrappers` — `true` when generating inspect-mode previews (field
+  inspection markup), `false` for normal previews.
 
-The Post integration hook will allow you to add a function that will be executed
-after the integration build is complete. The function accepts two arguments -
+**Return**
 
-**arguments**
+* `void` — register helpers on `handlebars` directly.
 
-- `tokens: DocumentationObject` This is an instance of the exported
-  DocumentationObject containing all of the tokens.
-- `data: HookReturn[]` This an array of HookReturns, consisting of `filename`
-  and `data`. Each object in this array will be written out to
-  `exported/{integration}-tokens`
+**Notes**
 
-**return**
-The hook must return an array of `HookReturn` objects, or an empty array
+* This hook runs once per preview render (each variation × normal vs inspect).
+* Registering the same helper name again replaces any previous registration for
+  subsequent renders in the same process.
 
-#### Example
+**Example**
 
 ```js
-handoff.postIntegration((documentationObject: DocumentationObject, data: HookReturn[]) => {
-  const colors = documentationObject.design.color.map((color) => {
-    return {
-      name: color.name,
-      value: color.value,
-    };
-  });
-  data.push({
-    filename: 'colors.json',
-    data: JSON.stringify(colors, null, 2),
-  });
-  return data;
-});
+// handoff.config.js
+module.exports = {
+  hooks: {
+    registerHandlebarsHelpers: ({ handlebars, componentId, injectFieldWrappers }) => {
+      handlebars.registerHelper('debugPreview', function () {
+        return injectFieldWrappers ? '[inspect]' : '[preview]';
+      });
+      handlebars.registerHelper('componentLabel', () => componentId);
+    },
+  },
+};
 ```
 
 ### postBuild
@@ -150,7 +145,7 @@ This function is called after the app build is complete.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
 
 **returns**
@@ -163,14 +158,14 @@ application to alter the css generation in transit
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables.
   Any changes you return here will be written to the css files
 
@@ -182,14 +177,14 @@ the transformed output prior to being written to disk.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as CSS variables.
   Any changes you return here will be written to the css files.
 
@@ -201,14 +196,14 @@ the transformed output prior to being written to disk.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `scss: CssTransformerOutput` This is an object containing all of the
+* `scss: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as SCSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as SCSS variables.
   Any changes you return here will be written to the scss files.
 
@@ -224,14 +219,14 @@ the transformed output prior to being written to disk.
 
 **arguments**
 
-- `tokens: DocumentationObject` This is an instance of the exported
+* `tokens: DocumentationObject` This is an instance of the exported
   DocumentationObject containing all of the tokens.
-- `scss: CssTransformerOutput` This is an object containing all of the
+* `scss: CssTransformerOutput` This is an object containing all of the
   type arrays for components and foundations, formatted as SCSS variables
 
 **returns**
 
-- `css: CssTransformerOutput` This is an object containing all of the
+* `css: CssTransformerOutput` This is an object containing all of the
   tokens for components and foundations, formatted as type variables.
   Any changes you return here will be written to the scss type files.
 
@@ -244,11 +239,11 @@ and allows you to alter and return that configuration.
 
 **arguments**
 
-- `webpackConfig: webpack.Configuration` This is a full webpack configuration.
+* `webpackConfig: webpack.Configuration` This is a full webpack configuration.
 
 **returns**
 
-- `webpackConfig: webpack.Configuration` Return the webpack configuration that
+* `webpackConfig: webpack.Configuration` Return the webpack configuration that
   you have altered to fit your needs.
 
 **Example**
@@ -265,15 +260,14 @@ export const modifyWebpackConfigForTailwind = (webpackConfig: webpack.Configurat
 
 This hook allows you to alter the exportable list. You could do this by ejecting
 the handoff configuration and modifying the list, but this hook allows you to
-alter the exportable list with just a couple of lines of code rather than 
+alter the exportable list with just a couple of lines of code rather than
 exporting the whole list
 
 **arguments**
 
-- `exportables: string[]` The current list of exportables
+* `exportables: string[]` The current list of exportables
 
 **returns**
 
-- `exportables: string[]` Return the list with whatever additions and subtractions
-you need for your application.
-
+* `exportables: string[]` Return the list with whatever additions and subtractions
+  you need for your application.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-app",
-  "version": "1.1.0",
+  "version": "1.1.2-0",
   "description": "Automated documentation toolchain for building client side documentation from figma",
   "author ": {
     "name": "Convertiv",

package/src/app/components/Component/ComponentLists.tsx

@@ -8,7 +8,7 @@ import HeadersType from '../Typography/Headers';
 import { Button } from '../ui/button';
 import { Input } from '../ui/input';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select';
-import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../ui/tooltip';
 import { Metadata } from '../util';
 
 interface ComponentMetadata extends Metadata {
@@ -74,7 +74,8 @@ export const ComponentList = ({
   if (!title) title = 'Components';
   if (!description) description = 'Self-contained reusable UI elements that can be used to build larger blocks or design patterns.';
   return (
-    <div className="mx-auto w-full mb-4">
+    <TooltipProvider delayDuration={0}>
+      <div className="mx-auto w-full mb-4">
       <div className="flex justify-between bg-accent rounded-xl mb-8">
         <div className="mr-auto flex items-center gap-3 bg-accent p-2.5 rounded-md">
           <div className="relative">
@@ -183,8 +184,8 @@ export const ComponentList = ({
         })}
         </div>
       )}
-    </div>
-
+      </div>
+    </TooltipProvider>
   );
 };
 

package/src/app/components/Navigation/MainNav.tsx

@@ -31,13 +31,12 @@ export function MainNav() {
                     <NavigationMenuLink className={navigationMenuTriggerStyle()} asChild>
                       <Link
                         href={section.path}
-                        passHref
                         className={cn(
                           'block select-none space-y-1 rounded-sm p-3 leading-none no-underline outline-hidden transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground'
                         )}
                         {...(isActive ? { 'data-active': 'true' } : {})}
                       >
-                        {section.title} {isActive}
+                        {section.title}
                       </Link>
                     </NavigationMenuLink>
                   </>
@@ -51,11 +50,10 @@ export function MainNav() {
                   <NavigationMenuLink className={navigationMenuTriggerStyle()} asChild>
                     <Link
                       href={section.path}
-                      passHref
-                      legacyBehavior
                       className="block select-none space-y-1 rounded-sm p-3 leading-none no-underline outline-hidden transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground"
+                      {...(isActive ? { 'data-active': 'true' } : {})}
                     >
-                      <div className="text-sm leading-none">{section.title}</div>
+                      <span className="text-sm leading-none">{section.title}</span>
                     </Link>
                   </NavigationMenuLink>
                 )}

package/src/app/components/Navigation/SideNav.tsx

@@ -30,19 +30,16 @@ import {
   SidebarMenuSub,
   SidebarSeparator,
 } from '../../components/ui/sidebar';
+import { normalizePathForMatch, toAbsolutePath } from '../../lib/utils';
 import { SectionLink } from '../util';
 
-const trimSlashes = (input: string): string => {
-  return input.replace(/^\/+|\/+$/g, '');
-};
-
 const NormalMenuItem = ({ title, icon, path }) => {
   const router = useRouter();
-  const isActive = trimSlashes(path) === trimSlashes(router.asPath);
+  const isActive = normalizePathForMatch(path) === normalizePathForMatch(router.asPath);
   return (
     <SidebarMenuItem>
       <SidebarMenuButton asChild isActive={isActive}>
-        <a href={`/${path}`} className="gap-3">
+        <a href={toAbsolutePath(path)} className="gap-3">
           <MenuIcon icon={icon} isActive={isActive} />
           <span>{title}</span>
         </a>
@@ -54,7 +51,7 @@ const NormalMenuItem = ({ title, icon, path }) => {
 const CollapsibleMenuItem = ({ title, icon, path, menu }) => {
   const router = useRouter();
   const isActive = menu.some(
-    (item) => trimSlashes(router.asPath).startsWith(trimSlashes(item.path)) || trimSlashes(item.path) === trimSlashes(router.asPath)
+    (item) => normalizePathForMatch(router.asPath).startsWith(normalizePathForMatch(item.path))
   );
   return (
     <Collapsible defaultOpen={isActive} className="group/collapsible">

package/src/app/components/SideNav/Custom.tsx

@@ -1,9 +1,11 @@
 import { usePathname } from 'next/navigation';
+import { normalizePathForMatch, toAbsolutePath } from '../../lib/utils';
 import NavLink from '../NavLink';
 import { SectionLink } from '../util';
 
 const CustomNav = ({ menu }: { menu: SectionLink }) => {
   const pathname = usePathname();
+  const normalizedPathname = normalizePathForMatch(pathname ?? '');
   return (
     <nav className="c-sidenav">
       <ul>
@@ -13,14 +15,14 @@ const CustomNav = ({ menu }: { menu: SectionLink }) => {
               <small>{item.title}</small>
             ) : (
               <>
-                <NavLink href={`/${item.path}`}>
+                <NavLink href={toAbsolutePath(item.path)}>
                   {item.title}
                 </NavLink>
                 {item.menu && (
-                  <ul className={`c-sidenav__sub${pathname.includes(item.path) ? ' is-active' : ''}`}>
+                  <ul className={`c-sidenav__sub${normalizedPathname.startsWith(normalizePathForMatch(item.path)) ? ' is-active' : ''}`}>
                     {item.menu.map((subItem) => (
                       <li key={subItem.path}>
-                        <NavLink key={subItem.path} href={`/${subItem.path}`} className="c-sidenav__sub-item">
+                        <NavLink key={subItem.path} href={toAbsolutePath(subItem.path)} className="c-sidenav__sub-item">
                           {subItem.title}
                         </NavLink>
                       </li>

package/src/app/components/ui/mobile-nav.tsx

@@ -1,8 +1,9 @@
 'use client';
 
 import Link from 'next/link';
-import { usePathname, useRouter } from 'next/navigation';
+import { usePathname } from 'next/navigation';
 import * as React from 'react';
+import { normalizePathForMatch, toAbsolutePath } from '../../lib/utils';
 import { SectionLink } from '../util';
 
 import { Button } from './button';
@@ -15,7 +16,7 @@ interface MobileNavProps {
 export function MobileNav({ menu }: MobileNavProps) {
   const [open, setOpen] = React.useState(false);
   const pathname = usePathname();
-  const router = useRouter();
+  const normalizedPathname = normalizePathForMatch(pathname ?? '');
 
   const onOpenChange = React.useCallback((open: boolean) => {
     setOpen(open);
@@ -52,24 +53,26 @@ export function MobileNav({ menu }: MobileNavProps) {
                   ) : (
                     <>
                       <Link
-                        href={`/${item.path}`}
+                        href={toAbsolutePath(item.path)}
                         className="text-[1.15rem]"
                         onClick={() => {
-                          router.push(`/${item.path}`);
                           setOpen(false);
                         }}
                       >
                         {item.title}
                       </Link>
                       {item.menu && (
-                        <ul className={`ml-4 mt-2 space-y-2${pathname.includes(item.path) ? ' is-active' : ''}`}>
+                        <ul
+                          className={`ml-4 mt-2 space-y-2${
+                            normalizedPathname.startsWith(normalizePathForMatch(item.path)) ? ' is-active' : ''
+                          }`}
+                        >
                           {item.menu.map((subItem) => (
                             <li key={subItem.path}>
                               <Link
-                                href={`/${subItem.path}`}
+                                href={toAbsolutePath(subItem.path)}
                                 className="text-[1rem] opacity-80"
                                 onClick={() => {
-                                  router.push(`/${subItem.path}`);
                                   setOpen(false);
                                 }}
                               >

package/src/app/components/util/index.ts

@@ -290,10 +290,10 @@ export const staticBuildMenu = () => {
 };
 
 const buildBasePath = () => {
-  if(!process.env.HANDOFF_APP_BASE_PATH) {
+  if (!process.env.HANDOFF_APP_BASE_PATH) {
     return '';
   }
-  return (process.env.HANDOFF_APP_BASE_PATH ?? '').replace(/^\//, '') + '/';
+  return (process.env.HANDOFF_APP_BASE_PATH ?? '').replace(/^\/+|\/+$/g, '') + '/';
 };
 
 const staticBuildComponentMenu = (type?: boolean | string) => {

package/src/app/lib/utils.ts

@@ -5,6 +5,19 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs));
 }
 
+export const trimSlashes = (input: string): string => {
+  return input.replace(/^\/+|\/+$/g, '');
+};
+
+export const toAbsolutePath = (input: string): string => {
+  return `/${trimSlashes(input)}`;
+};
+
+export const normalizePathForMatch = (input: string): string => {
+  const [pathname] = input.split(/[?#]/);
+  return trimSlashes(pathname);
+};
+
 /**
  * Filters out null values
  * @param value

package/src/app/next.config.mjs

@@ -2,6 +2,14 @@ import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'path';
 
+const resolveBasePath = (rawBasePath) => {
+  if (!rawBasePath || rawBasePath.startsWith('%HANDOFF_')) {
+    return '';
+  }
+  const trimmed = rawBasePath.replace(/^\/+|\/+$/g, '');
+  return trimmed ? `/${trimmed}` : '';
+};
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   output: 'export',
@@ -19,14 +27,14 @@ const nextConfig = {
     tsconfigPath: 'tsconfig.json',
   },
   //distDir: 'out',
-  basePath: '',
+  basePath: resolveBasePath('%HANDOFF_APP_BASE_PATH%'),
   env: {
-    HANDOFF_PROJECT_ID: '',
-    HANDOFF_APP_BASE_PATH: '',
-    HANDOFF_WORKING_PATH: '',
-    HANDOFF_MODULE_PATH: '',
-    HANDOFF_EXPORT_PATH: '',
-    HANDOFF_WEBSOCKET_PORT: '',
+    HANDOFF_PROJECT_ID: '%HANDOFF_PROJECT_ID%',
+    HANDOFF_APP_BASE_PATH: '%HANDOFF_APP_BASE_PATH%',
+    HANDOFF_WORKING_PATH: '%HANDOFF_WORKING_PATH%',
+    HANDOFF_MODULE_PATH: '%HANDOFF_MODULE_PATH%',
+    HANDOFF_EXPORT_PATH: '%HANDOFF_EXPORT_PATH%',
+    HANDOFF_WEBSOCKET_PORT: '%HANDOFF_WEBSOCKET_PORT%',
   },
   images: {
     unoptimized: true,
@@ -38,12 +46,12 @@ const nextConfig = {
 
       // Local environment
       const env = {
-        HANDOFF_PROJECT_ID: '',
-        HANDOFF_APP_BASE_PATH: '',
-        HANDOFF_WORKING_PATH: '',
-        HANDOFF_MODULE_PATH: '',
-        HANDOFF_EXPORT_PATH: '',
-        HANDOFF_WEBSOCKET_PORT: '',
+        HANDOFF_PROJECT_ID: '%HANDOFF_PROJECT_ID%',
+        HANDOFF_APP_BASE_PATH: '%HANDOFF_APP_BASE_PATH%',
+        HANDOFF_WORKING_PATH: '%HANDOFF_WORKING_PATH%',
+        HANDOFF_MODULE_PATH: '%HANDOFF_MODULE_PATH%',
+        HANDOFF_EXPORT_PATH: '%HANDOFF_EXPORT_PATH%',
+        HANDOFF_WEBSOCKET_PORT: '%HANDOFF_WEBSOCKET_PORT%',
       };
 
       // Check if client configuration exists

package/src/app/pages/system/component/[component]/index.tsx

@@ -163,7 +163,7 @@ const GenericComponentPage = ({ menu, metadata, current, id, config, componentHo
   }, [component, id]);
 
   if (!component) return <p>Loading...</p>;
-  const apiUrl = (window.location.origin && window.location.origin) + `/api/component/${id}.json`;
+  const apiUrl = (window.location.origin && window.location.origin) + `${normalizedBasePath}/api/component/${id}.json`;
   return (
     <Layout config={config} menu={menu} current={current} metadata={metadata}>
       <div className="flex flex-col gap-3 pb-14">

package/src/app-builder/build.ts

@@ -12,6 +12,8 @@ import { getAppPath, syncPublicFiles } from './paths';
 import { WatcherState, getRuntimeComponentsPathsToWatch, watchAppSource, watchGlobalEntries, watchPages, watchPublicDirectory, watchRuntimeComponents, watchRuntimeConfiguration } from './watchers';
 import { createWebSocketServer } from './websocket';
 
+const escapeForSingleQuotedJsString = (value: string): string => value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+
 /**
  * Performs cleanup of the application directory by removing the existing app directory if it exists.
  */
@@ -49,8 +51,7 @@ const initializeProjectApp = async (handoff: Handoff): Promise<string> => {
     Logger.success(`Custom theme.css loaded`);
   }
 
-  // Prepare project app configuration
-  // Warning: Regex replacement is fragile and depends on exact formatting in next.config.mjs
+  // Prepare project app configuration using stable placeholder replacement.
   const handoffProjectId = handoff.getProjectId();
   const handoffAppBasePath = handoff.config.app.base_path ?? '';
   const handoffWorkingPath = path.resolve(handoff.workingPath);
@@ -59,15 +60,24 @@ const initializeProjectApp = async (handoff: Handoff): Promise<string> => {
   const nextConfigPath = path.resolve(srcPath, 'next.config.mjs');
   const targetPath = path.resolve(appPath, 'next.config.mjs');
   const handoffWebsocketPort = handoff.config.app.ports?.websocket ?? 3001;
-  const nextConfigContent = (await fs.readFile(nextConfigPath, 'utf-8'))
-    .replace(/basePath:\s+''/g, `basePath: '${handoffAppBasePath}'`)
-    .replace(/HANDOFF_PROJECT_ID:\s+''/g, `HANDOFF_PROJECT_ID: '${handoffProjectId}'`)
-    .replace(/HANDOFF_APP_BASE_PATH:\s+''/g, `HANDOFF_APP_BASE_PATH: '${handoffAppBasePath}'`)
-    .replace(/HANDOFF_WORKING_PATH:\s+''/g, `HANDOFF_WORKING_PATH: '${handoffWorkingPath}'`)
-    .replace(/HANDOFF_MODULE_PATH:\s+''/g, `HANDOFF_MODULE_PATH: '${handoffModulePath}'`)
-    .replace(/HANDOFF_EXPORT_PATH:\s+''/g, `HANDOFF_EXPORT_PATH: '${handoffExportPath}'`)
-    .replace(/HANDOFF_WEBSOCKET_PORT:\s+''/g, `HANDOFF_WEBSOCKET_PORT: '${handoffWebsocketPort}'`)
-    .replace(/%HANDOFF_MODULE_PATH%/g, handoffModulePath);
+  const escapedAppBasePath = escapeForSingleQuotedJsString(handoffAppBasePath);
+  const escapedProjectId = escapeForSingleQuotedJsString(handoffProjectId);
+  const escapedWorkingPath = escapeForSingleQuotedJsString(handoffWorkingPath);
+  const escapedModulePath = escapeForSingleQuotedJsString(handoffModulePath);
+  const escapedExportPath = escapeForSingleQuotedJsString(handoffExportPath);
+  const escapedWebsocketPort = escapeForSingleQuotedJsString(String(handoffWebsocketPort));
+  const placeholderValues: Record<string, string> = {
+    '%HANDOFF_PROJECT_ID%': escapedProjectId,
+    '%HANDOFF_APP_BASE_PATH%': escapedAppBasePath,
+    '%HANDOFF_WORKING_PATH%': escapedWorkingPath,
+    '%HANDOFF_MODULE_PATH%': escapedModulePath,
+    '%HANDOFF_EXPORT_PATH%': escapedExportPath,
+    '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
+  };
+  let nextConfigContent = await fs.readFile(nextConfigPath, 'utf-8');
+  for (const [placeholder, value] of Object.entries(placeholderValues)) {
+    nextConfigContent = nextConfigContent.split(placeholder).join(value);
+  }
   await fs.writeFile(targetPath, nextConfigContent);
   return appPath;
 };

package/src/app-builder/watchers.ts

@@ -7,6 +7,7 @@ import { buildMainJS } from '../transformers/preview/component/javascript';
 import processComponents, { ComponentSegment } from '../transformers/preview/component/builder';
 import { ComponentListObject } from '../transformers/preview/types';
 import { Logger } from '../utils/logger';
+import { isPathInside, normalizePathForCompare } from '../utils/path';
 import { persistClientConfig } from './client-config';
 import { syncPublicFiles } from './paths';
 
@@ -115,12 +116,6 @@ export const watchGlobalEntries = (handoff: Handoff, state: WatcherState, chokid
   const pathsToWatch = [...scssPathsToWatch, ...jsPathsToWatch];
   if (pathsToWatch.length === 0) return;
 
-  const isPathInside = (filePath: string, parentPath: string): boolean => {
-    const normalizedFilePath = path.resolve(filePath);
-    const normalizedParentPath = path.resolve(parentPath);
-    return normalizedFilePath === normalizedParentPath || normalizedFilePath.startsWith(`${normalizedParentPath}${path.sep}`);
-  };
-
   chokidar.watch(pathsToWatch, chokidarConfig).on('all', async (event, file) => {
     switch (event) {
       case 'add':
@@ -206,11 +201,17 @@ export const watchRuntimeComponents = (
 
   if (runtimeComponentPathsToWatch.size > 0) {
     const pathsToWatch = Array.from(runtimeComponentPathsToWatch.keys());
+    const runtimeComponentEntryTypeByPath = new Map<string, keyof ComponentListObject['entries']>(
+      Array.from(runtimeComponentPathsToWatch.entries()).map(([watchPath, entryType]) => [normalizePathForCompare(watchPath), entryType])
+    );
+    const configFileSet = new Set(handoff.getConfigFilePaths().map((configPath) => normalizePathForCompare(configPath)));
+
     state.runtimeComponentsWatcher = chokidar.watch(pathsToWatch, {
       ignoreInitial: true,
     });
     state.runtimeComponentsWatcher.on('all', async (event, file) => {
-      if (handoff.getConfigFilePaths().includes(file)) {
+      const normalizedFile = normalizePathForCompare(file);
+      if (configFileSet.has(normalizedFile)) {
         return;
       }
 
@@ -221,7 +222,7 @@ export const watchRuntimeComponents = (
           if (!state.debounce) {
             state.debounce = true;
             try {
-              const entryType = runtimeComponentPathsToWatch.get(file);
+              const entryType = runtimeComponentEntryTypeByPath.get(normalizedFile);
               const segmentToUpdate: ComponentSegment = entryType ? mapEntryTypeToSegment(entryType) : undefined;
 
               const componentDir = path.basename(path.dirname(file));