swallowkit 1.1.2 → 2.0.0-alpha.1

package/src/__tests__/release-metadata.test.ts

@@ -0,0 +1,121 @@
+import * as fs from "fs";
+import * as path from "path";
+import { spawnSync } from "child_process";
+
+describe("npm release metadata", () => {
+  const repository = process.cwd();
+  const script = path.join(repository, "scripts", "release-metadata.cjs");
+  let directory: string;
+
+  beforeEach(() => {
+    directory = fs.mkdtempSync(path.join(repository, ".tmp-release-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(directory, { recursive: true, force: true });
+  });
+
+  function run(
+    version: unknown,
+    options: {
+      refType?: string;
+      refName?: string;
+      lockVersion?: string;
+      rootVersion?: string;
+      noRootPackage?: boolean;
+    } = {}
+  ) {
+    fs.writeFileSync(
+      path.join(directory, "package.json"),
+      JSON.stringify({ name: "swallowkit", version })
+    );
+    fs.writeFileSync(
+      path.join(directory, "package-lock.json"),
+      JSON.stringify({
+        version: options.lockVersion ?? version,
+        packages: options.noRootPackage
+          ? {}
+          : { "": { version: options.rootVersion ?? version } },
+      })
+    );
+    const outputPath = path.join(directory, "output.txt");
+    const result = spawnSync(process.execPath, [script], {
+      cwd: directory,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        GITHUB_REF_TYPE: options.refType ?? "tag",
+        GITHUB_REF_NAME: options.refName ?? `v${version}`,
+        GITHUB_OUTPUT: outputPath,
+      },
+    });
+    expect(result.error).toBeUndefined();
+    const output = fs.existsSync(outputPath)
+      ? fs.readFileSync(outputPath, "utf8")
+      : "";
+    return { ...result, output };
+  }
+
+  it.each([
+    ["2.0.0", "latest"],
+    ["2.0.0-alpha.1", "alpha"],
+    ["2.0.0-alpha.2", "alpha"],
+    ["2.0.0-alpha", "alpha"],
+    ["2.0.0-beta.1", "beta"],
+    ["2.0.0-beta.12", "beta"],
+    ["2.0.0-rc.1", "next"],
+    ["2.0.0-next.1", "next"],
+    ["2.0.0-alphabet.1", "next"],
+    ["2.0.0-0", "next"],
+    ["2.0.0+build.1", "latest"],
+    ["2.0.0-alpha.1+build.1", "alpha"],
+  ])("publishes %s on the %s channel", (version, channel) => {
+    const result = run(version);
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.output).toBe(`version=${version}\ndist_tag=${channel}\n`);
+    expect(result.stdout).toBe(result.output);
+  });
+
+  it("supports manual branch dry runs without requiring a release tag", () => {
+    const result = run("2.0.0-alpha.1", {
+      refType: "branch",
+      refName: "main",
+    });
+    expect(result.status).toBe(0);
+    expect(result.output).toContain("dist_tag=alpha\n");
+  });
+
+  it.each([
+    { refName: "v2.0.0" },
+    { refName: "2.0.0-alpha.1" },
+    { lockVersion: "1.1.2" },
+    { rootVersion: "1.1.2" },
+    { noRootPackage: true },
+  ])("rejects inconsistent release metadata: %j", (options) => {
+    const result = run("2.0.0-alpha.1", options);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain("must match");
+    expect(result.output).toBe("");
+  });
+
+  it.each([
+    undefined,
+    2,
+    "",
+    "v2.0.0-alpha.1",
+    "2.0",
+    "02.0.0",
+    "2.0.0-",
+    "2.0.0-alpha.01",
+    "2.0.0-alpha..1",
+    "2.0.0-alpha_1",
+    "2.0.0\n",
+    "2.0.0-alpha.1\ndist_tag=latest",
+  ])("rejects invalid versions before emitting Actions outputs: %j", (version) => {
+    const result = run(version);
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain("must be a valid SemVer version");
+    expect(result.output).toBe("");
+  });
+});

package/src/cli/commands/add-auth.ts

@@ -5,8 +5,10 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { ensureSwallowKitProject, getBackendLanguage, getConnectorDefinition, getValidatedFullConfig } from "../../core/config";
-import { AuthProvider, BackendLanguage, CustomJwtConfig, RdbConnectorConfig } from "../../types";
+import { ensureSwallowKitProject, getBackendLanguage, getFrontendFramework, getConnectorDefinition, getValidatedFullConfig } from "../../core/config";
+import { generateManagedFunctionConfig, generateReactAuthBff, generateReactBffHelper } from "../../core/scaffold/react-bff-generator";
+import { adaptReactPage } from "../../core/scaffold/react-ui-generator";
+import { AuthConfig, AuthProvider, BackendLanguage, CustomJwtConfig, RdbConnectorConfig } from "../../types";
 import {
   generateAuthModels,
   generateAuthFunctionsTS,
@@ -98,6 +100,32 @@ function defaultCustomJwtConfig(): CustomJwtConfig {
   };
 }
 
+function writeCallFunction(cwd: string, session: FileOperationSession, nextSource: string, auth: AuthConfig): void {
+  if (getFrontendFramework() === "react") {
+    const name = JSON.parse(session.readFile(path.join(cwd, "package.json"))).name;
+    session.writeFile(path.join(cwd, "bff", "src", "lib", "call-function.ts"), generateReactBffHelper(name, auth), managedMeta);
+  } else {
+    session.writeFile(path.join(cwd, "lib", "api", "call-function.ts"), nextSource, managedMeta);
+  }
+}
+
+function writeLoginPage(cwd: string, session: FileOperationSession, source: string): void {
+  const react = getFrontendFramework() === "react";
+  const destination = react ? path.join(cwd, "src", "pages", "login.tsx") : path.join(cwd, "app", "login", "page.tsx");
+  session.writeFile(destination, react ? adaptReactPage(source) : source, managedMeta);
+}
+
+function writeAuthContext(cwd: string, session: FileOperationSession, source: string): void {
+  session.writeFile(path.join(cwd, "lib", "auth", "auth-context.tsx"), getFrontendFramework() === "react" ? adaptReactPage(source) : source, managedMeta);
+}
+
+function writeManagedAuthRoute(cwd: string, session: FileOperationSession, customJwt: boolean): void {
+  const name = JSON.parse(session.readFile(path.join(cwd, "package.json"))).name;
+  const sharedName = JSON.parse(session.readFile(path.join(cwd, "shared", "package.json"))).name;
+  session.writeFile(path.join(cwd, "bff", "src", "auth", "index.ts"), generateReactAuthBff(name, sharedName, customJwt), managedMeta);
+  session.writeFile(path.join(cwd, "bff", "auth", "function.json"), generateManagedFunctionConfig("auth/{action}", ["GET", "POST"], "auth"), managedMeta);
+}
+
 function setupSwaAuth(cwd: string, backendLanguage: BackendLanguage, session: FileOperationSession, allowedProviders?: string[]): void {
   const providers = normalizeSwaProviders(allowedProviders);
   const helperPath = backendLanguage === "typescript"
@@ -112,14 +140,12 @@ function setupSwaAuth(cwd: string, backendLanguage: BackendLanguage, session: Fi
       : generateSwaAuthHelperPython();
   session.writeFile(helperPath, helper, managedMeta);
 
-  const callFnPath = path.join(cwd, "lib", "api", "call-function.ts");
-  session.writeFile(callFnPath, generateBFFCallFunctionWithSwaAuth(), managedMeta);
+  writeCallFunction(cwd, session, generateBFFCallFunctionWithSwaAuth(), { provider: "swa" });
 
   const authDir = path.join(cwd, "lib", "auth");
   session.writeFile(path.join(authDir, "auth-context.tsx"), generateSwaAuthContext(providers), managedMeta);
   updateRootLayoutWithAuthProvider(cwd, session);
-  const loginDir = path.join(cwd, "app", "login");
-  session.writeFile(path.join(loginDir, "page.tsx"), generateSwaLoginPage(providers), managedMeta);
+  writeLoginPage(cwd, session, generateSwaLoginPage(providers));
   updateSwaRouteConfig(cwd, session, providers);
 }
 
@@ -127,10 +153,10 @@ function setupExternalTokenAuth(cwd: string, backendLanguage: BackendLanguage, s
   const authDir = path.join(cwd, "lib", "auth");
   writeIfMissing(session, path.join(authDir, "external-token-adapter.ts"), generateExternalTokenAdapter());
   session.writeFile(path.join(authDir, "authenticated-fetch.ts"), generateAuthenticatedFetch(), managedMeta);
-  session.writeFile(path.join(authDir, "auth-context.tsx"), generateExternalTokenAuthContext(), managedMeta);
-  session.writeFile(path.join(cwd, "lib", "api", "call-function.ts"), generateBFFCallFunctionWithAuth(), managedMeta);
-  const meDir = path.join(cwd, "app", "api", "auth", "me");
-  session.writeFile(path.join(meDir, "route.ts"), generateExternalTokenBFFMeRoute(), managedMeta);
+  writeAuthContext(cwd, session, generateExternalTokenAuthContext());
+  writeCallFunction(cwd, session, generateBFFCallFunctionWithAuth(), { provider: "external-token" });
+  if (getFrontendFramework() === "react") writeManagedAuthRoute(cwd, session, false);
+  else session.writeFile(path.join(cwd, "app", "api", "auth", "me", "route.ts"), generateExternalTokenBFFMeRoute(), managedMeta);
   updateRootLayoutWithAuthProvider(cwd, session);
 
   if (backendLanguage === "typescript") {
@@ -240,6 +266,14 @@ export function addAuthProviderToRootLayout(layout: string): string {
 }
 
 function updateRootLayoutWithAuthProvider(cwd: string, session: FileOperationSession): void {
+  if (getFrontendFramework() === "react") {
+    const mainPath = path.join(cwd, "src", "main.tsx");
+    const main = session.readFile(mainPath);
+    if (main.includes("<AuthProvider>")) return;
+    if (!main.includes("<App />")) throw new Error("Could not find <App /> in src/main.tsx; cannot install AuthProvider");
+    session.writeFile(mainPath, `import { AuthProvider } from '@/lib/auth/auth-context';\n${main.replace("<App />", "<AuthProvider><App /></AuthProvider>")}`, extensionMeta);
+    return;
+  }
   const layoutPath = path.join(cwd, "app", "layout.tsx");
   if (!session.fileExists(layoutPath)) {
     throw new Error("app/layout.tsx was not found; cannot install AuthProvider");
@@ -364,27 +398,25 @@ export async function addAuthCommand(options: AddAuthOptions) {
 
   // 4. Generate proxy
   console.log("\n  Generating proxy...");
-  const proxyPath = path.join(cwd, "proxy.ts");
-  session.writeFile(proxyPath, generateProxy(projectName), managedMeta);
-  console.log(` Created: proxy.ts`);
+  if (getFrontendFramework() === "nextjs") {
+    const proxyPath = path.join(cwd, "proxy.ts");
+    session.writeFile(proxyPath, generateProxy(projectName), managedMeta);
+    console.log(` Created: proxy.ts`);
+  }
 
   // 5. Generate login page
   console.log("\n Generating login page...");
-  const loginDir = path.join(cwd, "app", "login");
-  session.writeFile(path.join(loginDir, "page.tsx"), generateLoginPage(), managedMeta);
-  console.log(` Created: app/login/page.tsx`);
+  writeLoginPage(cwd, session, generateLoginPage());
 
   // 6. Generate auth context
   console.log("\n Generating auth context...");
-  const authLibDir = path.join(cwd, "lib", "auth");
-  session.writeFile(path.join(authLibDir, "auth-context.tsx"), generateAuthContext(), managedMeta);
+  writeAuthContext(cwd, session, generateAuthContext());
   console.log(`✅ Created: lib/auth/auth-context.tsx`);
 
   // 7. Update callFunction with auth support
   console.log("\n Updating callFunction with auth support...");
-  const callFnPath = path.join(cwd, "lib", "api", "call-function.ts");
-  session.writeFile(callFnPath, generateBFFCallFunctionWithAuth(), managedMeta);
-  console.log(` Updated: lib/api/call-function.ts`);
+  writeCallFunction(cwd, session, generateBFFCallFunctionWithAuth(), { provider: "custom-jwt" });
+  console.log(` Updated: ${getFrontendFramework() === "react" ? "bff/src/lib" : "lib/api"}/call-function.ts`);
 
   // 8. Update swallowkit.config.js
   console.log("\n Updating configuration...");
@@ -498,11 +530,19 @@ function addNamedScheme(cwd: string, scheme: string, provider: AuthProvider, lan
   if (provider === "external-token") {
     writeIfMissing(session, path.join(clientDir, "token-adapter.ts"), generateExternalTokenAdapter());
     writeIfMissing(session, path.join(clientDir, "authenticated-fetch.ts"), generateAuthenticatedFetch().replace("'./external-token-adapter'", "'./token-adapter'"));
-    writeIfMissing(session, path.join(clientDir, "auth-context.tsx"), generateExternalTokenAuthContext().replace(/external-token-adapter/g, "token-adapter"));
+    const source = generateExternalTokenAuthContext().replace(/external-token-adapter/g, "token-adapter");
+    writeIfMissing(session, path.join(clientDir, "auth-context.tsx"), getFrontendFramework() === "react" ? adaptReactPage(source) : source);
   } else if (provider === "swa") {
     writeIfMissing(session, path.join(clientDir, "auth-context.tsx"), generateSwaAuthContext(allowedProviders));
   } else if (provider === "custom-jwt") {
-    writeIfMissing(session, path.join(clientDir, "auth-context.tsx"), generateAuthContext());
+    writeIfMissing(session, path.join(clientDir, "auth-context.tsx"), getFrontendFramework() === "react" ? adaptReactPage(generateAuthContext()) : generateAuthContext());
+  }
+  if (getFrontendFramework() === "react") {
+    const existing = getValidatedFullConfig().auth;
+    writeCallFunction(cwd, session, "", {
+      ...existing, schemes: { ...existing?.schemes, [scheme]: { provider } },
+    });
+    return;
   }
   const callFunctionPath = path.join(cwd, "lib", "api", "call-function.ts");
   if (!session.fileExists(callFunctionPath)) writeIfMissing(session, callFunctionPath, generateBFFCallFunctionWithMultipleAuth());
@@ -667,6 +707,10 @@ function generateFunctionsAuth(
 }
 
 function generateBFFAuth(cwd: string, projectName: string, sharedPackageName: string, session: FileOperationSession): void {
+  if (getFrontendFramework() === "react") {
+    writeManagedAuthRoute(cwd, session, true);
+    return;
+  }
   const authApiDir = path.join(cwd, "app", "api", "auth");
 
   // Login route

package/src/cli/commands/dev.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { spawn, ChildProcess } from 'child_process';
+import { spawn, spawnSync, ChildProcess } from 'child_process';
 import * as http from 'http';
 import * as https from 'https';
 import * as path from 'path';
@@ -7,7 +7,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as net from 'net';
 import { CosmosClient, PartitionKeyKind } from '@azure/cosmos';
-import { ensureSwallowKitProject, getBackendLanguage, getAuthConfig, normalizeAuthConfig } from '../../core/config';
+import { ensureSwallowKitProject, getBackendLanguage, getFrontendFramework, getAuthConfig, normalizeAuthConfig } from '../../core/config';
 import { ModelInfo } from '../../core/scaffold/model-parser';
 import {
   applyDevSeedEnvironment,
@@ -32,6 +32,7 @@ import { ConnectorMockServer } from '../../core/mock/connector-mock-server';
 export interface DevOptions {
   port?: string;
   functionsPort?: string;
+  bffPort?: string;
   host?: string;
   open?: boolean;
   verbose?: boolean;
@@ -125,7 +126,7 @@ export function buildFunctionsBaseUrl(host: string | undefined, functionsPort: s
   return `http://${host || 'localhost'}:${functionsPort}`;
 }
 
-export function buildSwaStartArgs(host: string | undefined, nextPort: string, swaPort: string): string[] {
+export function buildSwaStartArgs(host: string | undefined, nextPort: string, swaPort: string, bffPort?: string): string[] {
   return [
     'start',
     `http://${host || 'localhost'}:${nextPort}`,
@@ -133,9 +134,15 @@ export function buildSwaStartArgs(host: string | undefined, nextPort: string, sw
     '.',
     '--port',
     swaPort,
+    ...(bffPort ? ['--api-devserver-url', buildFunctionsBaseUrl(host, bffPort)] : []),
   ];
 }
 
+export function buildReactDevArgs(pm: string, port: string, host = 'localhost'): string[] {
+  const args = ['vite', '--port', port, '--host', host, '--strictPort'];
+  return pm === 'pnpm' ? ['exec', ...args] : args;
+}
+
 export function getSwaCliInstallCommand(pm: string): string {
   return pm === 'pnpm'
     ? 'pnpm add -Dw @azure/static-web-apps-cli'
@@ -522,23 +529,48 @@ async function checkCosmosDBEmulator(): Promise<boolean> {
   });
 }
 
+export async function assertDevPortAvailable(port: number, host: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const server = net.createServer();
+    server.once('error', error => reject(new Error(`Development port ${port} on ${host} is unavailable: ${error.message}`)));
+    server.listen({ port, host, exclusive: true }, () => server.close(error => error ? reject(error) : resolve()));
+  });
+}
+
+function stopDevProcesses(processes: ChildProcess[]): void {
+  const active = processes.filter(child => child.pid && !child.killed);
+  if (process.platform === 'win32' && active.length) {
+    // Windows shell termination alone leaves Vite, Core Tools, and SWA running.
+    const ids = active.map(child => child.pid).join(',');
+    const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+      `$all = @(Get-CimInstance Win32_Process); function Stop-OwnedTree([int]$id) { foreach ($child in ($all | Where-Object ParentProcessId -eq $id)) { Stop-OwnedTree $child.ProcessId }; Stop-Process -Id $id -Force -ErrorAction SilentlyContinue }; foreach ($id in @(${ids})) { Stop-OwnedTree $id }`,
+    ], { windowsHide: true, encoding: 'utf8' });
+    if (result.error || result.status !== 0) {
+      console.error('❌ Could not stop all development subprocesses:', result.error?.message || result.stderr);
+    }
+  } else {
+    for (const child of active) child.kill();
+  }
+}
+
 export function buildDevCommand(
   runDevEnvironment: (options: DevOptions) => Promise<void> = startDevEnvironment,
   verifyProject: (commandName: string, projectRoot?: string) => void = ensureSwallowKitProject
 ): Command {
   return new Command()
     .name('dev')
-    .description('Start SwallowKit development server (Cosmos DB + Next.js + Azure Functions)')
-    .option('-p, --port <port>', 'Next.js port', '3000')
+    .description('Start SwallowKit frontend, BFF, and standalone Azure Functions')
+    .option('-p, --port <port>', 'Frontend dev server port', '3000')
     .option('-f, --functions-port <port>', 'Azure Functions port', '7071')
+    .option('--bff-port <port>', 'React managed BFF Functions port', '7073')
     .option('--host <host>', 'Host name', 'localhost')
     .option('--open', 'Open browser automatically', false)
     .option('--verbose', 'Show verbose logs', false)
     .option('--no-functions', 'Skip Azure Functions startup')
     .option('--seed-env <environment>', 'Replace Cosmos DB Emulator data from dev-seeds/<environment> before startup')
     .option('--mock-connectors', 'Start mock server for connector models (serves Zod-generated data)', false)
-    .option('--swa-port <port>', 'SWA authentication emulator port', '4280')
-    .option('--no-swa', 'Skip the SWA authentication emulator')
+    .option('--swa-port <port>', 'SWA routing/authentication emulator port', '4280')
+    .option('--no-swa', 'Skip SWA routing/authentication emulation (React direct access has no same-origin API)')
     .action(async (options: ParsedDevActionOptions) => {
       const normalizedOptions = normalizeParsedDevOptions(options);
 
@@ -656,19 +688,24 @@ async function startDevEnvironment(options: DevOptions) {
   const port = options.port || '3000';
   const functionsPort = options.functionsPort || '7071';
   const swaPort = options.swaPort || '4280';
+  const bffPort = options.bffPort || '7073';
   
   // Detect package manager from project lockfile
   const pm = detectFromProject();
   const pmCmd = getCommands(pm);
   const backendLanguage = getBackendLanguage();
+  const react = getFrontendFramework() === 'react';
+  const frontendLabel = react ? 'React/Vite' : 'Next.js';
   const authConfig = getAuthConfig();
   const normalizedAuth = normalizeAuthConfig(authConfig);
-  const useSwaEmulator = Boolean(normalizedAuth && Object.values(normalizedAuth.schemes).some(scheme => scheme.provider === 'swa')) && !options.noSwa;
+  const authSchemes = Object.values(normalizedAuth?.schemes ?? {});
+  const swaScheme = authSchemes.find(scheme => scheme.provider === 'swa');
+  const useSwaEmulator = (react || Boolean(swaScheme)) && !options.noSwa;
   const swaCommand = useSwaEmulator ? await resolveSwaCliCommand(process.cwd()) : null;
 
   if (useSwaEmulator && !swaCommand) {
     const installCommand = getSwaCliInstallCommand(pm);
-    console.error('❌ SWA authentication requires Azure Static Web Apps CLI for local development.');
+    console.error('❌ SWA routing/authentication requires Azure Static Web Apps CLI for local development.');
     console.error('   Install it in this project and retry:');
     console.error(`\n   ${installCommand}\n`);
     process.exitCode = 1;
@@ -707,15 +744,22 @@ async function startDevEnvironment(options: DevOptions) {
     if (mockServer) {
       await mockServer.stop();
     }
-    processes.forEach((proc) => {
-      if (proc && !proc.killed) {
-        proc.kill();
-      }
-    });
+    stopDevProcesses(processes);
     process.exit(0);
   });
 
   try {
+    if (react) {
+      const ports = [port, bffPort, ...(!options.noFunctions ? [functionsPort] : []), ...(useSwaEmulator ? [swaPort] : []), ...(options.mockConnectors ? [String(Number(functionsPort) + 1)] : [])];
+      if (ports.some(value => !/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 65535) || new Set(ports).size !== ports.length) {
+        throw new Error('Frontend, BFF, standalone Functions, mock, and SWA ports must be valid and distinct');
+      }
+      for (const value of ports) await assertDevPortAvailable(Number(value), options.host || 'localhost');
+      const coreToolsVersion = await resolveInstalledCoreToolsVersion();
+      if (!coreToolsVersion || compareVersionNumbers(coreToolsVersion, '4.0.0') < 0) {
+        throw new Error('React BFF requires Azure Functions Core Tools v4. Install it explicitly before running dev.');
+      }
+    }
     // 1. Check for Next.js project
     const packageJsonPath = path.join(process.cwd(), 'package.json');
     const nextConfigPathJs = path.join(process.cwd(), 'next.config.js');
@@ -724,11 +768,11 @@ async function startDevEnvironment(options: DevOptions) {
     
     if (!fs.existsSync(packageJsonPath)) {
       console.log('❌ package.json not found.');
-      console.log('💡 Please run this command in the root directory of a Next.js project.');
+      console.log('💡 Please run this command in the root directory of a SwallowKit project.');
       process.exit(1);
     }
 
-    if (!fs.existsSync(nextConfigPathJs) && !fs.existsSync(nextConfigPathTs) && !fs.existsSync(nextConfigPathMjs)) {
+    if (!react && !fs.existsSync(nextConfigPathJs) && !fs.existsSync(nextConfigPathTs) && !fs.existsSync(nextConfigPathMjs)) {
       console.log('⚠️  next.config file not found. Is this a Next.js project?');
     }
 
@@ -963,14 +1007,14 @@ async function startDevEnvironment(options: DevOptions) {
       );
     } else if (!hasFunctions) {
       console.log('');
-      console.log('ℹ️  functions/ directory not found. Starting Next.js only.');
+      console.log(`ℹ️  functions/ directory not found. Starting ${frontendLabel}${react ? ' and managed BFF' : ''} only.`);
     } else if (options.noFunctions) {
       console.log('');
       console.log('ℹ️  --no-functions specified. Skipping Azure Functions.');
     }
 
     console.log('');
-    console.log('🚀 Starting Next.js development server...');
+    console.log(`🚀 Starting ${frontendLabel} development server...`);
 
     // Mock connector server — start proxy if --mock-connectors is enabled
     let bffTargetPort = functionsPort;
@@ -1039,7 +1083,7 @@ async function startDevEnvironment(options: DevOptions) {
     }
 
     // 5. Start Next.js development server
-    const nextArgs = buildNextDevArgs(pm, port);
+    const nextArgs = react ? buildReactDevArgs(pm, port, options.host) : buildNextDevArgs(pm, port);
     
     // Ensure .env.local points to bffTargetPort so Next.js reads the correct backend URL.
     // When --mock-connectors is active, bffTargetPort = mock port (7072); otherwise = Functions port (7071).
@@ -1067,6 +1111,25 @@ async function startDevEnvironment(options: DevOptions) {
       FUNCTIONS_BASE_URL: bffTargetUrl,
     };
 
+    if (react) {
+      await runCommand(pm, ['run', 'build'], path.join(process.cwd(), 'shared'), 'Shared schema build');
+      const bffDir = path.join(process.cwd(), 'bff');
+      await runCommand(pm, ['run', 'build'], bffDir, 'Managed BFF build');
+      const bffProcess = spawn('func', buildFunctionsStartArgs(bffPort), {
+        cwd: bffDir, shell: true, stdio: 'inherit', env: nextEnv,
+      });
+      processes.push(bffProcess);
+      bffProcess.on('error', error => console.error('❌ Managed BFF startup error:', error.message));
+      bffProcess.on('close', code => {
+        console.error(`⏹️ Managed BFF exited (exit code: ${code})`);
+        stopDevProcesses(processes);
+        process.exit(code || 1);
+      });
+      if (!await waitForHttpServerReady(buildFunctionsBaseUrl(options.host, bffPort))) {
+        throw new Error(`Managed BFF did not become ready on port ${bffPort}`);
+      }
+    }
+
     const nextProcess = spawn(pm === 'pnpm' ? 'pnpm' : 'npx', nextArgs, {
       cwd: process.cwd(),
       shell: true,
@@ -1077,23 +1140,19 @@ async function startDevEnvironment(options: DevOptions) {
     processes.push(nextProcess);
 
     nextProcess.on('error', (error) => {
-      console.error('❌ Next.js startup error:', error.message);
+      console.error(`❌ ${frontendLabel} startup error:`, error.message);
       process.exit(1);
     });
 
     nextProcess.on('close', (code) => {
       if (code !== 0) {
-        console.log(`\n⏹️  Next.js exited (exit code: ${code})`);
+        console.log(`\n⏹️  ${frontendLabel} exited (exit code: ${code})`);
       }
-      // Exit all processes when Next.js exits
+      // Exit all owned processes when the frontend exits.
       if (mockServer) {
         mockServer.stop().catch(() => {});
       }
-      processes.forEach((proc) => {
-        if (proc && !proc.killed) {
-          proc.kill();
-        }
-      });
+      stopDevProcesses(processes);
       process.exit(code || 0);
     });
 
@@ -1110,14 +1169,14 @@ async function startDevEnvironment(options: DevOptions) {
     let swaReady = false;
     if (useSwaEmulator && swaCommand) {
       const nextUrl = `http://${options.host || 'localhost'}:${port}`;
-      console.log(`⏳ Waiting for Next.js before starting the SWA emulator at ${nextUrl}...`);
+      console.log(`⏳ Waiting for ${frontendLabel} before starting the SWA emulator at ${nextUrl}...`);
       const nextReady = await waitForHttpServerReady(nextUrl);
       if (!nextReady) {
-        throw new Error(`Next.js did not become ready at ${nextUrl}`);
+        throw new Error(`${frontendLabel} did not become ready at ${nextUrl}`);
       }
 
-      console.log(`🔐 Starting SWA authentication emulator (port: ${swaPort})...`);
-      const swaProcess = spawn(swaCommand, buildSwaStartArgs(options.host, port, swaPort), {
+      console.log(`🔐 Starting SWA routing/authentication emulator (port: ${swaPort})...`);
+      const swaProcess = spawn(swaCommand, buildSwaStartArgs(options.host, port, swaPort, react ? bffPort : undefined), {
         cwd: process.cwd(),
         shell: true,
         stdio: 'inherit',
@@ -1131,7 +1190,7 @@ async function startDevEnvironment(options: DevOptions) {
       const swaUrl = `http://${options.host || 'localhost'}:${swaPort}`;
       swaReady = await waitForHttpServerReady(swaUrl);
       if (!swaReady) {
-        throw new Error(`SWA authentication emulator did not become ready at ${swaUrl}`);
+        throw new Error(`SWA routing/authentication emulator did not become ready at ${swaUrl}`);
       }
     }
 
@@ -1140,18 +1199,25 @@ async function startDevEnvironment(options: DevOptions) {
     console.log('');
     if (useSwaEmulator) {
       const swaUrl = `http://${options.host || 'localhost'}:${swaPort}`;
-      console.log('🔐 SWA authenticated app:');
+      console.log('🔐 SWA app (same-origin frontend and BFF):');
       console.log(`   ${swaUrl}`);
       console.log('');
-      console.log('🔑 Local sign-in:');
-      console.log(`   ${swaUrl}/.auth/login/aad`);
-      console.log('   Enter any username and select Login.');
-      console.log('   The "authenticated" role is added automatically.');
-      console.log('');
-      console.log('📱 Next.js direct access (authentication is not emulated):');
+      if (swaScheme) {
+        const provider = swaScheme.swa?.allowedProviders?.[0] || 'aad';
+        console.log('🔑 Local SWA sign-in:');
+        console.log(`   ${swaUrl}/.auth/login/${provider}`);
+        console.log('   Enter any username and select Login.');
+        console.log('   The "authenticated" role is added automatically.');
+        console.log('');
+      }
+      if (authSchemes.some(scheme => scheme.provider === 'custom-jwt')) {
+        console.log(`🔑 Application sign-in: ${swaUrl}/login`);
+        console.log('');
+      }
+      console.log(`📱 ${frontendLabel} direct access (SWA routing/authentication is not emulated):`);
       console.log(`   http://${options.host || 'localhost'}:${port}`);
     } else {
-      console.log(`📱 Next.js: http://${options.host || 'localhost'}:${port}`);
+      console.log(`📱 ${frontendLabel}: http://${options.host || 'localhost'}:${port}`);
     }
     if (hasFunctions && !options.noFunctions) {
       console.log(`${functionsReady ? '⚡ Azure Functions' : '⏳ Azure Functions (starting)'}: ${functionsBaseUrl}`);
@@ -1161,7 +1227,7 @@ async function startDevEnvironment(options: DevOptions) {
     }
     console.log('');
     if (hasFunctions && !options.noFunctions && functionsReady) {
-      console.log('💡 Azure Functions and Next.js BFF are connected');
+      console.log(`💡 Azure Functions and ${react ? 'managed Functions' : 'Next.js'} BFF are connected`);
     } else if (hasFunctions && !options.noFunctions) {
       console.log('💡 Azure Functions is still warming up; BFF routes can fail until the backend responds.');
     }
@@ -1171,6 +1237,7 @@ async function startDevEnvironment(options: DevOptions) {
     if (swaReady) {
       console.log('💡 Open the app through the SWA port when testing authenticated pages and CRUD APIs.');
     }
+    if (react) console.log(`🔀 Managed BFF: ${buildFunctionsBaseUrl(options.host, bffPort)} (not the standalone Functions endpoint)`);
     console.log('');
 
     if (options.open) {
@@ -1189,11 +1256,7 @@ async function startDevEnvironment(options: DevOptions) {
 
   } catch (error) {
     console.error('❌ Failed to start development environment:', error instanceof Error ? error.message : error);
-    processes.forEach((proc) => {
-      if (proc && !proc.killed) {
-        proc.kill();
-      }
-    });
+    stopDevProcesses(processes);
     process.exit(1);
   }
 }