local packages path

Author: alexanderkirtzel

packages/cli/src/commands/bundle/bundler.ts

@@ -138,6 +138,7 @@ export async function bundleCore(
       ([name, packageConfig]) => ({
         name,
         version: packageConfig.version || 'latest',
+        path: packageConfig.path, // Pass local path if defined
       }),
     );
     // downloadPackages adds 'node_modules' subdirectory automatically
@@ -146,6 +147,7 @@ export async function bundleCore(
       TEMP_DIR,
       logger,
       buildOptions.cache,
+      buildOptions.configDir, // For resolving relative local paths
     );
 
     // Fix @walkeros packages to have proper ESM exports

packages/cli/src/commands/bundle/package-manager.ts

@@ -1,12 +1,17 @@
 import pacote from 'pacote';
 import path from 'path';
 import fs from 'fs-extra';
-import { Logger } from '../../core/index.js';
+import {
+  Logger,
+  resolveLocalPackage,
+  copyLocalPackage,
+} from '../../core/index.js';
 import { getPackageCacheKey } from '../../core/cache-utils.js';
 
 export interface Package {
   name: string;
   version: string;
+  path?: string; // Local path to package directory
 }
 
 /**
@@ -123,6 +128,7 @@ export async function downloadPackages(
   targetDir: string,
   logger: Logger,
   useCache = true,
+  configDir?: string, // For resolving relative local paths
 ): Promise<Map<string, string>> {
   const packagePaths = new Map<string, string>();
   const downloadQueue: Package[] = [...packages];
@@ -142,6 +148,29 @@ export async function downloadPackages(
       continue;
     }
     processed.add(pkgKey);
+
+    // Handle local packages first
+    if (pkg.path) {
+      const localPkg = await resolveLocalPackage(
+        pkg.name,
+        pkg.path,
+        configDir || process.cwd(),
+        logger,
+      );
+      const installedPath = await copyLocalPackage(localPkg, targetDir, logger);
+      packagePaths.set(pkg.name, installedPath);
+
+      // Resolve dependencies from local package
+      const deps = await resolveDependencies(pkg, installedPath, logger);
+      for (const dep of deps) {
+        const depKey = `${dep.name}@${dep.version}`;
+        if (!processed.has(depKey)) {
+          downloadQueue.push(dep);
+        }
+      }
+      continue;
+    }
+
     const packageSpec = `${pkg.name}@${pkg.version}`;
     // Use proper node_modules structure: node_modules/@scope/package
     const packageDir = getPackageDirectory(targetDir, pkg.name, pkg.version);

packages/cli/src/commands/simulate/simulator.ts

@@ -11,7 +11,6 @@ import {
   type BuildOptions,
 } from '../../config/index.js';
 import { bundleCore } from '../bundle/bundler.js';
-import { downloadPackages } from '../bundle/package-manager.js';
 import { CallTracker } from './tracker.js';
 import { executeInJSDOM } from './jsdom-executor.js';
 import { executeInNode } from './node-executor.js';
@@ -131,31 +130,10 @@ export async function executeSimulation(
     // Detect platform from flowConfig
     const platform = getPlatform(flowConfig);
 
-    // 2. Download packages to temp directory
-    // This ensures we use clean npm packages, not workspace packages
-    const packagesArray = Object.entries(buildOptions.packages).map(
-      ([name, packageConfig]) => ({
-        name,
-        version:
-          (typeof packageConfig === 'object' &&
-          packageConfig !== null &&
-          'version' in packageConfig &&
-          typeof packageConfig.version === 'string'
-            ? packageConfig.version
-            : undefined) || 'latest',
-      }),
-    );
-    const packagePaths = await downloadPackages(
-      packagesArray,
-      tempDir, // downloadPackages will add 'node_modules' subdirectory itself
-      createLogger({ silent: true }),
-      buildOptions.cache,
-    );
-
-    // 3. Create tracker
+    // 2. Create tracker
     const tracker = new CallTracker();
 
-    // 4. Create temporary bundle
+    // 3. Create temporary bundle
     const tempOutput = path.join(
       tempDir,
       `simulation-bundle-${generateId()}.${platform === 'web' ? 'js' : 'mjs'}`,
@@ -184,7 +162,7 @@ export async function executeSimulation(
           }),
     };
 
-    // 5. Bundle with downloaded packages (they're already in tempDir/node_modules)
+    // 4. Bundle (downloads packages internally)
     await bundleCore(
       flowConfig,
       simulationBuildOptions,
@@ -193,10 +171,10 @@ export async function executeSimulation(
     );
     bundlePath = tempOutput;
 
-    // 6. Load env examples dynamically from destination packages
+    // 5. Load env examples dynamically from destination packages
     const envs = await loadDestinationEnvs(destinations || {});
 
-    // 7. Execute based on platform
+    // 6. Execute based on platform
     let result;
     if (platform === 'web') {
       result = await executeInJSDOM(

packages/cli/src/core/index.ts

@@ -6,3 +6,4 @@ export * from './docker.js';
 export * from './temp-manager.js';
 export * from './asset-resolver.js';
 export * from './utils.js';
+export * from './local-packages.js';

packages/cli/src/core/local-packages.ts

@@ -0,0 +1,83 @@
+import path from 'path';
+import fs from 'fs-extra';
+import type { Logger } from './logger.js';
+
+export interface LocalPackageInfo {
+  name: string;
+  absolutePath: string;
+  distPath: string;
+  hasDistFolder: boolean;
+}
+
+/**
+ * Resolve and validate a local package path
+ */
+export async function resolveLocalPackage(
+  packageName: string,
+  localPath: string,
+  configDir: string,
+  logger: Logger,
+): Promise<LocalPackageInfo> {
+  // Resolve relative to config file directory
+  const absolutePath = path.isAbsolute(localPath)
+    ? localPath
+    : path.resolve(configDir, localPath);
+
+  // Validate path exists
+  if (!(await fs.pathExists(absolutePath))) {
+    throw new Error(
+      `Local package path not found: ${localPath} (resolved to ${absolutePath})`,
+    );
+  }
+
+  // Validate package.json exists
+  const pkgJsonPath = path.join(absolutePath, 'package.json');
+  if (!(await fs.pathExists(pkgJsonPath))) {
+    throw new Error(
+      `No package.json found at ${absolutePath}. Is this a valid package directory?`,
+    );
+  }
+
+  // Check for dist folder
+  const distPath = path.join(absolutePath, 'dist');
+  const hasDistFolder = await fs.pathExists(distPath);
+
+  if (!hasDistFolder) {
+    logger.warn(
+      `⚠️  ${packageName}: No dist/ folder found. Using package root.`,
+    );
+  }
+
+  return {
+    name: packageName,
+    absolutePath,
+    distPath: hasDistFolder ? distPath : absolutePath,
+    hasDistFolder,
+  };
+}
+
+/**
+ * Copy local package to target node_modules directory
+ */
+export async function copyLocalPackage(
+  localPkg: LocalPackageInfo,
+  targetDir: string,
+  logger: Logger,
+): Promise<string> {
+  const packageDir = path.join(targetDir, 'node_modules', localPkg.name);
+
+  await fs.ensureDir(path.dirname(packageDir));
+
+  // Copy dist folder contents (or package root if no dist)
+  await fs.copy(localPkg.distPath, packageDir);
+
+  // Always copy package.json for module resolution
+  await fs.copy(
+    path.join(localPkg.absolutePath, 'package.json'),
+    path.join(packageDir, 'package.json'),
+  );
+
+  logger.info(`📦 Using local: ${localPkg.name} from ${localPkg.absolutePath}`);
+
+  return packageDir;
+}

packages/core/src/schemas/flow.ts

@@ -58,6 +58,7 @@ export const PackagesSchema = z
     z.object({
       version: z.string().optional(),
       imports: z.array(z.string()).optional(),
+      path: z.string().optional(), // Local path (takes precedence over version)
     }),
   )
   .describe('NPM packages to bundle');

packages/core/src/types/flow.ts

@@ -34,7 +34,14 @@ export type Definitions = Record<string, unknown>;
 /**
  * Packages configuration for build.
  */
-export type Packages = Record<string, { version?: string; imports?: string[] }>;
+export type Packages = Record<
+  string,
+  {
+    version?: string;
+    imports?: string[];
+    path?: string; // Local path to package directory (takes precedence over version)
+  }
+>;
 
 /**
  * Web platform configuration.

website/docs/apps/cli.mdx

@@ -58,6 +58,68 @@ The CLI uses types from `@walkeros/core`:
 
 The CLI transforms `Flow.Setup` → `Flow.Config` (per flow) → bundled code that uses `Collector.InitConfig` at runtime.
 
+## Local Packages
+
+By default, the CLI downloads packages from npm. For development or testing unpublished packages, you can use local packages instead by specifying a `path` property.
+
+### Configuration
+
+Add a `path` property to any package to use a local directory instead of npm:
+
+<CodeSnippet
+  code={`{
+  "packages": {
+    "@walkeros/collector": {
+      "version": "latest",
+      "imports": ["startFlow"]
+    },
+    "@my/custom-destination": {
+      "path": "./my-custom-destination",
+      "imports": ["myDestination"]
+    }
+  }
+}`}
+  language="json"
+/>
+
+### Resolution Rules
+
+- **`path` takes precedence** - When both `path` and `version` are specified, `path` is used
+- **Relative paths** - Resolved relative to the config file's directory
+- **Absolute paths** - Used as-is
+- **dist folder** - If a `dist/` folder exists, it's used; otherwise the package root is used
+
+### Use Cases
+
+**Development of custom packages:**
+<CodeSnippet
+  code={`{
+  "packages": {
+    "@my-org/destination-custom": {
+      "path": "../my-destination",
+      "imports": ["destinationCustom"]
+    }
+  }
+}`}
+  language="json"
+/>
+
+**Testing local changes to walkerOS packages:**
+<CodeSnippet
+  code={`{
+  "packages": {
+    "@walkeros/collector": {
+      "version": "latest",
+      "path": "../../packages/collector",
+      "imports": ["startFlow"]
+    }
+  }
+}`}
+  language="json"
+/>
+
+When ready for production, simply remove the `path` property to use the published npm version.
+
 ## Getting Started
 
 Before using the CLI, you need a [flow configuration file](/docs/getting-started/flow). Here's a minimal example:

website/docs/getting-started/flow.mdx

@@ -135,6 +135,23 @@ Specifies npm packages to download and bundle:
 **Properties:**
 - **`version`** - npm version (semver or "latest", defaults to "latest")
 - **`imports`** - Array of named exports to import
+- **`path`** - Local filesystem path (takes precedence over `version`)
+
+For development or custom packages, use `path` to reference a local directory:
+
+<CodeSnippet
+  code={`{
+  "packages": {
+    "@my/custom-destination": {
+      "path": "./my-destination",
+      "imports": ["myDestination"]
+    }
+  }
+}`}
+  language="json"
+/>
+
+See [Local Packages](/docs/apps/cli#local-packages) in the CLI documentation for more details.
 
 ### Sources