> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Code layer for React themes

> Add code sections, CSS and JavaScript on top of Nightfall, Ship, Circuit, Arsenal, MarketPro and Vanguard without leaving the visual editor.

The built-in themes Nightfall, Ship, Circuit, Arsenal, MarketPro and Vanguard stay exactly as they are. The code layer lets you add your own code on top of them and keep editing visually.

## Theme code package

Each store gets one **theme code package** per built-in theme. You open it in the code editor like any theme copy. A package holds only:

| Folder | Holds |
| - | - |
| `sections/` | Code sections (`.liquid` with a `{% schema %}` block) |
| `snippets/` | Partials for your sections |
| `assets/` | `theme.css`, loaded after the theme styles, and `theme.js`, loaded deferred on theme pages |
| `locales/` | Translations for your sections |

Theme JavaScript never loads on checkout, sign-in or account pages.

## Code sections in the visual editor

Every `sections/<name>.liquid` with a `{% schema %}` block appears in the visual editor's **Add section** list, under **Theme code**. Its settings form comes from the schema, so a code section stays fully editable without code. Reorder, hide, duplicate and delete work like built-in sections.

When you change the schema in code, the form updates right away. New settings get their defaults; removed settings are ignored and their values kept.

## Section ids in CSS

In a code section `section.id` is `code:<name>`. The `:` breaks CSS selectors (`#{{ section.id }}-yearly:checked` is dropped silently) and `#id` lookups. Use `section.css_id` (`code-<name>`) in `{% style %}` and in `id=` / `for=` attributes, or `{{ value | css_id }}`. The code editor and MCP `validate` / `save_draft` warn about a raw `section.id` there; the editor's quick fix is **Use section.css\_id**.

Labels, radio/checkbox toggles, `<details>` and selects work in the visual editor canvas. To click links and buttons, turn on **Interact** in the top bar (or press `I`, or hold `Alt`).

## Edit code of a built-in section

Choose **Edit code** on a built-in section to eject it. Its Liquid twin is copied into your package with the same markup and class names, so it looks identical and keeps its settings. **Revert to built-in** brings the original section back.

## Commerce and checkout

Code sections sell with app blocks. They need no script:

```liquid theme={"system"}
{% app_block 'add_to_cart', product_id: product.id %}
{% app_block 'buy_now', product_id: product.id, mode: 'embed', label: 'Buy' %}
{% app_block 'checkout_button', mode: 'embed' %}
```

* `buy_now` and `checkout_button` go to the checkout page by default. `mode: 'embed'` opens the checkout popup over your page.
* `add_to_cart` and `cart_count` open the platform cart drawer. The theme's cart badge stays in sync.
* `reviews_widget` and `powered_by` do not work in code sections. `currency_selector` needs `currencies: 'USD,EUR'`.
* Code sections have `shop`, `collections`, `all_products`, `request` and `localization`. They have no `product`, `collection` or `routes`.
* `window.PapelShip` loads after the page has loaded, on pages whose code sections contain an app block or a `data-ps` binding. In `assets/theme.js`, wait for `papelship:sdk-ready`.

See [Commerce and checkout](/en/themes/commerce) and [App blocks](/en/themes/app-blocks).

## Publish

Live pages show the package's **published** version. Saved files show in the visual editor and the code editor previews only.

1. Edit and save files in the code editor, or let an AI agent save drafts.
2. Check the preview.
3. Press **Publish** in the code editor or the visual editor. It is the same button and shows how many changes are unpublished.

Publishing validates every package file first. If anything fails, nothing changes on the live store.

<Note>
  AI agents connected through MCP can save package files but never publish them. See [AI agents (MCP)](/en/themes/mcp).
</Note>

## Security

Package files are scanned like designs, on the source and on the rendered output. Rich text and HTML settings are sanitised on the server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.