# Wave

Source: https://developers.swell.is/app-guides/wave

Wave is a storefront app with a visual editor and an AI agent built in. Describe a change in plain words and the agent makes it on your store's own pages, or click any section and edit it yourself. Wave works with the Tide theme, which supplies the starting sections and page templates, and shoppers check out on Swell's hosted checkout.

Wave is free. The agent's AI use is billed from your store's AI credits; the rest of the editor doesn't use AI.

## How it works

| When | What the app does |
| --- | --- |
| You create a storefront with Tide | Copies Tide's sections and page templates into the storefront's draft. Until your first publish, shoppers see a "Coming soon" page. |
| You ask the agent for a change | Edits the draft, test-renders every page that uses the change with sample store data and with an empty store, and saves it only if it passes. A version is saved before the agent changes the theme. |
| You edit a section yourself | Saves the change to the draft as you type. |
| You publish | Makes every changed page, section, menu and content page live together, and saves a version. |
| A shopper opens a page | Renders the page on the server with your catalog, and serves it from Swell's cache. |
| You change products, categories, content or settings in the dashboard | Refreshes the storefront's pages that show them, without a publish. Cached pages can take a few minutes to update. |
| Every night | Removes automatic versions older than 30 days and agent chats older than 90 days. |

## Before you begin

- The Tide theme. Wave edits themes built for it, and Tide is the first.
- AI allowed for Wave, if you want to use the agent and image generation. The Inspector, the Theme tab, pages, menus, versions and publishing work without it.
- Products and categories in your catalog, so the product, category and search templates show real data.
- Shipping and payment methods set up in Swell. Shoppers check out on Swell's hosted checkout.

## Set up

Set up Wave in your test environment first, and place a test order there before you go live.

**1. Install Wave and Tide**

Install Wave and the Tide theme from the Swell App Store. Tide's storefront app is Wave, so both must be installed. To use the agent, check **Allow AI** under **Uses AI** in Wave's install dialog; it's off by default. You can also turn it on later on the app's **Overview** page.

**2. Create a storefront with Tide**

In Swell, go to **Online Store > Storefront**, click **Add storefront** and open the **My library** tab. Click **Create storefront** on Tide. Tide's sections and templates are copied into the storefront's draft.

**3. Open the editor**

In **Online Store > Storefront**, click **Open editor** on the storefront.

**4. Set your store name and logo**

In the editor's right panel, open the **Theme** tab. Enter the store name, upload a logo and favicon, and add social links and an announcement.

**5. Build your pages**

Ask the agent for changes on the **Agent** tab, or click a section and edit it on the **Inspector** tab. Check each page under **Pages**, **Templates** and **Shopper** on the board, then click **Publish**.

**6. Place a test order**

In **Online Store > Storefront**, open the storefront's ⋮ menu and choose **Preview**. Add a product to the cart and check out on Swell's hosted checkout. The order then appears in **Orders**.

**7. Go live**

Apps and storefronts are separate in the test and live environments. In the live environment, repeat steps 1 to 5. Then in **Online Store > Storefront**, open the storefront's ⋮ menu and choose **Publish**. Publishing makes it the storefront customers see at your store's address and on your custom domains. After that, **Publish** in the editor is all you need to make changes live.

## Using Wave

### The editor

Every page of the store is a live card on one board, in three groups:

- **Pages**: home and your content pages.
- **Templates**: product, category, categories, search, page, blog, blog post, policy and page not found.
- **Shopper**: cart, account and sign in.

Click a card to open it, scroll to pan, and press Ctrl or ⌘ while you scroll to zoom. **Fit** shows every page. The rail on the left lists the same pages; open one to see its sections. Tags such as New and Changed mark what the draft changed.

The right panel has three tabs:

- **Agent**: chat with the AI agent. **New chat** starts over, and **History** lists past chats, which are shared with everyone who edits the store.
- **Inspector**: the selected section or block. Edit its fields, move it up or down, hide it, delete it, or add a section after it.
- **Theme**: store-wide settings. See Settings below.

The top bar shows the save status, **Versions**, **Preview** (the draft at desktop, tablet or mobile width) and **Publish**. Press **?** for keyboard shortcuts.

### Working with the agent

Describe the result you want, on the page you mean. Select a section first, or press **/**, and your message is about that section. For example:

- "Make the hero a split layout with the photo on the right."
- "Add an FAQ under the product details with three sample questions."
- "Use a serif for headings and make the background warmer."
- "Create a Shipping page from this text: …"

While the agent works, a status line says what it is doing, and each page it touches shows **AI editing**. **Stop** ends the turn. A message you send while it works steers the turn instead.

The agent can:

- Write and change sections and blocks, including new sections built from the theme's components.
- Rearrange any page.
- Change the theme's colors, fonts, corner radii and shadow, on every page at once.
- Add, edit and remove content pages.
- Place widgets from your installed apps.
- Generate images, and edit images already in your store.

The agent can't:

- Publish. Only you can.
- Change products, prices, orders, checkout or store settings. Those stay in the Swell dashboard.
- Edit menus. Use the menu field in a header or footer section.
- Install apps or add scripts to the storefront.

The agent won't invent store facts such as policies, prices, product specs, reviews, people, awards or contact details. When a page needs one you haven't given it, it asks, or writes a labelled placeholder such as "[Your return policy]" and lists the placeholders in its reply. Sample content says it is a sample on the page itself. Check for placeholders before you publish.

Ask for an image and the agent generates it (square, wide or tall), saves it to your store's files and sets it on the section. It makes at most 3 images per message and 10 per chat. Upload your logo and favicon in the **Theme** tab.

Every change the agent makes is test-rendered on each page that uses it before it is saved. A change that fails isn't saved, and the agent gets the reasons so it can fix them.

### Editing sections yourself

Click a section on the board to open it in the **Inspector**. Changes save as you type, and **Revert** puts the page back as it was when you selected the section. You can also click a line of text on the page and type over it. Text that comes from your store, such as a product name, is edited in the dashboard instead.

### Pages, templates and menus

Content pages are your store's Swell pages, at `/pages/<address>`. Add one with **Add page**, or ask the agent. Each has a name, address, text, layout, visibility, and an SEO title and description. Changing the address redirects the old one. **Remove from store** unpublishes a page; it is never deleted.

Templates lay out every product, category, blog post and policy page. Product grids, product details, category lists, search results and blog posts come from your catalog. A product, category or page can use an alternate layout of its template.

Menus are your storefront's Swell menus, the same ones as the dashboard's navigation. Edit them from a header or footer section's menu field: add, nest, reorder and remove links to pages, products, categories, blogs or any address.

Content page and menu edits stay in the draft until you publish.

### Colors and fonts

Ask the agent to change colors, fonts, corner radii or the shadow. Each change applies to every page at once. Fonts are chosen from fonts already installed on shoppers' devices; web fonts aren't available yet.

### Preview and publish

Everything you and the agent change is a draft. **Preview** shows the draft as shoppers will see it. **Publish** lists every changed page, section, menu and content page, then makes them live together. It won't publish while a section fails to render, or while the agent is still working. After a publish, shoppers get the new pages on their next page load.

### Versions

A version is saved before the agent changes the theme, when you publish, as you edit, and when you choose **Save version**. Open **Versions** to preview any of them or restore it. Your draft is saved as a version first, so a restore can be undone. Restoring changes the theme only: menus, content pages and store content stay as they are.

Automatic versions are kept 30 days, named ones until you delete them, and published ones for a year. Inline text edits can also be undone with Ctrl or ⌘ + Z while the undo notice shows.

### App widgets

Apps can offer storefront widgets. In the **Inspector**, **Add section** lists them under **Apps**, with a field for each of the widget's settings, or you can ask the agent to place one. In the editor a widget shows as a labelled placeholder; it runs on the storefront.

### AI credits

The agent, image generation and chat titles use AI through Swell. AI use is billed from your store's AI credits, at the AI provider's price plus 20%, and each store starts with $5 of included credits. Check **Allow AI** in Wave's install dialog, or turn on **Allow this app to use AI** later on the app's **Overview** page. Only the store owner and users who can manage apps can change it.

The agent panel tells you when it can't run:

| Message | What to do |
| --- | --- |
| You're out of AI credits. | Click Add credits to open the credits page. |
| You've reached this month's AI spending limit. | Click Change limit, or wait for next month. |
| AI is turned off for this app. | Turn on Allow this app to use AI on the app's Overview page. |
| AI is paused for this store. | Contact Swell support. |
| Too many AI requests at once. | Click Try again in a moment. |

### In the dashboard

| Where | What it's for |
| --- | --- |
| Online Store > Storefront | Create a storefront with Tide, open the editor with Open editor, and preview or publish a storefront from its ⋮ menu. |
| Apps > Wave | The app's Overview page, where Allow this app to use AI turns the agent's AI use on or off. Uninstall the app from here. |
| Products, Categories, Content | The catalog and content the storefront shows. Changes here reach the storefront without a publish. |

## Settings

Store-wide settings are on the editor's **Theme** tab. Colors, fonts, corner radii and the shadow are changed by asking the agent.

| Setting | Description |
| --- | --- |
| Store name | Shown in the header and page titles. |
| Logo | Shown in the header. PNG, JPEG, WebP or GIF, up to 2 MB. |
| Favicon | The browser tab icon. A square PNG, up to 512 KB. |
| Social links | Links to your social accounts. |
| Announcement | The announcement bar at the top of every page. |

## Limitations

- Wave works with themes built for it, starting with Tide. Liquid themes don't work with Wave.
- The storefront is in one language. If your store sells in several currencies, shoppers can pick one and prices show in it.
- The agent can't publish, edit menus, or change products, prices, orders, checkout or store settings.
- The Inspector has no image upload. Ask the agent to generate or edit an image, or paste the address of an image already on your store's image CDN.
- There's no undo for the whole editor. Use **Versions** to restore an earlier theme, or **Revert** to put the selected page back.
- Fonts are limited to fonts installed on shoppers' devices.
- A page holds up to 20 sections, and a section up to 12 blocks by default.
- The agent makes at most 3 images per message and 10 per chat.
- Dashboard changes to products, categories, content and settings can take a few minutes to show on cached pages.

## Troubleshooting

### "Not saved. The theme checks rejected this change"

A value broke a section. The reasons are listed; change the value, or ask the agent to fix it.

### "Not saved yet. Can't reach the store."

The editor retries on its own, then offers **Try again**.

### "… was changed somewhere else while you were editing."

Someone else edited the same field. **Use mine** keeps your change.

### The agent didn't respond to your message

Send the message again.

### Publish says "Fix before publishing"

A section fails to render. **Show** finds it, and **Ask the agent to fix it** sends the agent the error.

### Publish says a section shows sample data

The section shows labelled samples where your store has no data yet. Shoppers don't see the samples.

### "This text comes from your store."

Edit the text in the dashboard, for example on the product.

### "Update ready"

A newer version of the editor is available. Reloading keeps your page, selection and unsent message.

### A dashboard change isn't on the storefront yet

Cached pages refresh within a few minutes.

### The agent says AI can't run

See the messages under AI credits above.

## Uninstalling

If the Wave storefront is your published one, publish another storefront first. Then in **Online Store > Storefront**, open the Wave storefront's ⋮ menu and choose **Delete storefront**.

Then go to **Apps > Wave** and choose **Uninstall app**. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately. Your products, customers and orders aren't affected.

Published content pages and menus are your store's own Swell pages and menus, so they stay after you uninstall. Unpublished drafts of sections, pages and menus are kept with the Wave storefront and are deleted with it.

## For developers

A storefront's theme is a set of Swell theme files:

- `theme/sections/<type>.tsx` and `theme/blocks/<type>.tsx`: one React module per section and block type. Each exports a `schema` (label and fields) and a default component built from Wave's component kit.
- `theme/templates/<page>.json`: each page's ordered list of sections, with their settings and blocks.
- `theme/config/settings.json`: brand settings and design tokens.

The editor and the agent write the draft copy, and **Publish** copies it to the live one. Section fields are text, textarea, url, image, select and lists, plus data fields, such as a product, a product list, a category list, a menu or a content page, that Wave fills from Swell when it renders.

Pages are rendered on the server, each store's code in its own isolated worker. Section code never runs in the shopper's browser: imports are limited to React and the component kit, and every rendered section passes a strict HTML check. A section that fails is left out of the live page. Anonymous live pages are sent with `s-maxage=60, stale-while-revalidate=300`; carts, accounts and drafts are never shared.

Wave stores its own data in these collections on your store:

| Collection | What it holds |
| --- | --- |
| Agent chats | Agent chat history, kept 90 days. |
| Theme versions | Saved versions of the theme. |
| Theme blobs | The file contents that versions point to. |

Images the agent generates are saved to the store's files. A model function tells the storefront when catalog and content data it shows changes, and a nightly function removes expired versions and chats.

### Storefront widgets

An app declares its widgets in its own `swell.json`:

```json
{
  "storefront": {
    "embeds": {
      "script": "frontend://embed.js",
      "blocks": [
        {
          "id": "size_chart",
          "label": "Size chart",
          "description": "A size table for the current product",
          "icon": "ruler",
          "props": [
            {
              "id": "title",
              "type": "text",
              "label": "Title",
              "default": "Sizes"
            }
          ]
        }
      ]
    }
  }
}
```

Wave loads `script` from the app's frontend only on pages that place one of its blocks. Each placement is an element with `data-app-embed="<app>/<block>"` and its settings as JSON in `data-app-props`; what's inside it is the fallback shoppers see without JavaScript. Prop types are `text`, `textarea`, `url`, `number`, `boolean` and `select`. The optional `connect` and `img` lists name the https origins the script may call and load images from.

### Limits

| Limit | Value |
| --- | --- |
| Sections per page | 20 |
| Blocks per section / per page | 12 by default, up to 50 / 80 |
| Section or block module | 64 KB |
| Content page text | 32 KB |
| Image upload (Theme tab) | 2 MB, 8192 px a side |
| Agent message | 8,000 characters |
| Generated images | 3 per message, 10 per chat |
| Named versions | 25 |
| Apps with widgets | 10, with 20 blocks each |

## Support

Swell builds and maintains the Wave app. For help with it, email support@swell.is.