AI Features for Hyvä Commerce

These features require a Hyvä Commerce subscription, the relevant integration packages and your own provider credentials.

AI can help plan a page, generate a draft, improve fields, create reusable components and generate images. Review the result before accepting it. Publishing remains a separate editor action.

Requirements

Install hyva-themes/commerce-module-ai-worker-cms, its AI Worker/base AI/CMS dependencies and the provider packages you use. Content and image generation require a configured worker. Use Node for local development and a hosted worker service for production. PHP provides a baseline and backup when Enable PHP Worker is enabled; it is not recommended for streaming or production. Translation can use direct PHP through the separate CMS AI Translations integration.

Open Stores → Configuration → Hyvä AI → Settings to save provider keys, and Hyvä AI → AI Worker to connect the worker. Open Hyvä AI → Hyvä CMS → Generation to enable generation and select its shared default model. Image Generation has a separate model and execution override. See Setup and Feature Configuration.

The available controls depend on installed integrations, admin permissions, configuration and content type. CMS page support does not imply every content type supports full-page generation. Complete a new entity's initial creation/save before generating against it.

Configure the Features

Follow Feature Configuration for model defaults, execution inheritance and image settings. Running the Worker covers local Node, production Node and Cloudflare. Operations covers staging access, background consumers and connection troubleshooting.

Generate a Page or Section

Open Generate with AI in a supported editor. Describe the result you need, or use the planning conversation to develop a brief. Choose a full page or a section and, where useful, supply products, categories and images through the existing pickers.

The generation workspace lets you choose a configured model, review active-theme colours and adjust content and generation options. For CMS pages, you can preview supported page layouts before accepting one. Generated sections appear in the preview as they complete.

Review the result before saving it as a draft. Full-page generation replaces the page content; section generation appends content. Valid content does not automatically receive another polish request. Choose Polish for an optional original/polished comparison, or regenerate an individual section. Validation can still trigger a repair request for invalid markup; a failed refinement retains the previous valid candidate.

Generation uses the available component definitions and validates returned fields, component structure and supported markup before saving. Check the actual copy, product choices, links, images and responsive layout yourself before publishing.

If Tailwind compilation fails, valid generated content can still be saved as a draft with a warning. Publishing from the generation flow remains blocked until styles are available. Fix style generation and check the preview before publishing; another paid content-generation request is not required just to preserve the draft.

Planning, Recovery and Previous Runs

In Plan mode, discuss the page before generating it. Wait for a planning reply, then choose Use as generation brief to turn the conversation into an editable brief. Review the brief and the resource choices before starting generation.

Start from previous run opens the generation library, with all/page scopes and reusable previous results. Restored runs retain their saved brief, model and supported generation choices. Older results without those settings do not automatically enable image generation. Previously stored original/polished variants remain available for comparison.

The job store can recover completed results after a stream interruption where the worker successfully delivered its callback. Recovery still depends on runtime lifetime, callback connectivity and retention; it is not a promise that closing a browser always completes a generation. Cancelling or starting a newer run prevents late responses from replacing the active result. Review the existing result before buying another generation.

Assistance While Editing

Generated one-off components use restricted definitions and markup. The editor can promote supported generated components into reusable instance components; this does not turn them into unrestricted PHP templates.

Translate CMS Fields

Install hyva-themes/commerce-module-cms-ai-translations and at least one AI provider. This Commerce integration is separate from manual CMS translations and can translate directly in PHP without the page-generation worker.

1. Save the provider key under Stores → Configuration → Hyvä AI → Settings and use its connection test where available.
2. With the CMS worker integration installed, open Hyvä AI → Hyvä CMS → AI Translation. A translation-only installation keeps the group under Settings.
3. Enable AI translation, choose the default content language and target store-view languages, then select a provider/model and its options. Review any custom translation rules.
4. In the translation panel, choose whether to translate missing fields or replace existing translations. Review the text and save the draft before publishing.

Translation can inherit the shared execution choice or explicitly select Direct PHP or AI Worker. DeepL remains direct because it has no worker adapter. Other supported providers can use the worker, but the translation handler still runs synchronously within PHP's request budget. Use smaller batches when necessary.

DeepL's connection test checks the saved Free/Pro key without submitting translation text. Re-enter an unreadable key on the current installation before retesting. A worker connection test does not verify provider credentials.