@swell/cli 2.9.26 → 2.9.27

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,19 @@
+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>;
+        overwrite: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    createType: ConfigType;
+    run(): Promise<void>;
+}

package/dist/commands/create/component.js

@@ -0,0 +1,84 @@
+import { input } from '@inquirer/prompts';
+import { Args, Flags } from '@oclif/core';
+import { CreateConfigCommand } from '../../create-config-command.js';
+import { ConfigType } from '../../lib/apps/index.js';
+import { getComponentTemplate, setupComponentSupport, toComponentName, } from '../../lib/create/component.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',
+    ];
+    static helpMeta = {
+        usageDirect: '<name> [-d <description>] -y',
+    };
+    static flags = {
+        description: Flags.string({
+            char: 'd',
+            default: '',
+            description: 'Description',
+        }),
+        overwrite: Flags.boolean({
+            default: false,
+            description: 'Overwrite existing file',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Skip prompts, require all arguments',
+        }),
+    };
+    static summary = 'Create an app component in the components folder.';
+    createType = ConfigType.COMPONENT;
+    async run() {
+        const { args, flags } = await this.parse(CreateComponent);
+        const { description: descriptionFlag, overwrite, 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 });
+        }
+        const created = await this.createFile({
+            extension: 'tsx',
+            fileBody: getComponentTemplate(componentName, description),
+            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/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,9 @@ 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>;
     preparePostData(postData: any): Promise<any>;
 }
 export declare class AppConfigAsset extends AppConfigDefault {

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

@@ -3,8 +3,8 @@ 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 { bundleFunction, bundleComponent, bundleComponentModule, bundleWorkflow, getLocalInputs, } from '../bundle.js';
+import { analyzeFunctionSource, hasKindDiagnostic, readStaticConfig, workflowStaticConfigError, } from '../function-source-analysis.js';
 import { AllConfigPaths, ConfigType, filePathExistsAsync, hashFile, hashString, } from './index.js';
 export class IgnoringFileError extends Error {
     constructor(message) {
@@ -95,6 +95,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 +190,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 +229,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 +311,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 +367,19 @@ 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;
+    }
     async preparePostData(postData) {
         if (!this.isRootComponent()) {
             return postData;
@@ -366,19 +390,32 @@ 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('; ')}`);
+            }
+            // Checkout payment components still load through swell-js, which evaluates the legacy IIFE
+            if (config?.extension) {
+                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 = config ?? {};
         }
         catch (error) {
             throw new FunctionProcessingError(`Unable to compile component ${this.name}`, error);

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>;

package/dist/lib/apps/components.js

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { bundleComponentModule } from '../bundle.js';
+import { getNameFromFilePath } from './index.js';
+/** Path of component modules on the `swell app dev` proxy */
+export const COMPONENT_DEV_PATH = '/.swell/components/';
+const COMPONENT_EXTENSIONS = new Set(['.jsx', '.tsx']);
+/**
+ * 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 function isRootComponentFile(file) {
+    const parts = file.split('/');
+    return (parts.length === 2 &&
+        parts[0] === 'components' &&
+        COMPONENT_EXTENSIONS.has(path.extname(parts[1])));
+}
+/**
+ * Component entries of an app
+ * @param {string} appPath app directory
+ * @returns {Promise<string[]>} paths relative to the app, sorted
+ */
+export async function listRootComponentFiles(appPath) {
+    let names;
+    try {
+        names = await fs.readdir(path.join(appPath, 'components'));
+    }
+    catch {
+        return [];
+    }
+    return names
+        .map((name) => `components/${name}`)
+        .filter((file) => isRootComponentFile(file))
+        .sort();
+}
+/**
+ * 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 async function componentsToRebuild(appPath, changedFile) {
+    if (!changedFile.startsWith('components/') ||
+        isRootComponentFile(changedFile)) {
+        return [];
+    }
+    return listRootComponentFiles(appPath);
+}
+/**
+ * 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 async function serveComponentModule(appPath, pathname, res) {
+    const headers = {
+        'Access-Control-Allow-Origin': '*',
+        'Cache-Control': 'no-store',
+    };
+    const name = /^\/\.swell\/components\/([\w-]+)\.js$/.exec(pathname)?.[1];
+    const files = name ? await listRootComponentFiles(appPath) : [];
+    const file = files.find((entry) => getNameFromFilePath(entry) === name);
+    if (!file) {
+        res.writeHead(404, headers).end('Component not found');
+        return;
+    }
+    try {
+        const { code } = await bundleComponentModule(file, appPath);
+        res
+            .writeHead(200, { ...headers, 'Content-Type': 'text/javascript' })
+            .end(code);
+    }
+    catch (error) {
+        res
+            .writeHead(500, { ...headers, 'Content-Type': 'text/plain' })
+            .end(error.message);
+    }
+}

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

@@ -205,6 +205,7 @@ export declare function writeJsonFile(file: string, data?: any): Promise<void>;
 export declare function hashFile(filePath: string, fileContents?: Buffer, relativePath?: string): string;
 export declare function hashString(...contents: (Buffer | string)[]): string;
 export declare function appAssetImage(appPath: string, fileName: string): Promise<string | undefined>;
+export declare function getNameFromFilePath(filePath: string): string;
 export declare function appConfigFromFile(filePath: string, configType: ConfigType, appPath: string): Promise<AppConfig>;
 export declare function findAppConfig(app: App, filePath: string, configType: ConfigType): AppConfig | undefined;
 interface BatchAppFiles {

package/dist/lib/apps/index.js

@@ -52,9 +52,11 @@ export var ConfigType;
     ConfigType["THEME"] = "theme";
     ConfigType["WEBHOOK"] = "webhook";
 })(ConfigType || (ConfigType = {}));
-// Models and content should come first in order
+// Models first; then components, which content and settings fields reference
+// by name; then content
 const ConfigTypeBatchOrder = [
     ConfigType.MODEL,
+    ConfigType.COMPONENT,
     ConfigType.CONTENT,
     ConfigType.ASSET,
     ConfigType.FUNCTION,
@@ -63,7 +65,6 @@ const ConfigTypeBatchOrder = [
     ConfigType.WEBHOOK,
     ConfigType.THEME,
     ConfigType.FRONTEND,
-    ConfigType.COMPONENT,
     ConfigType.FILE,
 ];
 // All available configs
@@ -89,6 +90,7 @@ const StandardConfigTypes = [
     'NOTIFICATION',
     'SETTING',
     'WEBHOOK',
+    'COMPONENT',
 ];
 // Configs available for storefront app types
 export const StorefrontConfigTypes = [
@@ -359,7 +361,7 @@ export async function appAssetImage(appPath, fileName) {
         }
     }
 }
-function getNameFromFilePath(filePath) {
+export function getNameFromFilePath(filePath) {
     return path.parse(filePath).name.replaceAll('_', '-');
 }
 export async function appConfigFromFile(filePath, configType, appPath) {

package/dist/lib/bundle.d.ts

@@ -9,4 +9,24 @@ import type { FunctionSourceAnalysis } from './function-source-analysis.js';
 export declare function getLocalInputs(entryPoint: string, rootDir: string): Promise<string[]>;
 export declare function bundleFunction(filePath: string): Promise<any>;
 export declare function bundleWorkflow(filePath: string, analysis: FunctionSourceAnalysis): Promise<any>;
-export declare function bundleComponent(filePath: string): Promise<any>;
+/**
+ * Legacy build for checkout payment components, which swell-js evaluates as an
+ * IIFE exposing `Component.default`, `Component.config` and `Component.preact`.
+ * @param {string} filePath absolute path of the component file
+ * @returns {Promise<string>} the bundle code
+ */
+export declare function bundleComponent(filePath: string): Promise<string>;
+export interface ComponentModuleBuild {
+    /** ES module exporting mount, update and unmount */
+    code: string;
+    /** App files the component imports, relative to the app root */
+    inputs: string[];
+}
+/**
+ * Builds a component into the module the component frame loads: generated
+ * mount, update and unmount functions render its default export with Preact.
+ * @param {string} filePath component file, relative to appRoot
+ * @param {string} appRoot app directory
+ * @returns {Promise<ComponentModuleBuild>} the module code and the app files it includes
+ */
+export declare function bundleComponentModule(filePath: string, appRoot: string): Promise<ComponentModuleBuild>;

package/dist/lib/bundle.js

@@ -84,6 +84,12 @@ export async function bundleWorkflow(filePath, analysis) {
         throw new Error(`Unable to compile workflow "${filePath}": ${error.message}`, { cause: error });
     }
 }
+/**
+ * Legacy build for checkout payment components, which swell-js evaluates as an
+ * IIFE exposing `Component.default`, `Component.config` and `Component.preact`.
+ * @param {string} filePath absolute path of the component file
+ * @returns {Promise<string>} the bundle code
+ */
 export async function bundleComponent(filePath) {
     try {
         const content = await fs.readFile(filePath, 'utf8');
@@ -113,11 +119,7 @@ export async function bundleComponent(filePath) {
             write: false,
             logLevel: 'silent',
         });
-        const { outputFiles: [{ text: code }], } = buildResult;
-        // eslint-disable-next-line no-new-func
-        const evalFn = new Function(`${code}\nreturn { ...Component }`);
-        const { config } = evalFn();
-        return { code, config };
+        return buildResult.outputFiles[0].text;
     }
     catch (error) {
         throw new Error(`Unable to compile component "${filePath}": ${error.message}`, { cause: error });
@@ -435,3 +437,84 @@ function replaceModuleExports(code) {
         .replaceAll(/^module\.exports\b/gm, 'var moduleExports')
         .replaceAll(/\bmodule\.exports\b/gm, 'moduleExports');
 }
+const COMPONENT_ENTRY = 'swell-component-entry.js';
+// Components render with Preact; React imports in third-party libraries resolve to its compat layer
+const COMPONENT_ALIASES = {
+    react: 'preact/compat',
+    'react-dom': 'preact/compat',
+};
+// The nearest tsconfig.json overrides esbuild's jsx options per file, and
+// apps may still say "jsx": "react". A pragma wins over both, so the app's
+// own .jsx/.tsx files always compile with Preact's automatic runtime, while
+// the rest of its tsconfig (paths, baseUrl) still applies.
+const preactJsxPlugin = {
+    name: 'swell-preact-jsx',
+    setup(build) {
+        build.onLoad({ filter: /\.[jt]sx$/ }, async (args) => {
+            if (args.path.split(path.sep).includes('node_modules')) {
+                return;
+            }
+            const source = await fs.readFile(args.path, 'utf8');
+            return {
+                contents: `/** @jsxRuntime automatic @jsxImportSource preact */ ${source}`,
+                loader: args.path.endsWith('.tsx') ? 'tsx' : 'jsx',
+            };
+        });
+    },
+};
+/**
+ * Builds a component into the module the component frame loads: generated
+ * mount, update and unmount functions render its default export with Preact.
+ * @param {string} filePath component file, relative to appRoot
+ * @param {string} appRoot app directory
+ * @returns {Promise<ComponentModuleBuild>} the module code and the app files it includes
+ */
+export async function bundleComponentModule(filePath, appRoot) {
+    const entry = `./${filePath.split(path.sep).join('/')}`;
+    try {
+        const { metafile, outputFiles } = await esbuild.build({
+            absWorkingDir: appRoot,
+            alias: COMPONENT_ALIASES,
+            bundle: true,
+            format: 'esm',
+            jsx: 'automatic',
+            jsxImportSource: 'preact',
+            logLevel: 'silent',
+            metafile: true,
+            minify: true,
+            platform: 'browser',
+            plugins: [preactJsxPlugin],
+            stdin: {
+                contents: [
+                    "import { h, render } from 'preact';",
+                    `import Component from ${JSON.stringify(entry)};`,
+                    'export function mount(root, props) { render(h(Component, props), root); }',
+                    'export function update(root, props) { render(h(Component, props), root); }',
+                    'export function unmount(root) { render(null, root); }',
+                ].join('\n'),
+                loader: 'js',
+                resolveDir: appRoot,
+                sourcefile: COMPONENT_ENTRY,
+            },
+            target: 'es2020',
+            write: false,
+        });
+        const inputs = Object.keys(metafile.inputs).filter((input) => !input.includes('node_modules/') &&
+            !input.startsWith('<') &&
+            input !== COMPONENT_ENTRY);
+        return { code: outputFiles[0].text, inputs };
+    }
+    catch (error) {
+        const nonJs = /Cannot import "([^"]+)" into a JavaScript file|No loader is configured for "[^"]+" files: (\S+)/.exec(error.message);
+        let reason = error.message;
+        if (/Could not resolve "preact(?:\/[^"]*)?"/.test(error.message)) {
+            reason = 'install preact in the app (npm install preact)';
+        }
+        else if (nonJs) {
+            reason = `components cannot import CSS or other non-JavaScript files yet (${nonJs[1] ?? nonJs[2]}); use inline styles or a <style> element`;
+        }
+        throw new Error(`Unable to compile component "${filePath}": ${reason}`, {
+            cause: error,
+        });
+    }
+}

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

@@ -0,0 +1,18 @@
+export declare const PREACT_VERSION = "^10.28.0";
+export declare const APPS_SDK_VERSION = "^2.0.0-alpha.6";
+export declare const toComponentName: (value: string) => string;
+export declare function getComponentTemplate(name: string, description: string): string;
+export interface ComponentSetupResult {
+    changed: string[];
+    dependenciesAdded: boolean;
+    warnings: string[];
+}
+/**
+ * Adds preact and @swell/apps-sdk to package.json, and gives components their
+ * own tsconfig, excluded from the root one and checked by the typecheck script.
+ * Never overwrites values the app already has, except a 2.x SDK from before
+ * components.
+ * @param {string} appPath app directory
+ * @returns {Promise<ComponentSetupResult>} files changed and warnings to show
+ */
+export declare function setupComponentSupport(appPath: string): Promise<ComponentSetupResult>;

package/dist/lib/create/component.js

@@ -0,0 +1,186 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as semver from 'semver';
+export const PREACT_VERSION = '^10.28.0';
+export const APPS_SDK_VERSION = '^2.0.0-alpha.6';
+// The first release with the ./components entry
+const COMPONENTS_SDK = semver.minVersion(APPS_SDK_VERSION);
+// Example: 'color picker' => 'ColorPicker'
+export const toComponentName = (value) => {
+    const name = value
+        .split('.')[0]
+        .split(/[^\dA-Za-z]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join('');
+    // A component name is also its function name, so it must start with a letter
+    return /^[A-Za-z]/.test(name) ? name : '';
+};
+export function getComponentTemplate(name, description) {
+    return `import type { ComponentProps } from '@swell/apps-sdk/components';
+
+export const config = {
+  description: ${JSON.stringify(description)},
+};
+
+export default function ${name}({ value, setValue, readonly }: ComponentProps<string>) {
+  return (
+    <input
+      value={value ?? ''}
+      disabled={readonly}
+      onInput={(event) => setValue(event.currentTarget.value)}
+    />
+  );
+}
+`;
+}
+// undefined when the file is missing, null when it is not valid JSON
+async function readJson(file) {
+    let text;
+    try {
+        text = await fs.readFile(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+const writeJson = (file, value) => fs.writeFile(file, `${JSON.stringify(value, null, 2)}\n`);
+// Appended to the app's typecheck script, as the scaffold does for test/ and frontend/
+const TYPECHECK_COMPONENTS = ' && ([ ! -f components/tsconfig.json ] || tsc --noEmit -p components)';
+/**
+ * Components render in the browser with Preact, while the root tsconfig
+ * checks functions with the worker libs, which conflict with the DOM ones.
+ * Components get their own config instead.
+ * @param {boolean} extendsRoot whether the app has a root tsconfig to extend
+ * @returns {object} the contents of components/tsconfig.json
+ */
+function getComponentsTsconfig(extendsRoot) {
+    const compilerOptions = {
+        jsx: 'react-jsx',
+        jsxImportSource: 'preact',
+        lib: ['esnext', 'dom', 'dom.iterable'],
+        types: [],
+        // Relative to this file when no baseUrl is set
+        paths: {
+            react: ['../node_modules/preact/compat'],
+            'react-dom': ['../node_modules/preact/compat'],
+        },
+    };
+    if (extendsRoot) {
+        return {
+            extends: '../tsconfig.json',
+            compilerOptions,
+            include: ['**/*'],
+            // The root config excludes components, which would exclude every file here
+            exclude: [],
+        };
+    }
+    return {
+        compilerOptions: {
+            ...compilerOptions,
+            module: 'esnext',
+            moduleResolution: 'bundler',
+            target: 'esnext',
+            noEmit: true,
+        },
+        include: ['**/*'],
+        exclude: [],
+    };
+}
+/**
+ * Adds preact and @swell/apps-sdk to package.json, and gives components their
+ * own tsconfig, excluded from the root one and checked by the typecheck script.
+ * Never overwrites values the app already has, except a 2.x SDK from before
+ * components.
+ * @param {string} appPath app directory
+ * @returns {Promise<ComponentSetupResult>} files changed and warnings to show
+ */
+export async function setupComponentSupport(appPath) {
+    const result = {
+        changed: [],
+        dependenciesAdded: false,
+        warnings: [],
+    };
+    const packagePath = path.join(appPath, 'package.json');
+    const pkg = await readJson(packagePath);
+    if (pkg) {
+        if (!pkg.dependencies?.preact) {
+            pkg.dependencies = { ...pkg.dependencies, preact: PREACT_VERSION };
+            result.dependenciesAdded = true;
+        }
+        const sdkSection = ['dependencies', 'devDependencies'].find((section) => pkg[section]?.['@swell/apps-sdk']);
+        if (sdkSection) {
+            const range = pkg[sdkSection]['@swell/apps-sdk'];
+            const min = semver.validRange(range) ? semver.minVersion(range) : null;
+            if (min && semver.lt(min, COMPONENTS_SDK)) {
+                // `swell create tests` pins an earlier 2.x; 1.x is another SDK the app may use
+                if (semver.major(min) === 2) {
+                    pkg[sdkSection]['@swell/apps-sdk'] = APPS_SDK_VERSION;
+                    result.dependenciesAdded = true;
+                }
+                else {
+                    result.warnings.push(`@swell/apps-sdk ${range} has no components: install @swell/apps-sdk@${APPS_SDK_VERSION} to type them.`);
+                }
+            }
+        }
+        else {
+            pkg.devDependencies = {
+                ...pkg.devDependencies,
+                '@swell/apps-sdk': APPS_SDK_VERSION,
+            };
+            result.dependenciesAdded = true;
+        }
+        const typecheck = pkg.scripts?.typecheck;
+        const typecheckUpdated = typeof typecheck === 'string' && !typecheck.includes('components');
+        if (typecheckUpdated) {
+            pkg.scripts.typecheck = typecheck + TYPECHECK_COMPONENTS;
+        }
+        if (result.dependenciesAdded || typecheckUpdated) {
+            await writeJson(packagePath, pkg);
+            result.changed.push('package.json');
+        }
+    }
+    else {
+        result.warnings.push(pkg === undefined
+            ? 'package.json not found: run `npm init`, then `npm install preact` and `npm install -D @swell/apps-sdk`.'
+            : 'package.json could not be parsed: add preact to dependencies and @swell/apps-sdk to devDependencies.');
+    }
+    const tsconfigPath = path.join(appPath, 'tsconfig.json');
+    const tsconfig = await readJson(tsconfigPath);
+    if (tsconfig) {
+        const { exclude } = tsconfig;
+        if (!Array.isArray(exclude) || !exclude.includes('components')) {
+            // An explicit exclude replaces TypeScript's default one, so keep node_modules
+            tsconfig.exclude = [
+                ...(Array.isArray(exclude) ? exclude : ['node_modules']),
+                'components',
+            ];
+            await writeJson(tsconfigPath, tsconfig);
+            result.changed.push('tsconfig.json');
+        }
+    }
+    const componentsTsconfigPath = path.join(appPath, 'components', 'tsconfig.json');
+    await fs.mkdir(path.dirname(componentsTsconfigPath), { recursive: true });
+    const created = await fs
+        .writeFile(componentsTsconfigPath, `${JSON.stringify(getComponentsTsconfig(Boolean(tsconfig)), null, 2)}\n`, { flag: 'wx' })
+        .then(() => true, (error) => {
+        if (error.code !== 'EEXIST')
+            throw error;
+        return false;
+    });
+    if (created) {
+        result.changed.push('components/tsconfig.json');
+    }
+    if (tsconfig === null) {
+        result.warnings.push(created
+            ? 'tsconfig.json could not be parsed: add "components" to its "exclude". components/tsconfig.json was created without "extends".'
+            : 'tsconfig.json could not be parsed: add "components" to its "exclude".');
+    }
+    return result;
+}

package/dist/lib/create/content.d.ts

@@ -13,7 +13,7 @@ interface ContentViewProps {
     tabs: [];
 }
 type ContentView = 'edit' | 'list' | 'new';
-type ContentType = 'asset' | 'basic_html' | 'boolean' | 'category_lookup' | 'checkbox' | 'checkboxes' | 'collection' | 'color' | 'color_scheme' | 'color_scheme_group' | 'currency' | 'customer_lookup' | 'date' | 'datetime' | 'document' | 'dropdown' | 'email' | 'field_group' | 'font_family' | 'generic_lookup' | 'html' | 'icon' | 'image' | 'long_text' | 'lookup' | 'markdown' | 'number' | 'percent' | 'phone' | 'product_lookup' | 'radio' | 'rich_html' | 'rich_text' | 'select' | 'short_text' | 'slider' | 'slug' | 'tags' | 'text' | 'textarea' | 'time' | 'toggle' | 'url' | 'variant_lookup' | 'video';
+type ContentType = 'asset' | 'basic_html' | 'boolean' | 'category_lookup' | 'checkbox' | 'checkboxes' | 'collection' | 'color' | 'color_scheme' | 'color_scheme_group' | 'component' | 'currency' | 'customer_lookup' | 'date' | 'datetime' | 'document' | 'dropdown' | 'email' | 'field_group' | 'font_family' | 'generic_lookup' | 'html' | 'icon' | 'image' | 'long_text' | 'lookup' | 'markdown' | 'number' | 'percent' | 'phone' | 'product_lookup' | 'radio' | 'rich_html' | 'rich_text' | 'select' | 'short_text' | 'slider' | 'slug' | 'tags' | 'text' | 'textarea' | 'time' | 'toggle' | 'url' | 'variant_lookup' | 'video';
 interface ContentFieldProps {
     id: string;
     label: string;

package/dist/lib/create/setting.d.ts

@@ -9,7 +9,7 @@ interface SettingFieldProps {
     label: string;
     type?: SettingFieldType;
 }
-type SettingFieldType = 'asset' | 'basic_html' | 'boolean' | 'category_lookup' | 'checkbox' | 'checkboxes' | 'collection' | 'color' | 'color_scheme' | 'color_scheme_group' | 'currency' | 'customer_lookup' | 'date' | 'datetime' | 'document' | 'dropdown' | 'email' | 'field_group' | 'font_family' | 'generic_lookup' | 'html' | 'icon' | 'image' | 'long_text' | 'lookup' | 'markdown' | 'number' | 'percent' | 'phone' | 'product_lookup' | 'radio' | 'rich_html' | 'rich_text' | 'select' | 'short_text' | 'slider' | 'slug' | 'tags' | 'text' | 'textarea' | 'time' | 'toggle' | 'url' | 'variant_lookup' | 'video';
+type SettingFieldType = 'asset' | 'basic_html' | 'boolean' | 'category_lookup' | 'checkbox' | 'checkboxes' | 'collection' | 'color' | 'color_scheme' | 'color_scheme_group' | 'component' | 'currency' | 'customer_lookup' | 'date' | 'datetime' | 'document' | 'dropdown' | 'email' | 'field_group' | 'font_family' | 'generic_lookup' | 'html' | 'icon' | 'image' | 'long_text' | 'lookup' | 'markdown' | 'number' | 'percent' | 'phone' | 'product_lookup' | 'radio' | 'rich_html' | 'rich_text' | 'select' | 'short_text' | 'slider' | 'slug' | 'tags' | 'text' | 'textarea' | 'time' | 'toggle' | 'url' | 'variant_lookup' | 'video';
 export declare function parseFields(fields: string[]): SettingFieldProps[];
 export declare const toSettingLabel: (value: string) => string;
 export {};

package/dist/lib/function-source-analysis.d.ts

@@ -14,3 +14,14 @@ export declare function analyzeFunctionSourceText(sourceText: string, filePath?:
 export declare function getFunctionTriggers(config: Record<string, unknown>): string[];
 export declare function hasKindDiagnostic(analysis: FunctionSourceAnalysis): boolean;
 export declare function workflowStaticConfigError(): Error;
+export interface StaticConfig {
+    config?: Record<string, unknown>;
+    errors: string[];
+}
+/**
+ * Reads `export const config = {...}` as static JSON-like data without running the module.
+ * @param {string} sourceText source code of the file
+ * @param {string} filePath file name, used to pick the parser (TS, TSX, JS or JSX)
+ * @returns {StaticConfig} the config when present and static, otherwise the errors
+ */
+export declare function readStaticConfig(sourceText: string, filePath: string): StaticConfig;

package/dist/lib/function-source-analysis.js

@@ -76,6 +76,39 @@ export function hasKindDiagnostic(analysis) {
 export function workflowStaticConfigError() {
     return new Error('Workflow configs must export a static object literal so the CLI can choose the workflow bundling path before compiling.');
 }
+/**
+ * Reads `export const config = {...}` as static JSON-like data without running the module.
+ * @param {string} sourceText source code of the file
+ * @param {string} filePath file name, used to pick the parser (TS, TSX, JS or JSX)
+ * @returns {StaticConfig} the config when present and static, otherwise the errors
+ */
+export function readStaticConfig(sourceText, filePath) {
+    const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, scriptKind(filePath));
+    const configExport = findConfigExport(sourceFile);
+    if (!configExport) {
+        return { errors: [] };
+    }
+    if (!configExport.initializer) {
+        return { errors: ['config must be initialized with an object literal.'] };
+    }
+    const result = evaluateStatic(configExport.initializer);
+    if (result.errors.length > 0) {
+        return { errors: result.errors };
+    }
+    if (!isRecord(result.value)) {
+        return { errors: ['config must be an object literal.'] };
+    }
+    return { config: result.value, errors: [] };
+}
+function scriptKind(filePath) {
+    if (filePath.endsWith('.tsx'))
+        return ts.ScriptKind.TSX;
+    if (filePath.endsWith('.jsx'))
+        return ts.ScriptKind.JSX;
+    if (filePath.endsWith('.ts'))
+        return ts.ScriptKind.TS;
+    return ts.ScriptKind.JS;
+}
 function findConfigExport(sourceFile) {
     const localVariables = new Map();
     let exportedConfigLocalName;

package/dist/lib/swell-function-wrapper.js

@@ -107,6 +107,10 @@ class SwellRequest {
         this.id = req.headers.get('Swell-Request-ID') || this.logParams?.req_id;
         // Check if the request is from a local development environment
         this.isLocalDev = req.headers.get('Swell-Local-Dev') === 'true';
+        // Context of a call from an app component (Swell-Context). Only the platform
+        // sets this header; verify it with verifySwellContext from @swell/apps-sdk
+        // when a function needs cryptographic proof
+        this.swellContext = this.parseSwellContext(req.headers.get('Swell-Context'));
         // Swell client
         this.swell = new SwellAPI(this, context);
         // URL of the original request
@@ -160,6 +164,33 @@ class SwellRequest {
             return {};
         }
     }
+    parseSwellContext(token) {
+        const payload = token?.split('.')[1];
+        if (!payload) {
+            return null;
+        }
+        let claims;
+        try {
+            const binary = atob(payload.replaceAll('-', '+').replaceAll('_', '/'));
+            claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0))));
+        }
+        catch {
+            return null;
+        }
+        if (!claims || typeof claims !== 'object') {
+            return null;
+        }
+        return {
+            appId: claims.app_id,
+            installationId: claims.installation_id,
+            storeId: claims.store_id,
+            storeUser: claims.admin?.user_id
+                ? { storeId: claims.store_id, userId: claims.admin.user_id }
+                : null,
+            storefrontId: claims.storefront_id ?? undefined,
+            surface: claims.surface ?? undefined,
+        };
+    }
     log(level, ...line) {
         originalConsole[level]?.(...line);
         this._logs.push({

package/dist/push-app-command.js

@@ -6,6 +6,7 @@ import * as path from 'node:path';
 import Stream from 'node:stream';
 import ora from 'ora';
 import { default as swellConfig } from './lib/app-config.js';
+import { componentsToRebuild } from './lib/apps/components.js';
 import { buildFrontendPackage, getManagedFrontendFramework, } from './lib/apps/frontend-package.js';
 import { warnFrontendRouteCollisions } from './lib/apps/frontend-routes.js';
 import { ConfigType, getFrontendProjectValidValues, allConfigFilesInDir, CUSTOM_FRAMEWORK_SLUG, appConfigFromFile, filePathExistsAsync, findAppConfig, getConfigTypeFromPath, getConfigTypeKeyFromValue, getFrontendProjectType, getProjectCommands, globAllFilesByPath, hashFile, hashString, isPathDirectory, toPosixPath, } from './lib/apps/index.js';
@@ -714,6 +715,16 @@ export class PushAppCommand extends RemoteAppCommand {
                     appConfig: config,
                     configFile,
                 });
+                // Root components bundle their shared code, so push them again too
+                const componentFiles = await componentsToRebuild(this.appPath, configFile);
+                const componentConfigs = await Promise.all(componentFiles.map((file) => appConfigFromFile(file, ConfigType.COMPONENT, this.appPath)));
+                for (const appConfig of componentConfigs) {
+                    this.watchingChangeQueue.set(appConfig.filePath, {
+                        action: 'push',
+                        appConfig,
+                        configFile: appConfig.filePath,
+                    });
+                }
                 break;
             }
         }

package/oclif.manifest.json

@@ -1652,6 +1652,70 @@
         "app.js"
       ]
     },
+    "create:component": {
+      "aliases": [],
+      "args": {
+        "name": {
+          "default": "",
+          "description": "Component name (e.g., ColorPicker)",
+          "name": "name"
+        }
+      },
+      "description": "Create an app component in the components folder.",
+      "examples": [
+        "$ swell create component",
+        "$ swell create component ColorPicker -d \"Brand color picker\" -y"
+      ],
+      "flags": {
+        "app-path": {
+          "description": "Path to your app directory",
+          "name": "app-path",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "description": {
+          "char": "d",
+          "description": "Description",
+          "name": "description",
+          "default": "",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "overwrite": {
+          "description": "Overwrite existing file",
+          "name": "overwrite",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip prompts, require all arguments",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "create:component",
+      "pluginAlias": "@swell/cli",
+      "pluginName": "@swell/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Create an app component in the components folder.",
+      "helpMeta": {
+        "usageDirect": "<name> [-d <description>] -y"
+      },
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "create",
+        "component.js"
+      ]
+    },
     "create:content": {
       "aliases": [],
       "args": {
@@ -1978,7 +2042,7 @@
     "create": {
       "aliases": [],
       "args": {},
-      "description": "Scaffold apps, models, functions, and notifications.",
+      "description": "Scaffold apps, models, functions, components, and notifications.",
       "examples": [
         "<%= config.bin %> <%= command.id %>"
       ],
@@ -3606,5 +3670,5 @@
       ]
     }
   },
-  "version": "2.9.26"
+  "version": "2.9.27"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swell/cli",
-  "version": "2.9.26",
+  "version": "2.9.27",
   "type": "module",
   "description": "Swell's command line interface/utility",
   "keywords": [
@@ -80,9 +80,11 @@
     "eslint-config-prettier": "9.0.0",
     "eslint-plugin-prettier": "5.0.1",
     "eslint-plugin-unicorn": "48.0.1",
+    "happy-dom": "20.14.5",
     "mocha": "11.7.6",
     "nock": "13.3.6",
     "oclif": "4.0.3",
+    "preact": "10.28.0",
     "shx": "0.3.4",
     "testdouble": "3.20.0",
     "ts-node": "10.9.1"