@swell/cli 2.9.17 → 2.9.19

package/README.md

@@ -1,3 +1,93 @@
 # @swell/cli 2 alpha
 
 Find the alpha docs at https://www.notion.so/swellcorp/CLI-reference-c3553ebb3de24d94becbedf95a5a25d8?pvs=4
+
+## Frontend scaffolding
+
+Run `swell create app` for interactive setup. The frontend picker groups templates
+by hosting mode. App creation without a frontend remains supported.
+
+| `--frontend` | Starter | Hosting |
+| --- | --- | --- |
+| `swell-react` | React + Vite, with server endpoints | Swell managed |
+| `swell-vinext` | Vinext, with server rendering and server components | Swell managed |
+| `swell-spa` | Client-only React storefront with commerce hooks and UI components | Swell managed; storefront apps only |
+| `nextjs`, `astro`, `nuxt`, `react`, `hono`, `angular` | Framework starter | Self-hosted; requires your own Cloudflare account |
+| `none` | No frontend | Default for `create app -y` |
+
+```sh
+swell create app my-app -t admin --frontend swell-react -y
+swell create app my-app -t admin --frontend swell-vinext -y
+swell create app my-store -t storefront --frontend swell-spa -p bun -y
+swell create app my-app -t admin --frontend astro -y
+```
+
+Managed starters come from
+[`swell-app-templates`](https://github.com/swellstores/swell-app-templates).
+Use Node.js 22.22.2 or newer and select a package manager with
+`--pkg npm|yarn|pnpm|bun`. pnpm must allow the `esbuild` and `workerd` install
+scripts. Hosting is recorded in `swell.json`; no developer Cloudflare account is
+needed for managed hosting.
+
+From the generated app directory, run `swell app frontend dev` for local
+development and `swell app push` to deploy through Swell. Managed hosting requires
+a compatible Swell platform deployment.
+The SPA starter includes commerce components but starts with an empty route tree;
+add storefront pages before expecting a visible storefront. SPA creation also
+creates the development app and storefront in your configured test store.
+
+To add a frontend to an existing app:
+
+```sh
+swell create frontend
+swell create frontend --frontend swell-react -y
+```
+
+`create frontend -y` requires an explicit template. Without `--pkg` it uses the
+package manager of the workspace lockfile, as `app frontend dev` and `app push`
+do. It preserves existing frontend files and does not provision remote
+storefront resources. `swell app init` only creates `swell.json`; use
+`create frontend` afterward to scaffold a frontend.
+
+Existing generic framework values retain self-hosted behavior. The former
+internal `react-storefront` value is accepted as a hidden alias for managed
+`swell-spa`; existing app deployments keep their configured hosting. The managed
+SPA has no supported self-hosted scaffold at this time.
+
+## Managed deployment failures
+
+If managed deployment fails, Swell retains the uploaded package and keeps the
+working frontend active. Correct any reported errors and repeat `swell app push`
+or `swell app frontend deploy`. These commands build and upload the frontend
+again; no separate retry command is needed.
+
+If another operation is updating the app, Swell returns 409 without waiting.
+Wait briefly and repeat the install, upgrade or deployment. An activation-write
+failure also returns 409; provider outages remain server errors. A merchant who
+cannot install an app because its frontend is invalid should contact the app
+developer.
+
+Managed frontend runtime logs are not available in this release. `swell logs`
+does not include managed frontend Worker console output or runtime exceptions.
+Use local frontend development logs to investigate application behavior and the
+deployment error returned by the CLI for build/upload failures. For deployment
+support, provide the app ID, selected version, store/environment, operation time
+and error code/message; do not include credentials or session cookies.
+
+## Frontend routes in development and deployment
+
+Swell owns `/api` and its existing platform endpoints on Swell-routed domains.
+Use native paths such as `/app-api/quote` for frontend handlers. Calls to
+`fetch('/api/products')` still reach Swell. The React and Vinext starters use
+`/app-api`; the SPA starter remains client-only.
+
+Development and deployment warn about conventional Next/Vinext App Router and
+Pages Router API handlers under `/api`, including `src/` layouts. This check
+does not analyze arbitrary Worker routing, rewrites, custom route extensions,
+or every platform endpoint. It does not move source files or change a base path.
+
+Existing handlers can use `/<app_private_id>/api/...` as a compatibility mount
+for the app selected by the domain. The prefix is removed before forwarding,
+with the query retained. A different app's prefix cannot select that app.
+Redirects, callback URLs and cookie paths may need explicit configuration for
+this mount. Storefront password protection still applies.

package/dist/commands/app/dev.js

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import getPort, { portNumbers } from 'get-port';
+import httpProxy from 'http-proxy';
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs/promises';
 import * as http from 'node:http';
@@ -148,29 +149,17 @@ export default class AppDev extends PushAppCommand {
         }
     }
     async createFunctionRouter(serverPort) {
+        const proxy = httpProxy.createProxyServer();
         const server = http.createServer((req, res) => {
             const url = new URL(req.url, `http://localhost:${serverPort}`);
             const functionName = url.pathname.slice(1); // Remove leading slash
+            const fail = (status, message) => {
+                if (!res.headersSent)
+                    res.writeHead(status);
+                res.end(message);
+            };
             if (this.functionPorts.has(functionName)) {
                 const targetPort = this.functionPorts.get(functionName);
-                // Proxy the request to the function server
-                const proxyReq = http.request({
-                    hostname: 'localhost',
-                    port: targetPort,
-                    path: req.url,
-                    method: req.method,
-                    headers: {
-                        ...req.headers,
-                        'Swell-Local-Dev': 'true',
-                    },
-                }, (proxyRes) => {
-                    res.writeHead(proxyRes.statusCode, proxyRes.headers);
-                    proxyRes.pipe(res);
-                });
-                proxyReq.on('error', (error) => {
-                    res.writeHead(500);
-                    res.end(`Error proxying to function ${functionName}: ${error.message}`);
-                });
                 // Log when response is finished, method, status, and time to execute by proxy
                 const startTime = Date.now();
                 res.on('finish', async () => {
@@ -181,25 +170,15 @@ export default class AppDev extends PushAppCommand {
                     });
                     this.log(`\n${style.appConfigValue(`→ ${functionName}`)} ${this.timestampStyled()} [${res.statusCode}] ${req.method} ${req.url} (${duration}ms)\n`);
                 });
-                req.pipe(proxyReq);
+                // Proxy the request to the function server
+                proxy.web(req, res, {
+                    target: `http://localhost:${targetPort}`,
+                    headers: { 'Swell-Local-Dev': 'true' },
+                }, (error) => fail(500, `Error proxying to function ${functionName}: ${error.message}`));
             }
             else if (this.frontendPort) {
                 // Proxy non-function requests to frontend dev server
-                const proxyReq = http.request({
-                    hostname: 'localhost',
-                    port: this.frontendPort,
-                    path: req.url,
-                    method: req.method,
-                    headers: req.headers,
-                }, (proxyRes) => {
-                    res.writeHead(proxyRes.statusCode, proxyRes.headers);
-                    proxyRes.pipe(res);
-                });
-                proxyReq.on('error', (error) => {
-                    res.writeHead(502);
-                    res.end(`Frontend dev server error: ${error.message}`);
-                });
-                req.pipe(proxyReq);
+                proxy.web(req, res, { target: `http://localhost:${this.frontendPort}` }, (error) => fail(502, `Frontend dev server error: ${error.message}`));
             }
             else {
                 res.writeHead(404);
@@ -212,6 +191,13 @@ export default class AppDev extends PushAppCommand {
                         : ''}`);
             }
         });
+        server.on('upgrade', (req, socket, head) => {
+            if (!this.frontendPort) {
+                socket.destroy();
+                return;
+            }
+            proxy.ws(req, socket, head, { target: `http://localhost:${this.frontendPort}` }, () => socket.destroy());
+        });
         await new Promise((resolve, reject) => {
             server.once('error', reject);
             server.listen(serverPort, () => {
@@ -219,6 +205,7 @@ export default class AppDev extends PushAppCommand {
                 resolve();
             });
         });
+        return server;
     }
     emitLifecycleEvent(type, data) {
         if (!this.jsonEvents)

package/dist/commands/app/frontend/deploy.js

@@ -2,9 +2,9 @@ import { Flags } from '@oclif/core';
 import { PushAppCommand } from '../../../push-app-command.js';
 export default class AppFrontendDeploy extends PushAppCommand {
     static description = `Creates a new build using the relevant command depending on your frontend framework.
-Once the build succeeds, this command will invoke Cloudflare Wrangler to upload
-build assets using your own Cloudflare account. Once complete, Swell will update
-the app's deployment URL and push the updated frontend files.`;
+Managed frontends are uploaded to Swell and deployed using Swell's Cloudflare account.
+Self-hosted frontends deploy through Wrangler using your own Cloudflare account.
+If deployment fails, correct any reported errors and run this command again.`;
     static examples = [
         'swell app frontend deploy',
         'swell app frontend deploy --force',

package/dist/commands/app/frontend/dev.js

@@ -1,4 +1,5 @@
 import { Flags } from '@oclif/core';
+import { warnFrontendRouteCollisions } from '../../../lib/apps/frontend-routes.js';
 import { CUSTOM_FRAMEWORK_SLUG, getManualDevHint, getProjectCommands, } from '../../../lib/apps/index.js';
 import { PushAppCommand } from '../../../push-app-command.js';
 import AppDev from '../dev.js';
@@ -76,6 +77,7 @@ export default class AppFrontendDev extends PushAppCommand {
         if (!projectType) {
             return;
         }
+        await warnFrontendRouteCollisions(this.appPath, projectType.slug, (message) => this.warn(message));
         // Manual mode for unrecognized frameworks
         if (projectType.slug === CUSTOM_FRAMEWORK_SLUG) {
             const hintCommand = await getManualDevHint(this.appPath, serverPort);
@@ -189,9 +191,10 @@ export default class AppFrontendDev extends PushAppCommand {
                     break;
                 }
                 case 'react':
-                case 'react-storefront': {
+                case 'react-storefront':
+                case 'vinext': {
                     // Vite emits the Local URL as its ready signal — no separate
-                    // detector needed.
+                    // detector needed. Vinext dev delegates URL printing to Vite.
                     if (/➜\s+local:\s+http:\/\//i.test(string) ||
                         /➜\s+network:/i.test(string)) {
                         if (!serverReadyDetected) {

package/dist/commands/app/init.js

@@ -1,4 +1,4 @@
-import { Args } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
 import path from 'node:path';
 import CreateApp, { appHelpMetaBase } from '../create/app.js';
 export default class InitApp extends CreateApp {
@@ -16,22 +16,32 @@ export default class InitApp extends CreateApp {
         '$ swell app init my-app',
         '$ swell app init -t admin -y',
         '$ swell app init my-app -t admin -y',
-        '$ swell app init my-app -t admin --frontend astro -y',
         '$ swell app init my_theme -t theme --storefront-app proxima -y',
     ];
     static helpMeta = {
         ...appHelpMetaBase,
+        typeSection: {
+            ...appHelpMetaBase.typeSection,
+            types: appHelpMetaBase.typeSection.types.map((type) => ({
+                ...type,
+                optional: [],
+            })),
+        },
         usageDirect: '[id] -t <type> [...] -y',
     };
     // Inherit all flags from CreateApp (includes -p, -t, -n, -v, -d)
     // baseFlags from CreateAppCommand (-y, --frontend, etc.) are merged automatically by oclif
     static flags = {
         ...CreateApp.flags,
+        frontend: Flags.string({ hidden: true }),
     };
     async run() {
         const { args, flags } = await this.parse(InitApp);
         const { id: argId } = args;
         const { yes: confirmYes, type, name, version, description, frontend, } = flags;
+        if (frontend !== undefined) {
+            this.error('app init only creates swell.json. Run swell create frontend --frontend <template> afterward.');
+        }
         // Use provided id argument, or fall back to current directory name
         const id = argId || process.cwd().split(path.sep).pop() || 'Swell App';
         await this.createSwellConfig({

package/dist/commands/create/app.d.ts

@@ -1,3 +1,4 @@
+import type { FrontendTemplate } from '../../lib/apps/frontend-templates.js';
 import { CreateAppCommand } from '../../create-app-command.js';
 import { HelpMeta } from '../../help/types.js';
 /**
@@ -16,7 +17,7 @@ export default class CreateApp extends CreateAppCommand {
     appType: string;
     private jsonOutput;
     log(message?: string, ...args: any[]): void;
-    createSwellConfig({ allowOverwrite, inputId, inputStorefrontApp, inputType, inputName, inputVersion, inputDescription, inputFrontend, inputIntegrationType, inputIntegrationId, inputYes, nestedPath, }: {
+    createSwellConfig({ allowOverwrite, inputId, inputStorefrontApp, inputType, inputName, inputVersion, inputDescription, inputFrontend, inputIntegrationType, inputIntegrationId, inputYes, nestedPath, scaffoldFrontend, }: {
         allowOverwrite?: boolean;
         inputDescription?: string;
         inputFrontend?: string;
@@ -29,11 +30,15 @@ export default class CreateApp extends CreateAppCommand {
         inputVersion?: string;
         inputYes?: boolean;
         nestedPath?: boolean;
+        scaffoldFrontend?: boolean;
     }): Promise<{
         appId: string;
         config: import("conf").default<Record<string, unknown>>;
         installedStorefrontApp: any;
         swellConfigJson: {
+            frontend?: {
+                hosting: "managed" | "self-hosted";
+            } | undefined;
             extensions?: any[] | undefined;
             theme: {
                 storefront: {
@@ -46,6 +51,9 @@ export default class CreateApp extends CreateAppCommand {
             type: string;
             version: string;
         } | {
+            frontend?: {
+                hosting: "managed" | "self-hosted";
+            } | undefined;
             extensions?: any[] | undefined;
             permissions: never[];
             description: string;
@@ -54,6 +62,7 @@ export default class CreateApp extends CreateAppCommand {
             type: string;
             version: string;
         };
+        template: FrontendTemplate | undefined;
     } | undefined>;
     run(): Promise<void>;
 }

package/dist/commands/create/app.js

@@ -5,6 +5,7 @@ import ora from 'ora';
 import { CreateAppCommand } from '../../create-app-command.js';
 import { newConfig, swellConfigFileExists } from '../../lib/app-config.js';
 import { buildCreateAppResult } from '../../lib/apps/create-app-result.js';
+import { setupPackage } from '../../lib/apps/frontend-scaffold.js';
 import { toAppId, toAppName } from '../../lib/create/index.js';
 import style from '../../lib/style.js';
 /**
@@ -33,6 +34,7 @@ export const appHelpMetaBase = {
             {
                 name: 'integration',
                 description: 'Third-party service',
+                optional: ['--frontend'],
                 requires: [
                     '--integration-type',
                     '--integration-id (for payment | shipping | tax)',
@@ -58,16 +60,25 @@ export default class CreateApp extends CreateAppCommand {
     static examples = [
         '$ swell create app',
         '$ swell create app my_app -t admin -y',
-        '$ swell create app my_app -t admin --frontend astro -y',
+        '$ swell create app my_app -t admin --frontend swell-react -y',
+        '$ swell create app my_shop -t storefront --frontend swell-spa -y',
         '$ swell create app my_theme -t theme --storefront-app proxima -y',
         '$ swell create app my_payment -t integration --integration-type payment --integration-id card -y',
-        '$ swell create app my_shipping -t integration --integration-type shipping --integration-id fedex -y',
     ];
     static helpMeta = {
         ...appHelpMetaBase,
+        frontendTemplates: 'optional',
         usageDirect: '<id> -t <type> [...] -y',
     };
     static flags = {
+        'storefront-app': Flags.string({ description: 'Target storefront app ID' }),
+        'integration-type': Flags.string({
+            description: 'Integration: generic | payment | shipping | tax',
+            options: ['generic', 'payment', 'shipping', 'tax'],
+        }),
+        'integration-id': Flags.string({
+            description: 'Service ID (e.g., card, fedex)',
+        }),
         pkg: Flags.string({
             char: 'p',
             default: 'npm',
@@ -101,7 +112,7 @@ export default class CreateApp extends CreateAppCommand {
         if (!this.jsonOutput)
             super.log(message, ...args);
     }
-    async createSwellConfig({ allowOverwrite = true, inputId = '', inputStorefrontApp, inputType, inputName, inputVersion, inputDescription, inputFrontend, inputIntegrationType, inputIntegrationId, inputYes, nestedPath = true, }) {
+    async createSwellConfig({ allowOverwrite = true, inputId = '', inputStorefrontApp, inputType, inputName, inputVersion, inputDescription, inputFrontend, inputIntegrationType, inputIntegrationId, inputYes, nestedPath = true, scaffoldFrontend = false, }) {
         const confirmYes = inputYes;
         let appId = toAppId(inputId || '');
         let storefrontInstalledApps;
@@ -292,16 +303,15 @@ export default class CreateApp extends CreateAppCommand {
                 });
             }
         }
-        // check inputFrontend value
-        if (!installedStorefrontApp &&
-            confirmYes &&
-            inputFrontend &&
-            inputFrontend !== 'none') {
-            const projectType = this.getProjectType(inputFrontend);
-            if (!projectType) {
-                // error should be thrown from getProjectType
-                return;
-            }
+        let template;
+        if (scaffoldFrontend && type !== 'theme') {
+            template = await this.selectFrontend(type, {
+                frontend: inputFrontend,
+                yes: confirmYes,
+            });
+        }
+        else if (inputFrontend && inputFrontend !== 'none') {
+            this.error('A theme cannot have a frontend.');
         }
         const swellConfigJson = {
             description,
@@ -321,6 +331,7 @@ export default class CreateApp extends CreateAppCommand {
                     permissions: [],
                 }),
             ...(extensions && { extensions }),
+            ...(template && { frontend: { hosting: template.hosting } }),
         };
         const appPath = nestedPath
             ? path.join(process.cwd(), inputId || appId)
@@ -345,6 +356,12 @@ export default class CreateApp extends CreateAppCommand {
         }
         this.log(`\nCreating ${this.appType === 'theme' ? 'theme' : 'app'} ${style.appConfigValue(name)} in ${appPath}/swell.json`);
         this.log(`\n${JSON.stringify(swellConfigJson, null, 2)}\n`);
+        if (template) {
+            this.log(`Frontend: ${template.name} (${template.hosting})`);
+            if (template.provisionsStorefront) {
+                this.log('A development app and storefront will also be created in your test store.');
+            }
+        }
         const confirmCreateApp = confirmYes
             ? true
             : await confirm({
@@ -356,7 +373,13 @@ export default class CreateApp extends CreateAppCommand {
         const config = newConfig(nestedPath ? inputId || appId : '');
         config.clear();
         config.set(swellConfigJson);
-        return { appId, config, installedStorefrontApp, swellConfigJson };
+        return {
+            appId,
+            config,
+            installedStorefrontApp,
+            swellConfigJson,
+            template,
+        };
     }
     async run() {
         const { args, flags } = await this.parse(CreateApp);
@@ -375,16 +398,17 @@ export default class CreateApp extends CreateAppCommand {
             inputFrontend: frontend,
             inputIntegrationType: flags['integration-type'],
             inputIntegrationId: flags['integration-id'],
+            scaffoldFrontend: true,
         });
         if (!createParams) {
             return;
         }
-        const { appId, config, installedStorefrontApp, swellConfigJson } = createParams;
+        const { appId, config, installedStorefrontApp, swellConfigJson, template } = createParams;
         !confirmYes && this.log();
         const spinner = ora();
         spinner.start('Creating app...');
         if (pkg !== 'none') {
-            await this.tryPackageSetup(appId, config, pkg);
+            await setupPackage(appId, config, pkg);
         }
         await this.createAppConfigFolders(config);
         spinner.succeed(`${style.appConfigValue(config.get('name'))} app created.\n`);
@@ -394,15 +418,11 @@ export default class CreateApp extends CreateAppCommand {
         if (installedStorefrontApp) {
             createdTheme = await this.createThemeApp(config, flags, installedStorefrontApp);
         }
-        else if (config.get('type') === 'storefront') {
-            const storefrontResult = await this.createStorefrontApp(config, flags, {
-                provisionResources: true,
+        else if (template) {
+            frontendResult = await this.createFrontend(config, template, pkg, {
+                provisionResources: config.get('type') === 'storefront',
             });
-            frontendResult = storefrontResult;
-            resources = storefrontResult.resources;
-        }
-        else {
-            frontendResult = await this.createFrontendApp(config, flags);
+            resources = frontendResult.resources;
         }
         if (json) {
             super.log(JSON.stringify(buildCreateAppResult({
@@ -410,7 +430,10 @@ export default class CreateApp extends CreateAppCommand {
                 resources,
                 name: swellConfigJson.name,
                 type: swellConfigJson.type,
-                frontend: frontendResult?.framework ?? null,
+                // Echo the requested value, including the hidden alias.
+                frontend: frontendResult
+                    ? frontend || frontendResult.template
+                    : null,
                 path: path.dirname(config.path),
             })));
             return;

package/dist/commands/create/frontend.d.ts

@@ -1,3 +1,4 @@
+import type { HelpMeta } from '../../help/types.js';
 import { CreateAppCommand } from '../../create-app-command.js';
 export default class CreateFrontend extends CreateAppCommand {
     static description: string;
@@ -5,8 +6,9 @@ export default class CreateFrontend extends CreateAppCommand {
         command: string;
         description: string;
     }[];
+    static helpMeta: HelpMeta;
     static flags: {
-        pkg: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        pkg: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     run(): Promise<void>;
 }

package/dist/commands/create/frontend.js

@@ -1,7 +1,8 @@
 import { Flags } from '@oclif/core';
-import ora from 'ora';
+import path from 'node:path';
 import { CreateAppCommand } from '../../create-app-command.js';
 import swellConfig from '../../lib/app-config.js';
+import { detectPackageManager } from '../../lib/package-manager.js';
 export default class CreateFrontend extends CreateAppCommand {
     static description = 'Initialize a frontend app framework and folder structure.';
     static examples = [
@@ -10,15 +11,22 @@ export default class CreateFrontend extends CreateAppCommand {
             description: 'Create frontend app following command prompts.',
         },
         {
-            command: 'swell create frontend -y',
-            description: 'Create frontend app and accept all default values.',
+            command: 'swell create frontend --frontend swell-react -y',
+            description: 'Add a React frontend hosted by Swell.',
+        },
+        {
+            command: 'swell create frontend --frontend astro -y',
+            description: 'Add a self-hosted Astro frontend.',
         },
     ];
+    static helpMeta = {
+        frontendTemplates: 'required',
+        usageDirect: '--frontend <template> [...] -y',
+    };
     static flags = {
         pkg: Flags.string({
             char: 'p',
-            default: 'npm',
-            description: 'Package manager: npm | yarn | pnpm | bun | none',
+            description: 'Package manager: npm | yarn | pnpm | bun | none (default: the workspace lockfile, else npm)',
             options: ['npm', 'yarn', 'pnpm', 'bun', 'none'],
         }),
     };
@@ -26,15 +34,15 @@ export default class CreateFrontend extends CreateAppCommand {
         const { flags } = await this.parse(CreateFrontend);
         const newSwellConfig = await swellConfig();
         const appType = newSwellConfig?.get('type');
-        const spinner = ora();
         if (appType === 'theme') {
-            spinner.fail("You can't create app frontend in a theme.");
-            return;
+            this.error("You can't create app frontend in a theme.");
+        }
+        const template = await this.selectFrontend(appType, flags, true);
+        if (template) {
+            // Match the manager that app dev and push will detect for this workspace.
+            const pkg = flags.pkg ??
+                (await detectPackageManager(path.dirname(newSwellConfig.path)));
+            await this.scaffoldFrontend(newSwellConfig, template, pkg, true);
         }
-        await (appType === 'storefront'
-            ? this.createStorefrontApp(newSwellConfig, flags, {
-                directCreate: true,
-            })
-            : this.createFrontendApp(newSwellConfig, flags, true));
     }
 }

package/dist/create-app-command.d.ts

@@ -1,71 +1,30 @@
+import { type FrontendTemplate } from './lib/apps/frontend-templates.js';
 import { type StorefrontResourceResult } from './lib/apps/storefront-resources.js';
-import { PackageManager } from './lib/package-manager.js';
 import { SwellCommand } from './swell-command.js';
 export interface FrontendCreationResult {
     created: boolean;
-    framework: string | null;
-    provisionsStorefront: boolean;
-}
-export interface StorefrontCreationResult extends FrontendCreationResult {
     resources?: StorefrontResourceResult;
+    /** Resolved template slug; the JSON result echoes the requested value. */
+    template: string;
 }
-export interface StorefrontCreationOptions {
-    directCreate?: boolean;
+export interface FrontendCreationOptions {
     provisionResources?: boolean;
 }
 export declare abstract class CreateAppCommand extends SwellCommand {
     protected commandExample: string;
     static baseFlags: {
         frontend: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        'storefront-app': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        'integration-type': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
-        'integration-id': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
     };
     private devApi;
     constructor(argv: string[], config: any);
-    addAllowedHostsToAngular(configPath: string): Promise<void>;
-    addAllowedHostsToAstro(configPath: string): Promise<void>;
-    addAllowedHostsToNuxt(configPath: string): Promise<void>;
-    /**
-     * For frameworks whose dev server is Vite directly. Astro/Nuxt nest the
-     * vite block inside their own defineConfig — see addViteAllowedHosts.
-     */
-    addAllowedHostsToVite(configPath: string): Promise<void>;
-    /**
-     * Add vite allowedHosts configuration to a framework config file.
-     * Supports config files that use a defineX({}) pattern (Astro, Nuxt, etc.)
-     */
-    private addViteAllowedHosts;
     createAppConfigFolders(swellConfig: any): Promise<void>;
-    createFrontendApp(swellConfig: any, flags: any, directCreate?: boolean, kind?: string): Promise<FrontendCreationResult>;
-    createStorefrontApp(swellConfig: any, flags: any, options?: StorefrontCreationOptions): Promise<StorefrontCreationResult>;
+    selectFrontend(appType: string, flags: any, direct?: boolean): Promise<FrontendTemplate | undefined>;
+    /** Scaffold the local frontend workspace without touching remote resources. */
+    scaffoldFrontend(swellConfig: any, template: FrontendTemplate, packageManager?: string, directCreate?: boolean): Promise<FrontendCreationResult>;
+    /** Scaffold the frontend and, when asked, its remote storefront resources. */
+    createFrontend(swellConfig: any, template: FrontendTemplate, packageManager: string | undefined, options?: FrontendCreationOptions): Promise<FrontendCreationResult>;
     createThemeApp(config: any, flags: any, installedStorefrontApp: any): Promise<boolean>;
-    doesPackageManagerExist(packageManager: string): Promise<boolean>;
-    execWithStdio(cwd: string, command: string, onOutput?: (string: string) => any | false): Promise<void>;
-    findPackageManager(pkg?: string): Promise<string | undefined>;
     getInstalledStorefrontApps(): Promise<any[] | boolean>;
-    getProjectType(frameworkType: string): {
-        installCommand: string;
-        appTypes?: string[] | undefined;
-        buildCommand?: string | undefined;
-        devCommand: string;
-        displayOrder?: number | undefined;
-        mainPackage: string;
-        name: string;
-        provisionsStorefront?: boolean | undefined;
-        slug: string;
-    };
-    setupPackage(name: string, config: any, pkg: PackageManager): Promise<void>;
-    tryPackageSetup(name: string, config: any, pkg: PackageManager): Promise<void>;
-    /**
-     * Fix wrangler.jsonc `main` field when it points to a build artifact that
-     * doesn't exist at dev time. The @cloudflare/vite-plugin validates this path
-     * at startup and crashes during `astro dev` if it can't resolve it.
-     *
-     * Only replaces the exact legacy value that C3 currently scaffolds.
-     * Once C3 updates its template, this becomes a no-op.
-     */
-    private fixAstroWranglerEntrypoint;
-    private addFrontendAllowedHosts;
+    resolveFrontendTemplate(value: string): FrontendTemplate;
 }