@swell/cli 2.9.26 → 2.9.28

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

@@ -39,5 +39,6 @@ export default class AppDev extends PushAppCommand {
     private logFunction;
     private onChangeFunctionWatcher;
     private startAppFunctionServer;
+    private logComponentModules;
     private startFunctionServers;
 }

package/dist/commands/app/dev.js

@@ -7,6 +7,7 @@ import * as http from 'node:http';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import ora from 'ora';
+import { COMPONENT_DEV_PATH, listRootComponentFiles, serveComponentModule, } from '../../lib/apps/components.js';
 import { ConfigType, allConfigFilesInDir, appConfigFromFile, } from '../../lib/apps/index.js';
 import { bundleFunction } from '../../lib/bundle.js';
 import { FUNCTION_COMPATIBILITY_DATE, getLocalFrontendHost, } from '../../lib/constants.js';
@@ -194,6 +195,10 @@ export default class AppDev extends PushAppCommand {
                     res.writeHead(status);
                 res.end(message);
             };
+            if (url.pathname.startsWith(COMPONENT_DEV_PATH)) {
+                serveComponentModule(this.appPath, url.pathname, res).catch((error) => fail(500, error.message));
+                return;
+            }
             if (this.functionPorts.has(functionName)) {
                 const targetPort = this.functionPorts.get(functionName);
                 // Log when response is finished, method, status, and time to execute by proxy
@@ -443,15 +448,26 @@ ENVIRONMENT = "development"
     async startAppFunctionServer(spinner, serverPort) {
         // Get all functions in this app
         const functions = await this.getAppFunctions();
+        const components = await listRootComponentFiles(this.appPath);
         const projectType = await this.getFrontendProjectType(false);
         const shouldLogPreviewUrl = this.app.type === 'storefront' && !projectType;
         if (functions.length === 0) {
-            if (!projectType && this.app.type !== 'storefront') {
+            if (!projectType &&
+                this.app.type !== 'storefront' &&
+                components.length === 0) {
                 spinner.stop();
-                this.log(`No functions or frontend detected. Exiting.\n`);
+                this.log(`No functions, components or frontend detected. Exiting.\n`);
                 await this.cleanupOnExit();
                 return;
             }
+            // Components are pushed again when they change; the tmp directory lets
+            // a function added while dev runs start like it does in the full mode
+            if (components.length > 0) {
+                await this.createTmpDirectory();
+                this.watchForChanges({
+                    onChange: this.onChangeFunctionWatcher.bind(this),
+                });
+            }
             // Create routing server to proxy requests to frontend even without functions
             await this.createFunctionRouter(serverPort);
             if (shouldLogPreviewUrl) {
@@ -461,6 +477,7 @@ ENVIRONMENT = "development"
             else {
                 spinner.stop();
             }
+            this.logComponentModules(components, serverPort);
             return;
         }
         // Create TMP directory for wrangler configs and bundled functions
@@ -480,6 +497,13 @@ ENVIRONMENT = "development"
         if (shouldLogPreviewUrl) {
             this.logLocalPreviewUrl();
         }
+        this.logComponentModules(components, serverPort);
+    }
+    logComponentModules(components, serverPort) {
+        if (components.length === 0) {
+            return;
+        }
+        this.log(`${style.success('→')} Component modules at: http://localhost:${serverPort}${COMPONENT_DEV_PATH}<Name>.js\n`);
     }
     async startFunctionServers(functions) {
         const functionStatus = new Map();

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

@@ -0,0 +1,22 @@
+import { CreateConfigCommand } from '../../create-config-command.js';
+import { HelpMeta } from '../../help/types.js';
+import { ConfigType } from '../../lib/apps/index.js';
+export default class CreateComponent extends CreateConfigCommand {
+    static args: {
+        name: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static helpMeta: HelpMeta;
+    static flags: {
+        description: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        extension: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        overwrite: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        target: 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>;
+    };
+    static summary: string;
+    createType: ConfigType;
+    private checkConfig;
+    run(): Promise<void>;
+}

package/dist/commands/create/component.js

@@ -0,0 +1,129 @@
+import { input } from '@inquirer/prompts';
+import { Args, Flags } from '@oclif/core';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { CreateConfigCommand } from '../../create-config-command.js';
+import { resolveComponentValues, } from '../../lib/apps/component-extension.js';
+import { listRootComponentFiles } from '../../lib/apps/components.js';
+import { ConfigType } from '../../lib/apps/index.js';
+import { getComponentTemplate, setupComponentSupport, toComponentName, } from '../../lib/create/component.js';
+import { readStaticConfig } from '../../lib/function-source-analysis.js';
+export default class CreateComponent extends CreateConfigCommand {
+    static args = {
+        name: Args.string({
+            default: '',
+            description: 'Component name (e.g., ColorPicker)',
+        }),
+    };
+    static description = 'Create an app component in the components folder.';
+    static examples = [
+        '$ swell create component',
+        '$ swell create component ColorPicker -d "Brand color picker" -y',
+        '$ swell create component MyComponent --extension <extension-id> --target <target-id> -y',
+    ];
+    static helpMeta = {
+        usageDirect: '<name> [-d <description>] [--extension <extension-id>] [--target <target-id>...] -y',
+    };
+    static flags = {
+        description: Flags.string({
+            char: 'd',
+            default: '',
+            description: 'Description',
+        }),
+        extension: Flags.string({
+            description: 'Extension id from swell.json: makes the component the UI of that extension',
+        }),
+        overwrite: Flags.boolean({
+            default: false,
+            description: 'Overwrite existing file',
+        }),
+        target: Flags.string({
+            description: 'Target id where the component renders; repeat for more targets',
+            multiple: true,
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Skip prompts, require all arguments',
+        }),
+    };
+    static summary = 'Create an app component in the components folder.';
+    createType = ConfigType.COMPONENT;
+    // The same rules as push, so a scaffold that would fail to push is refused here
+    async checkConfig(componentName, extension, targets) {
+        const configured = this.swellConfig.get('extensions');
+        const extensions = Array.isArray(configured)
+            ? configured
+            : [];
+        const files = await listRootComponentFiles(this.appPath);
+        const siblings = await Promise.all(files.map(async (file) => {
+            const source = await fs
+                .readFile(path.join(this.appPath, file), 'utf8')
+                .catch(() => '');
+            return {
+                config: readStaticConfig(source, file).config,
+                name: path.basename(file).replace(/\.[^.]+$/, ''),
+            };
+        }));
+        try {
+            resolveComponentValues(componentName, {
+                ...(extension && { extension: { id: extension } }),
+                ...(targets.length > 0 && { targets: targets.map((id) => ({ id })) }),
+            }, extensions, siblings);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 1 });
+        }
+    }
+    async run() {
+        const { args, flags } = await this.parse(CreateComponent);
+        const { description: descriptionFlag, extension, overwrite, target: targets = [], yes, } = flags;
+        let name = args.name;
+        let description = descriptionFlag;
+        if (yes) {
+            if (!name) {
+                this.error('Missing required argument for non-interactive mode: NAME\n\nExample: swell create component ColorPicker -y', { exit: 1 });
+            }
+        }
+        else {
+            if (!name) {
+                name = await input({
+                    default: 'MyComponent',
+                    message: 'Component name',
+                });
+            }
+            if (!description) {
+                description = await input({
+                    message: 'Describe what the component does',
+                });
+            }
+        }
+        const componentName = toComponentName(name);
+        if (!componentName) {
+            this.error(`Invalid component name: ${name}`, { exit: 1 });
+        }
+        if (extension || targets.length > 0) {
+            await this.checkConfig(componentName, extension, targets);
+        }
+        const created = await this.createFile({
+            extension: 'tsx',
+            fileBody: getComponentTemplate(componentName, description, {
+                extension,
+                targets,
+            }),
+            fileName: componentName,
+        }, overwrite, !yes);
+        if (!created) {
+            return;
+        }
+        const { changed, dependenciesAdded, warnings } = await setupComponentSupport(this.appPath);
+        if (changed.length > 0) {
+            const install = dependenciesAdded
+                ? ' Run `npm install` to install preact and @swell/apps-sdk.'
+                : '';
+            this.log(`Updated ${changed.join(', ')}.${install}`);
+        }
+        for (const warning of warnings) {
+            this.warn(warning);
+        }
+    }
+}

package/dist/commands/create/index.js

@@ -1,7 +1,7 @@
 import { select } from '@inquirer/prompts';
 import { Command } from '@oclif/core';
 export default class Create extends Command {
-    static description = 'Scaffold apps, models, functions, and notifications.';
+    static description = 'Scaffold apps, models, functions, components, and notifications.';
     static examples = ['<%= config.bin %> <%= command.id %>'];
     async run() {
         const createTarget = await select({
@@ -18,6 +18,10 @@ export default class Create extends Command {
                     name: 'Content',
                     value: 'content',
                 },
+                {
+                    name: 'Component',
+                    value: 'component',
+                },
                 {
                     name: 'Function',
                     value: 'function',

package/dist/commands/create/tests.js

@@ -4,7 +4,7 @@ import { toAppId } from '../../lib/create/index.js';
 import { createTestsScaffold, } from '../../lib/create/tests.js';
 import { detectPackageManager, getPackageManagerCommands, } from '../../lib/package-manager.js';
 export default class CreateTests extends AppCommand {
-    static description = 'Initialize a vitest + Cloudflare Workers test setup that reuses swell-cli authentication.';
+    static description = 'Initialize a vitest + Cloudflare Workers test setup for app functions.';
     static examples = [
         '$ swell create tests',
         '$ swell create tests --overwrite',
@@ -43,7 +43,9 @@ export default class CreateTests extends AppCommand {
         this.logScaffoldResult(result, pm);
     }
     logScaffoldResult(result, pm) {
-        const hasChanges = result.createdFiles.length > 0 || result.packageJsonUpdated;
+        const hasChanges = result.createdFiles.length > 0 ||
+            result.removedFiles.length > 0 ||
+            result.packageJsonUpdated;
         if (hasChanges) {
             this.log('');
             this.log('✓ Created test scaffolding');
@@ -62,6 +64,13 @@ export default class CreateTests extends AppCommand {
                 this.log(`  ${file}`);
             }
         }
+        if (result.removedFiles.length > 0) {
+            this.log('');
+            this.log('Removed (no longer part of the test setup):');
+            for (const file of result.removedFiles) {
+                this.log(`  ${file}`);
+            }
+        }
         if (result.packageJsonUpdated) {
             this.log('');
             this.log('Updated package.json with test scripts and devDependencies.');

package/dist/commands/inspect/extensions.js

@@ -6,7 +6,7 @@ import { resolveInspectScope, ScopeError, } from '../../lib/apps/inspect-scope.j
 import { HEX24, isObjectId } from '../../lib/apps/object-id.js';
 import { resolveAppId } from '../../lib/apps/resolve.js';
 import { default as localConfig } from '../../lib/config.js';
-import { buildExtensionDetail, buildOrphanDetail, componentMatchesExtension, diffManifestEntries, formatExtensionKey, functionMatchesExtension, listGroupForApp, listGroupForOrphans, listMetaFor, nextStepLines, orphanListMeta, parseExtensionKey, } from '../../lib/inspect/extensions.js';
+import { buildExtensionDetail, buildOrphanDetail, componentMatchesExtension, diffManifestEntries, formatExtensionKey, componentExtensionId, functionMatchesExtension, listGroupForApp, listGroupForOrphans, listMetaFor, nextStepLines, orphanListMeta, parseExtensionKey, } from '../../lib/inspect/extensions.js';
 import { renderKeyMetaTable } from '../../lib/inspect/table.js';
 import { SwellCommand } from '../../swell-command.js';
 export default class Extensions extends SwellCommand {
@@ -144,7 +144,7 @@ Identifier forms:
                 }
             }
             for (const comp of appComponents) {
-                const ext = comp.values?.extension;
+                const ext = componentExtensionId(comp.values);
                 if (!ext)
                     continue;
                 if (declaredIds.has(ext))
@@ -331,7 +331,7 @@ Identifier forms:
             // but no manifest entry declares it. Surface as the orphan envelope only
             // when we actually find handlers; otherwise it's a "not found" lookup.
             const orphanFns = allFunctions.filter((f) => f.extension === extId);
-            const orphanComps = allComponents.filter((c) => c.values?.extension === extId);
+            const orphanComps = allComponents.filter((c) => componentExtensionId(c.values) === extId);
             if (orphanFns.length === 0 && orphanComps.length === 0) {
                 this.error(`No extension '${extId}' declared by app '${appSlug}', and no handlers reference it. ` +
                     `List available: swell inspect extensions${scope.appSlug ? ` --app=${scope.appSlug}` : ''}`, { exit: 1 });

package/dist/lib/apps/app-config.d.ts

@@ -50,6 +50,12 @@ export declare abstract class AppConfig {
      * @returns {Promise<string | undefined>} the hash
      */
     protected contentHash(): Promise<string | undefined>;
+    /**
+     * File hash combined with the app files this file imports, for configs that
+     * deploy as a bundle: a change in shared code redeploys them
+     * @returns {Promise<string | undefined>} the hash, or undefined until the file compiles
+     */
+    protected bundleHash(): Promise<string | undefined>;
     /**
      * Full path of the app directory this config belongs to
      * @returns {string} the path
@@ -60,6 +66,11 @@ export declare abstract class AppConfig {
     postData(): Promise<any>;
     prepareFileData(): any;
     abstract hasValues: boolean;
+    /**
+     * Whether .json files are parsed into values; otherwise they are pushed as raw files
+     * @returns {boolean} true to parse
+     */
+    protected parsesJsonValues(): boolean;
     /** build the JSON used when making requests (usually push) to the API */
     protected abstract preparePostData(postData: any): Promise<any>;
     abstract type: ConfigType;
@@ -104,7 +115,11 @@ export declare class AppConfigFunction extends AppConfig {
 export declare class AppConfigComponent extends AppConfig {
     hasValues: boolean;
     type: ConfigType;
+    protected parsesJsonValues(): boolean;
     isRootComponent(): boolean;
+    protected contentHash(): Promise<string | undefined>;
+    private manifestExtensions;
+    private siblingComponents;
     preparePostData(postData: any): Promise<any>;
 }
 export declare class AppConfigAsset extends AppConfigDefault {

package/dist/lib/apps/app-config.js

@@ -3,9 +3,11 @@ import isEmpty from 'lodash/isEmpty.js';
 import { detectFilenameMime } from 'mime-detect';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { bundleFunction, bundleComponent, bundleWorkflow, getLocalInputs, } from '../bundle.js';
-import { analyzeFunctionSource, hasKindDiagnostic, workflowStaticConfigError, } from '../function-source-analysis.js';
-import { AllConfigPaths, ConfigType, filePathExistsAsync, hashFile, hashString, } from './index.js';
+import { bundleFunction, bundleComponent, bundleComponentModule, bundleWorkflow, getLocalInputs, } from '../bundle.js';
+import { analyzeFunctionSource, hasKindDiagnostic, readStaticConfig, workflowStaticConfigError, } from '../function-source-analysis.js';
+import { isLegacyComponent, resolveComponentValues, } from './component-extension.js';
+import { listRootComponentFiles } from './components.js';
+import { AllConfigPaths, ConfigType, filePathExistsAsync, getNameFromFilePath, hashFile, hashString, } from './index.js';
 export class IgnoringFileError extends Error {
     constructor(message) {
         super(message);
@@ -95,6 +97,30 @@ export class AppConfig {
     async contentHash() {
         return this.fileHash;
     }
+    /**
+     * File hash combined with the app files this file imports, for configs that
+     * deploy as a bundle: a change in shared code redeploys them
+     * @returns {Promise<string | undefined>} the hash, or undefined until the file compiles
+     */
+    async bundleHash() {
+        if (!this.fileHash) {
+            return this.fileHash;
+        }
+        const appRoot = this.appRoot();
+        let inputs;
+        try {
+            inputs = await getLocalInputs(this.appPath, appRoot);
+        }
+        catch {
+            // Unknown until it compiles: push tries it and reports the error
+            return undefined;
+        }
+        const imports = inputs
+            .filter((input) => input !== this.filePath)
+            .sort()
+            .map((input) => hashFile(path.join(appRoot, input), undefined, input));
+        return hashString(this.fileHash, ...imports);
+    }
     /**
      * Full path of the app directory this config belongs to
      * @returns {string} the path
@@ -166,7 +192,7 @@ export class AppConfig {
         if (this.fileData === undefined) {
             return;
         }
-        if (this.hasValues && this.filePath.endsWith('.json')) {
+        if (this.parsesJsonValues() && this.filePath.endsWith('.json')) {
             try {
                 this.values = JSON.parse(this.fileData.toString('utf8'));
             }
@@ -205,6 +231,13 @@ export class AppConfig {
             ? { $base64: this.fileData.toString('base64') }
             : this.fileData?.toString('utf8');
     }
+    /**
+     * Whether .json files are parsed into values; otherwise they are pushed as raw files
+     * @returns {boolean} true to parse
+     */
+    parsesJsonValues() {
+        return this.hasValues;
+    }
 }
 export class AppConfigDefault extends AppConfig {
     hasValues = false;
@@ -280,23 +313,7 @@ export class AppConfigFunction extends AppConfig {
     // A function deploys as a bundle, so the hash includes the local files it
     // imports: a change in shared code under functions/lib redeploys it
     async contentHash() {
-        if (!this.isRootFunction() || !this.fileHash) {
-            return this.fileHash;
-        }
-        const appRoot = this.appRoot();
-        let inputs;
-        try {
-            inputs = await getLocalInputs(this.appPath, appRoot);
-        }
-        catch {
-            // Unknown until it compiles: push tries it and reports the error
-            return undefined;
-        }
-        const imports = inputs
-            .filter((input) => input !== this.filePath)
-            .sort()
-            .map((input) => hashFile(path.join(appRoot, input), undefined, input));
-        return hashString(this.fileHash, ...imports);
+        return this.isRootFunction() ? this.bundleHash() : this.fileHash;
     }
     async preparePostData(postData) {
         if (this.isRootFunction()) {
@@ -352,10 +369,44 @@ export class AppConfigFunction extends AppConfig {
 export class AppConfigComponent extends AppConfig {
     hasValues = true;
     type = ConfigType.COMPONENT;
+    // Only .tsx/.jsx files are components, any .json under components/ is shared source
+    parsesJsonValues() {
+        return false;
+    }
     isRootComponent() {
         return (this.isRootConfig('components') &&
             (this.filePath.endsWith('.jsx') || this.filePath.endsWith('.tsx')));
     }
+    // A component deploys as a bundle, so the hash includes the local files it
+    // imports: a change in shared code under components/lib redeploys it
+    async contentHash() {
+        return this.isRootComponent() ? this.bundleHash() : this.fileHash;
+    }
+    // Read only for components that name an extension, so other apps never need a readable swell.json
+    async manifestExtensions() {
+        try {
+            const manifest = JSON.parse(await fs.readFile(path.join(this.appRoot(), 'swell.json'), 'utf8'));
+            return Array.isArray(manifest?.extensions) ? manifest.extensions : [];
+        }
+        catch (error) {
+            throw new Error(`cannot read swell.json: ${error.message}`);
+        }
+    }
+    // Siblings whose config cannot be read are skipped: their own push reports them
+    async siblingComponents() {
+        const appRoot = this.appRoot();
+        const files = await listRootComponentFiles(appRoot);
+        return Promise.all(files
+            .filter((file) => file !== this.filePath)
+            .map(async (file) => {
+            const source = await fs
+                .readFile(path.join(appRoot, file), 'utf8')
+                // A sibling that vanished or was renamed reads as empty and is skipped
+                .catch(() => '');
+            const { config } = readStaticConfig(source, file);
+            return { name: getNameFromFilePath(file), config };
+        }));
+    }
     async preparePostData(postData) {
         if (!this.isRootComponent()) {
             return postData;
@@ -366,19 +417,37 @@ export class AppConfigComponent extends AppConfig {
             if (!fileData) {
                 return;
             }
-            const { code, config } = await bundleComponent(this.filePath);
-            if (!config) {
-                throw new IgnoringFileError('Component must export a `config` object.');
+            const source = this.fileData?.toString('utf8') ?? '';
+            const { config, errors } = readStaticConfig(source, this.filePath);
+            if (errors.length > 0) {
+                throw new Error(`config must be static metadata: ${errors.join('; ')}`);
+            }
+            const name = getNameFromFilePath(this.filePath);
+            // Without an object extension only the targets shape is checked, with no manifest read
+            const values = config?.extension !== undefined && !isLegacyComponent(config)
+                ? resolveComponentValues(name, config, await this.manifestExtensions(), await this.siblingComponents())
+                : resolveComponentValues(name, config, [], []);
+            // Legacy payment components (string extension) still load through swell.app, which evaluates an IIFE
+            if (isLegacyComponent(config)) {
+                postData.build_file = {
+                    content_type: 'application/javascript',
+                    data: await bundleComponent(this.appPath),
+                };
+            }
+            else {
+                const { code } = await bundleComponentModule(this.filePath, this.appRoot());
+                // The CDN keeps a file's type only through an extension it maps, and
+                // it maps application/javascript but not text/javascript. Frames
+                // import the bundle as a module, which browsers refuse as text/plain
+                postData.build_file = {
+                    content_type: 'application/javascript',
+                    data: code,
+                };
             }
-            // Save the original file and the bundled version
             postData.file = {
                 data: fileData,
             };
-            postData.build_file = {
-                content_type: 'application/javascript',
-                data: code,
-            };
-            postData.values = config;
+            postData.values = values;
         }
         catch (error) {
             throw new FunctionProcessingError(`Unable to compile component ${this.name}`, error);

package/dist/lib/apps/component-extension.d.ts

@@ -0,0 +1,23 @@
+export interface ManifestExtension {
+    id: string;
+    type: string;
+}
+export interface SiblingComponent {
+    name: string;
+    config?: Record<string, unknown>;
+}
+/**
+ * Whether the config is the legacy swell.app contract (string extension)
+ * @param {object} config static component config
+ * @returns {boolean} true for a string extension
+ */
+export declare function isLegacyComponent(config: Record<string, unknown> | undefined): boolean;
+/**
+ * The values to push for a component's static config
+ * @param {string} name component name
+ * @param {object} config static component config
+ * @param {ManifestExtension[]} extensions extensions of swell.json
+ * @param {SiblingComponent[]} siblings the app's other root components
+ * @returns {object} values with the extension type added
+ */
+export declare function resolveComponentValues(name: string, config: Record<string, unknown> | undefined, extensions: ManifestExtension[], siblings: SiblingComponent[]): Record<string, unknown>;

package/dist/lib/apps/component-extension.js

@@ -0,0 +1,60 @@
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const TARGETS_SHAPE = 'targets must be a list of objects with an id, like [{ id: "<target id>" }]';
+/**
+ * Whether the config is the legacy swell.app contract (string extension)
+ * @param {object} config static component config
+ * @returns {boolean} true for a string extension
+ */
+export function isLegacyComponent(config) {
+    return typeof config?.extension === 'string';
+}
+// Target ids and what each target needs are the platform's to check at push
+function checkTargets(config) {
+    if (config.targets === undefined) {
+        return;
+    }
+    if (!Array.isArray(config.targets) ||
+        !config.targets.every((item) => isRecord(item) && typeof item.id === 'string' && item.id !== '')) {
+        throw new Error(TARGETS_SHAPE);
+    }
+}
+/**
+ * The values to push for a component's static config
+ * @param {string} name component name
+ * @param {object} config static component config
+ * @param {ManifestExtension[]} extensions extensions of swell.json
+ * @param {SiblingComponent[]} siblings the app's other root components
+ * @returns {object} values with the extension type added
+ */
+export function resolveComponentValues(name, config, extensions, siblings) {
+    const values = { ...config };
+    checkTargets(values);
+    const { extension } = values;
+    // A string extension is the legacy swell.app contract
+    if (extension === undefined || typeof extension === 'string') {
+        return values;
+    }
+    if (!isRecord(extension) ||
+        typeof extension.id !== 'string' ||
+        !extension.id) {
+        throw new Error('extension must be an object with an id, like { id: "card" }');
+    }
+    const matches = extensions.filter((item) => item.id === extension.id);
+    if (matches.length > 1) {
+        throw new Error(`extension "${extension.id}" is declared more than once in swell.json`);
+    }
+    const [declared] = matches;
+    if (!declared) {
+        throw new Error(`extension "${extension.id}" is not declared in swell.json`);
+    }
+    const other = siblings.find((sibling) => {
+        const siblingExtension = sibling.config?.extension;
+        return (sibling.name !== name &&
+            isRecord(siblingExtension) &&
+            siblingExtension.id === extension.id);
+    });
+    if (other) {
+        throw new Error(`extension "${extension.id}" already has the component ${other.name}`);
+    }
+    return { ...values, extension: { ...extension, type: declared.type } };
+}

package/dist/lib/apps/components.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" resolution-mode="require"/>
+import type * as http from 'node:http';
+/** Path of component modules on the `swell app dev` proxy */
+export declare const COMPONENT_DEV_PATH = "/.swell/components/";
+/**
+ * Whether a file is a component entry: a .tsx or .jsx file directly in components/
+ * @param {string} file path relative to the app
+ * @returns {boolean} true for a root component
+ */
+export declare function isRootComponentFile(file: string): boolean;
+/**
+ * Component entries of an app
+ * @param {string} appPath app directory
+ * @returns {Promise<string[]>} paths relative to the app, sorted
+ */
+export declare function listRootComponentFiles(appPath: string): Promise<string[]>;
+/**
+ * Components to rebuild after a change: root components bundle their shared
+ * code, so a change under components/ outside the root rebuilds all of them
+ * @param {string} appPath app directory
+ * @param {string} changedFile changed file, relative to the app
+ * @returns {Promise<string[]>} root components to push again
+ */
+export declare function componentsToRebuild(appPath: string, changedFile: string): Promise<string[]>;
+/**
+ * Builds and serves `/.swell/components/<Name>.js` for `swell app dev`
+ * @param {string} appPath app directory
+ * @param {string} pathname request path
+ * @param {http.ServerResponse} res response to write
+ * @returns {Promise<void>} resolves when the response is written
+ */
+export declare function serveComponentModule(appPath: string, pathname: string, res: http.ServerResponse): Promise<void>;