Change compiler ID generation logic to use Node.js import specifier

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');

.changeset/rich-symbols-fold.md

@@ -0,0 +1,14 @@
+---
+"@workflow/swc-plugin": patch
+"@workflow/builders": patch
+"@workflow/rollup": patch
+"@workflow/next": patch
+---
+
+Change compiler ID generation logic to use Node.js import specifiers
+
+IDs for workflows, steps, and classes now use module specifiers:
+- Local files use `./path/to/file` format instead of `path/to/file.ext`
+- Package files use `packageName@version` format (e.g., `workflow@4.0.1`)
+
+This enables stable IDs across different package.json export conditions.

packages/builders/src/apply-swc-transform.ts

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { transform } from '@swc/core';
 import { getDecoratorOptionsForDirectory } from './config-helpers.js';
+import { resolveModuleSpecifier } from './module-specifier.js';
 
 const require = createRequire(import.meta.url);
 
@@ -67,6 +68,16 @@ export async function applySwcTransform(
  filename.endsWith('.mts') ||
  filename.endsWith('.cts');
 
+ // Resolve module specifier for packages (node_modules or workspace packages)
+ const projectRoot = process.cwd();
+ const absoluteFilename = isAbsolute(filename)
+ ? filename
+ : join(projectRoot, filename);
+ const { moduleSpecifier } = resolveModuleSpecifier(
+ absoluteFilename,
+ projectRoot
+ );
+
  // Transform with SWC to support syntax esbuild doesn't
  const result = await transform(source, {
  filename,
@@ -88,7 +99,7 @@ export async function applySwcTransform(
  target: 'es2022',
  experimental: mode
  ? {
- plugins: [[swcPluginPath, { mode }]],
+ plugins: [[swcPluginPath, { mode, moduleSpecifier }]],
  }
  : undefined,
  transform: {

packages/builders/src/base-builder.ts

@@ -13,6 +13,7 @@ import {
  type WorkflowManifest,
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+import { getImportPath } from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -319,7 +320,20 @@ export abstract class BaseBuilder {
  });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with the appropriate conditions
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');
@@ -505,7 +519,21 @@ export abstract class BaseBuilder {
  await this.writeDebugFile(outfile, { workflowFiles, serdeOnlyFiles });
 
  // Helper to create import statement from file path
+ // For workspace/node_modules packages, uses the package name so esbuild
+ // will resolve through package.json exports with conditions: ['workflow']
  const createImport = (file: string) => {
+ const { importPath, isPackage } = getImportPath(
+ file,
+ this.config.workingDir
+ );
+
+ if (isPackage) {
+ // Use package name - esbuild will resolve via package.json exports
+ // and apply the 'workflow' condition
+ return `import '${importPath}';`;
+ }
+
+ // Local app file - use relative path
  // Normalize both paths to forward slashes before calling relative()
  // This is critical on Windows where relative() can produce unexpected results with mixed path formats
  const normalizedWorkingDir = this.config.workingDir.replace(/\\/g, '/');

packages/builders/src/index.ts

@@ -9,6 +9,13 @@ export {
 } from './config-helpers.js';
 export { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from './constants.js';
 export { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
+export {
+ clearModuleSpecifierCache,
+ getImportPath,
+ type ImportPathResult,
+ type ModuleSpecifierResult,
+ resolveModuleSpecifier,
+} from './module-specifier.js';
 export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 export {
  createPseudoPackagePlugin,

packages/builders/src/module-specifier.ts

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+/**
+ * Result of resolving a module specifier for a file.
+ */
+export interface ModuleSpecifierResult {
+ /**
+ * The module specifier to use for ID generation.
+ * - For packages: "{name}@{version}" (e.g., "point@1.0.0", "@myorg/shared@2.0.0")
+ * - For local files: undefined (plugin will use default "./relative/path" format)
+ */
+ moduleSpecifier: string | undefined;
+}
+
+/**
+ * Cache for package.json lookups to avoid repeated filesystem reads.
+ * Maps directory path to parsed package.json or null if not found.
+ */
+const packageJsonCache = new Map<
+ string,
+ { name: string; version: string } | null
+>();
+
+/**
+ * Find and read the nearest package.json for a given file path.
+ * Results are cached for performance.
+ */
+function findPackageJson(
+ filePath: string
+): { name: string; version: string } | null {
+ let dir = dirname(filePath);
+
+ while (dir !== dirname(dir)) {
+ // Check cache first
+ const cached = packageJsonCache.get(dir);
+ if (cached !== undefined) {
+ return cached;
+ }
+
+ const packageJsonPath = join(dir, 'package.json');
+ if (existsSync(packageJsonPath)) {
+ try {
+ const content = readFileSync(packageJsonPath, 'utf-8');
+ const parsed = JSON.parse(content);
+ if (parsed.name && parsed.version) {
+ const result = { name: parsed.name, version: parsed.version };
+ packageJsonCache.set(dir, result);
+ return result;
+ }
+ } catch {
+ // Invalid JSON or missing fields, continue searching
+ }
+ }
+
+ packageJsonCache.set(dir, null);
+ dir = dirname(dir);
+ }
+
+ return null;
+}
+
+/**
+ * Check if a file path is inside node_modules.
+ */
+function isInNodeModules(filePath: string): boolean {
+ const normalizedPath = filePath.split(sep).join('/');
+ return normalizedPath.includes('/node_modules/');
+}
+
+/**
+ * Check if a file path is inside a workspace package.
+ * This is a heuristic - we check if the file is in a directory with a package.json
+ * that has a "name" field, but is NOT in node_modules.
+ */
+function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
+ if (isInNodeModules(filePath)) {
+ return false;
+ }
+
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ return false;
+ }
+
+ // Check if the package.json is not the root package.json
+ // Use resolve() to normalize paths for cross-platform comparison
+ const rootPkgPath = resolve(projectRoot, 'package.json');
+
+ // Walk up to find the package.json directory
+ let dir = dirname(filePath);
+ while (dir !== dirname(dir)) {
+ const pkgPath = join(dir, 'package.json');
+ if (existsSync(pkgPath)) {
+ // If this is the root package.json, it's not a workspace package
+ // Use resolve() to normalize both paths before comparison
+ if (resolve(pkgPath) === rootPkgPath) {
+ return false;
+ }
+ // Found a package.json that's not the root - it's a workspace package
+ return true;
+ }
+ dir = dirname(dir);
+ }
+
+ return false;
+}
+
+/**
+ * Resolve the module specifier for a file.
+ *
+ * @param filePath - Absolute path to the file being transformed
+ * @param projectRoot - Absolute path to the project root (usually process.cwd())
+ * @returns The module specifier result
+ *
+ * @example
+ * // File in node_modules
+ * resolveModuleSpecifier('/project/node_modules/point/dist/index.js', '/project')
+ * // => { moduleSpecifier: 'point@1.0.0' }
+ *
+ * @example
+ * // File in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
+ *
+ * @example
+ * // Local app file
+ * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ */
+export function resolveModuleSpecifier(
+ filePath: string,
+ projectRoot: string
+): ModuleSpecifierResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (!inNodeModules && !inWorkspace) {
+ // Local app file - use default relative path format
+ return { moduleSpecifier: undefined };
+ }
+
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (!pkg) {
+ // Couldn't find package.json - fall back to default
+ return { moduleSpecifier: undefined };
+ }
+
+ // Return the module specifier as "name@version"
+ return {
+ moduleSpecifier: `${pkg.name}@${pkg.version}`,
+ };
+}
+
+/**
+ * Clear the package.json cache. Useful for testing or when package.json files may have changed.
+ */
+export function clearModuleSpecifierCache(): void {
+ packageJsonCache.clear();
+}
+
+/**
+ * Result of resolving an import path for a file.
+ */
+export interface ImportPathResult {
+ /**
+ * The import path to use.
+ * - For workspace packages: the package name (e.g., "@myorg/shared")
+ * - For node_modules packages: the package name
+ * - For local files: a relative path (e.g., "./src/workflows/order.ts")
+ */
+ importPath: string;
+
+ /**
+ * Whether this file is from a package (workspace or node_modules).
+ * When true, the import should go through package resolution which respects export conditions.
+ */
+ isPackage: boolean;
+}
+
+/**
+ * Get the import path to use for a file in a bundle's virtual entry.
+ *
+ * For workspace packages and node_modules packages, returns the package name
+ * so that bundler resolution will respect package.json exports and conditions.
+ *
+ * For local app files, returns a relative path.
+ *
+ * @param filePath - Absolute path to the file
+ * @param projectRoot - Absolute path to the project root
+ * @returns The import path and whether it's a package
+ *
+ * @example
+ * // Workspace package
+ * getImportPath('/project/packages/shared/src/index.ts', '/project')
+ * // => { importPath: '@myorg/shared', isPackage: true }
+ *
+ * @example
+ * // Local app file
+ * getImportPath('/project/src/workflows/order.ts', '/project')
+ * // => { importPath: './src/workflows/order.ts', isPackage: false }
+ */
+export function getImportPath(
+ filePath: string,
+ projectRoot: string
+): ImportPathResult {
+ // Check if file is in node_modules or a workspace package
+ const inNodeModules = isInNodeModules(filePath);
+ const inWorkspace =
+ !inNodeModules && isWorkspacePackage(filePath, projectRoot);
+
+ if (inNodeModules || inWorkspace) {
+ // Find the package.json for this file
+ const pkg = findPackageJson(filePath);
+ if (pkg) {
+ return {
+ importPath: pkg.name,
+ isPackage: true,
+ };
+ }
+ }
+
+ // Local app file - use relative path
+ const normalizedProjectRoot = projectRoot.replace(/\\/g, '/');
+ const normalizedFilePath = filePath.replace(/\\/g, '/');
+
+ let relativePath: string;
+ if (normalizedFilePath.startsWith(normalizedProjectRoot + '/')) {
+ relativePath = normalizedFilePath.substring(
+ normalizedProjectRoot.length + 1
+ );
+ } else {
+ // File is outside project root, use the full path segments after common ancestor
+ relativePath = relative(projectRoot, filePath).replace(/\\/g, '/');
+ }
+
+ // Ensure relative paths start with ./
+ if (!relativePath.startsWith('.')) {
+ relativePath = `./${relativePath}`;
+ }
+
+ return {
+ importPath: relativePath,
+ isPackage: false,
+ };
+}

packages/core/e2e/e2e.test.ts

@@ -163,13 +163,17 @@ describe('e2e', () => {
  input: [123],
  output: 133,
  });
- // In local vs. vercel backends, the workflow name is different, so we check for either,
- // since this test runs against both. Also different workbenches have different directory structures.
- expect(json.workflowName).toBeOneOf([
- `workflow//example/${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//${workflow.workflowFile}//${workflow.workflowFn}`,
- `workflow//src/${workflow.workflowFile}//${workflow.workflowFn}`,
- ]);
+ // Workflow ID format: workflow//./{path-without-extension}//{functionName}
+ // Different workbenches have different directory structures:
+ // - workflows/ (standard)
+ // - src/workflows/ (some frameworks)
+ // - example/workflows/ (example app)
+ const fileWithoutExt = workflow.workflowFile.replace(/\.tsx?$/, '');
+ expect(json.workflowName).toMatch(
+ new RegExp(
+ `^workflow//\\./(?:src/|example/)?${fileWithoutExt}//${workflow.workflowFn}$`
+ )
+ );
  });
 
  const isNext = process.env.APP_NAME?.includes('nextjs');