fix(plugin-bff): re-base relative specifiers when copying cross-project client declarations

Author: omarshibli

.changeset/bff-portable-client-types.md

@@ -0,0 +1,7 @@
+---
+'@modern-js/plugin-bff': patch
+---
+
+fix(plugin-bff): re-base relative specifiers when copying cross-project client declarations
+
+The cross-project client generator copied each handler's declaration into `dist/client` verbatim, one directory shallower than its origin, which broke the relative specifiers TypeScript emits. Specifiers are now re-based onto the copy's location so the generated `<package>/api/*` client types resolve in consuming projects.

packages/cli/plugin-bff/src/utils/clientGenerator.ts

@@ -212,9 +212,40 @@ async function setPackage(
   }
 }
 
-export async function copyFiles(from: string, to: string) {
+const RELATIVE_SPECIFIER =
+  /(\bfrom\s*|\bimport\(\s*|\brequire\(\s*)(['"])(\.\.?\/[^'"]*)\2/g;
+
+// The generated client mirrors the handler's declaration but lives one
+// directory shallower (`dist/client/*` vs `dist/<lambda>/*`), so the relative
+// specifiers TypeScript emitted for the origin file must be re-based to keep
+// resolving from the copy's location.
+export function rebaseDeclarationSpecifiers(
+  source: string,
+  fromDir: string,
+  toDir: string,
+) {
+  return source.replace(
+    RELATIVE_SPECIFIER,
+    (_match, lead, quote, specifier) => {
+      const target = path.resolve(fromDir, specifier);
+      const relative = toPosixPath(path.relative(toDir, target));
+      const rebased = relative.startsWith('.') ? relative : `./${relative}`;
+      return `${lead}${quote}${rebased}${quote}`;
+    },
+  );
+}
+
+async function copyDeclarationFile(from: string, to: string) {
   if (await fs.pathExists(from)) {
-    await fs.copy(toPosixPath(from), toPosixPath(to));
+    const source = await fs.readFile(from, 'utf8');
+    await fs.outputFile(
+      to,
+      rebaseDeclarationSpecifiers(
+        source,
+        path.dirname(path.resolve(from)),
+        path.dirname(path.resolve(to)),
+      ),
+    );
   }
 }
 
@@ -264,9 +295,9 @@ async function clientGenerator(draftOptions: APILoaderOptions) {
       const code = await getClitentCode(source.resourcePath, source.source);
       if (code?.value) {
         await writeTargetFile(source.absTargetDir, code.value);
-        await copyFiles(
+        await copyDeclarationFile(
           source.relativeTargetDistDir,
-          source.targetDir.replace(`js`, 'd.ts'),
+          source.targetDir.replace(/\.js$/, '.d.ts'),
         );
       }
     }

packages/cli/plugin-bff/tests/clientGenerator.test.ts

@@ -0,0 +1,43 @@
+import path from 'path';
+import { rebaseDeclarationSpecifiers } from '../src/utils/clientGenerator';
+
+describe('rebaseDeclarationSpecifiers', () => {
+  const originDir = path.resolve('/app/dist/api/lambda/user');
+  const clientDir = path.resolve('/app/dist/client/user');
+
+  test('re-bases relative specifiers onto the copy location', () => {
+    const source = [
+      `import { load } from '../../../src/requests/service';`,
+      `export * from './helper';`,
+      `import fs = require('../shared');`,
+      `export declare const get: () => Promise<import("../../../src/types").Data>;`,
+    ].join('\n');
+
+    const result = rebaseDeclarationSpecifiers(source, originDir, clientDir);
+
+    expect(result).toContain(`from '../../src/requests/service'`);
+    expect(result).toContain(`from '../../api/lambda/user/helper'`);
+    expect(result).toContain(`require('../../api/lambda/shared')`);
+    expect(result).toContain(`import("../../src/types")`);
+  });
+
+  test('leaves bare package specifiers untouched', () => {
+    const source = [
+      `import type { Foo } from '@scope/pkg';`,
+      `import { z } from 'zod';`,
+      `export declare const f: () => import("hono").Context;`,
+    ].join('\n');
+
+    expect(rebaseDeclarationSpecifiers(source, originDir, clientDir)).toBe(
+      source,
+    );
+  });
+
+  test('is a no-op when origin and target directories match', () => {
+    const source = `import { a } from './sibling';\n`;
+
+    expect(rebaseDeclarationSpecifiers(source, originDir, originDir)).toBe(
+      source,
+    );
+  });
+});

tests/integration/bff-corss-project/bff-api-app/api/lambda/index.ts

@@ -7,9 +7,10 @@ import {
   Query,
 } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
+import type { ApiMessage } from '@shared/index';
 import { z } from 'zod';
 
-export default async () => {
+export default async (): Promise<ApiMessage> => {
   return {
     message: 'Hello get bff-api-app',
   };

tests/integration/bff-corss-project/bff-api-app/shared/index.ts

@@ -1 +1,5 @@
 export const COMMON_PREFIX = '/common-api';
+
+export type ApiMessage = {
+  message: string;
+};

tests/integration/bff-corss-project/tests/index.test.ts

@@ -1,4 +1,5 @@
 import dns from 'node:dns';
+import fs from 'node:fs';
 import path from 'path';
 import puppeteer, { type Browser, type Page } from 'puppeteer';
 import {
@@ -157,6 +158,49 @@ describe('corss project bff', () => {
       });
     });
 
+    test('generated client declarations are portable', () => {
+      const clientDir = path.join(apiAppDir, 'dist-1', 'client');
+      const declarations: string[] = [];
+      const walk = (dir: string) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          const full = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            walk(full);
+          } else if (entry.name.endsWith('.d.ts')) {
+            declarations.push(full);
+          }
+        }
+      };
+      walk(clientDir);
+      expect(declarations.length).toBeGreaterThan(0);
+
+      const specifierRegex =
+        /(?:\bfrom\s*|\bimport\(\s*|\brequire\(\s*)(['"])([^'"]+)\1/g;
+      for (const file of declarations) {
+        const content = fs.readFileSync(file, 'utf8');
+        for (const match of content.matchAll(specifierRegex)) {
+          const specifier = match[2];
+          // tsconfig path aliases must not leak into published declarations
+          expect(specifier).not.toMatch(/^@(shared|api)\//);
+          // every relative specifier must resolve inside the dist tree
+          if (specifier.startsWith('.')) {
+            const target = path.resolve(path.dirname(file), specifier);
+            const resolved = [
+              `${target}.d.ts`,
+              path.join(target, 'index.d.ts'),
+            ].some(candidate => fs.existsSync(candidate));
+            expect(`${specifier}:${resolved}`).toBe(`${specifier}:true`);
+          }
+        }
+      }
+
+      const indexClient = fs.readFileSync(
+        path.join(clientDir, 'index.d.ts'),
+        'utf8',
+      );
+      expect(indexClient).toContain('../shared/index');
+    });
+
     test('basic usage', async () => {
       await page.goto(`${host}:${port}/${BASE_PAGE}`, {
         timeout: 50000,