Developer Overview ​

This section is for developers who build on Lynx: agencies, in-house teams and extension vendors. It assumes you know Magento 2 module development. For installing Lynx on a store, see Installation.

Lynx from a developer's view ​

Lynx keeps Magento as it is: routers, controllers, the full page cache, sessions, customer data and the admin all work as usual. What changes is how a store view that runs a Lynx theme turns a controller's result into HTML.

• Every page is an Inertia.js page. Instead of rendering blocks and templates, Magento answers with a page object: the name of a page component and its props. The first visit gets that object inside the HTML; later clicks fetch only the JSON of the next page and swap it in. There is no REST or GraphQL layer to build.
• Most pages are built from a PageBuilder layout. A layout is a tree of nodes, one per component, stored per design under the page's full action name (catalog_product_view_type_simple, contact_index_index…). Merchants edit it in the visual editor.
• Components get their data from PHP providers. Each node names a registered component. When the page is resolved, the component's provider turns the node's stored settings into props. The browser renders each node with its Vue component, loading only the components on the page.

You extend Lynx mostly by adding components (a Vue file, a declaration in etc/components/*.graphqls and an optional provider) and pages (a Magento route whose layout merchants then build).

Frontend stack ​

Lynx pages do not load RequireJS, KnockoutJS, jQuery or the LESS stylesheets of Magento's standard theme:

Styling uses Tailwind CSS, the utility-first CSS framework, and daisyUI, its component library for buttons, fields, cards and notices. Both read their colors, corners and sizes from the design settings of the active PageBuilder design.

Packages ​

Lynx is a set of Composer packages under the oocscommerce/ vendor. The oocscommerce/magento2-lynx-community metapackage requires the core set; the packages marked add-on are installed separately.

Themes ​

Components live in modules, under view/frontend/lynx/vue/src. A theme only overrides them. To customise the look, create a child theme of Lynx Vue: see Themes and Overrides.

Any theme whose code, or whose parent's code, starts with OOCS/Lynx counts as a Lynx theme. Everything below applies only to store views that run one; other store views behave like plain Magento.

What changes for Magento code ​

On a Lynx store view:

• Only lynx_*.xml layout files are read. Lynx adds a lynx_ twin of every layout handle (lynx_default, lynx_catalog_product_view…) and collects only files with that prefix, from every module and theme. Blocks declared in regular layout files of Magento or other extensions are therefore not created; blocks and templates declared in lynx_*.xml render as usual, in the few containers Lynx's page layout has (see Layout XML). Use lynx_<handle>.xml for what a Lynx page needs from layout XML, such as the title or the arguments of the lynx.inertia block.
• The page layout is always lynx_column, which holds the Inertia mount point and two containers for scripts (lynx.after.body.start, lynx.before.body.end).
• Widgets assigned through layout updates do not appear. Merchants place content with components instead.
• Translations come from files (module and theme CSV files, language packs). Translations stored in the database through Inline Translation are not used.
• Pages Lynx cannot render can go back to a standard theme. The Page Fallback setting lists full action names to render with another theme; Inertia visits to them turn into full page loads.

How a Lynx page differs ​

A Lynx page keeps Magento's <head>: the title, meta tags, canonical link and Open Graph tags are printed by Magento on every full page load, as on a standard store. What changes is the body. Instead of hundreds of blocks rendered from layout XML, it carries the page as JSON, one node per component, and Vue draws it. When the shopper follows a link, only the JSON of the new page's content is fetched.

{
  "component": "OOCS_LynxTheme/Pages/Default",
  "props": {
    "title": "Men",
    "bodyClass": "catalog-category-view …",
    "layout": {
      "content": [{ "name": "default_product_listing", … }]
    }
  },
  "url": "/men.html"
}

Request lifecycle ​

Browser ──GET /contact──▶ Magento router ──▶ controller (returns a result page)
                                               │
              layout handles: default, contact_index_index
              + lynx_default, lynx_contact_index_index
                                               │
                              InertiaService::resolvePage()
                                               │
         no page declared? ──▶ PageBuilder reads the layout of the active design
                               (zones header, footer, backstage + content
                                under the path "contact_index_index")
                                               │
                              LayoutResolver: each node's provider → props
                                               │
         ┌─────────────────────────────────────┴───────────────────────────┐
   first visit: HTML with the page JSON                 Inertia visit: JSON only
   (rendered on the server when SSR is on)              (content zone only)
         └─────────────────────────────────────┬───────────────────────────┘
                                               ▼
              Browser: page component OOCS_LynxTheme/Pages/Default,
              DynamicNode renders one Vue component per node

1. Routing and controller. The request is dispatched as on any Magento store. A controller returns a regular result page; it may also declare its own page component (see Pages and Controllers).
2. Layout handles. Lynx adds the lynx_ handles and forces the lynx_column page layout. The lynx.inertia block is the mount point.
3. Page resolution. When no controller declared a page, OOCS_LynxPageBuilder builds one: the page component OOCS_LynxTheme::Default with a layout prop. The content zone is the layout stored under the request's full action name in the active design; the other zones are the same on every page of the store view.
4. Providers. LayoutResolver walks every node, merges the component's default settings into its props and, when the component has a provider, replaces them with what the provider returns. Providers can also mark their data as deferred or optional, which then loads after the page appears (see Component Providers).
5. Response. A first visit gets the HTML page with the page object embedded, server-rendered when SSR is on for that route. An Inertia visit (header X-Inertia) gets JSON. Both go through the full page cache: Inertia requests carry a _lynx query parameter, so their JSON is cached apart from the HTML.
6. Rendering. The browser resolves the page component, wraps it in the page shell (Layouts/Default) and renders each node with DynamicNode, which loads the node's component on demand.

Zones ​

Components declare which zones they may be placed in. See Creating Components.

Working with Claude Code ​

Lynx has Claude Code skills for the developer tasks on these pages. With the skills in your Magento project, ask Claude Code for the result ("add a Lynx payment renderer for my method vendor_invoice with an Invoice reference field") and it writes the module the way these pages describe: global di.xml entries, a provider with translated labels, Vue files styled with the design tokens.

The skills come as the lynx plugin of the oocscommerce marketplace, published under the MIT License at github.com/oocscommerce/claude-skills. Install it in Claude Code 2.1.275 or later:

/plugin install lynx --marketplace oocscommerce/claude-skills

For a whole team, run these from the Magento root folder and commit .claude/settings.json; each teammate then runs the install command once:

claude plugin marketplace add oocscommerce/claude-skills --scope project
claude plugin install lynx@oocscommerce --scope project

Describe what you want and Claude Code picks the matching skill, or call one by name, such as /lynx:component. To update, run claude plugin marketplace update oocscommerce and claude plugin update lynx@oocscommerce, or turn on auto-update in /plugin › Marketplaces.

Review what it writes like any other code, then build and test as described in Development Setup. Connected to your store's MCP server as well, the same session can place the new component on a page and check it in the preview.

Where to go next ​