Installation ​

This page installs Lynx on a Magento store and keeps it up to date. It is for whoever runs the store's server: a developer, an agency or the hosting provider. Once it is done, the store owner continues in the admin with Getting Started.

Requirements ​

• Magento Open Source 2.4
• PHP 8.2 or newer
• Node.js 22 or newer on the server or on the machine that builds your store, used to build the theme

Install ​

Lynx installs with Composer from Packagist, so no repository or access token is needed. Run these commands from the Magento root folder:

composer require oocscommerce/magento2-lynx-community
bin/magento setup:upgrade
bin/magento lynx:theme:setup OOCS_LynxVue                      # installs the JavaScript packages of the theme
bin/magento lynx:static:deploy                                 # builds the storefront scripts and styles
bin/magento setup:di:compile                                   # production mode only
bin/magento setup:static-content:deploy                        # production mode only
bin/magento cache:flush

Lynx's storefront is a JavaScript app, built with Node.js. lynx:theme:setup installs the JavaScript packages of the themes you name, each into its own theme folder. lynx:static:deploy builds the storefront: the scripts and styles of those themes. Without this build, the store has nothing to load. The PageBuilder editor of the admin comes prebuilt. Run lynx:theme:setup again after enabling or disabling a module; lynx:static:deploy stops and tells you when it is needed.

The Stripe and Braintree integrations are separate packages, for stores that already run the official payment module of that provider. Install one only after its payment module:

composer require oocscommerce/module-lynx-payment-stripe   # or module-lynx-payment-braintree
bin/magento setup:upgrade

Then run the Lynx build commands above again, so the new payment form is built into the checkout.

Run setup:static-content:deploy after lynx:static:deploy: it publishes the files that command builds, so running it first would publish the previous build. setup:di:compile and setup:static-content:deploy are needed only in production mode; skip them in developer mode.

Turn off Magento's JavaScript and CSS merging and Inline Translation ​

Lynx ships its scripts and styles already optimized. Magento's own merging and bundling options would break them, and Inline Translation would show its raw {{{…}}} markers in the texts, so they must stay off for every store view that uses Lynx. They are off in a fresh Magento install, but some stores turn them on. Run:

bin/magento config:set dev/css/merge_css_files 0
bin/magento config:set dev/js/merge_files 0
bin/magento config:set dev/js/enable_js_bundling 0
bin/magento config:set dev/js/move_script_to_bottom 0
bin/magento config:set dev/translate_inline/active 0
bin/magento cache:flush

In developer mode the same options are in Stores › Configuration › Advanced › Developer, under CSS Settings, JavaScript Settings and Translate Inline. If one of them is set on a website or store view, add --scope=websites --scope-code=<code> or --scope=stores --scope-code=<code> to the commands above.

Email theme ​

Lynx draws storefront pages, not emails. Emails such as order confirmations are drawn with a Magento theme, set per store view in Stores › Configuration › Lynx › Theme Settings › Email › Email Theme. It defaults to Magento Blank; pick the theme the store used before, such as Magento Luma, to keep the look of its emails. That theme must stay installed. See Settings.

Optional: critical CSS ​

Use CSS critical path in Stores › Configuration › Advanced › Developer › CSS Settings (default scope only) puts the theme's web/css/critical.css inline in the page and loads the main stylesheet without blocking. Lynx Vue ships a basic critical.css for the page frame: the header, the page width, image boxes, and what keeps menus and drawers hidden. Content below shows unstyled until the stylesheet arrives. Write your own in a child theme once the header changes.

Optional: compile module XML before going live ​

bin/magento lynx:compile

This stores Magento's merged module configuration as files, so the store does less work when its cache is rebuilt. Lynx works without it. Run it when the store goes live, after setup:upgrade and setup:di:compile, and again after each update, setup:upgrade, or module install, enable or disable. See Compiling module XML for what it does.

Updating ​

To install a new version of Lynx, run from the Magento root folder:

composer update 'oocscommerce/*'
bin/magento setup:upgrade
bin/magento lynx:theme:setup OOCS_LynxVue                      # installs the JavaScript packages of the theme
bin/magento lynx:static:deploy                                 # builds the storefront scripts and styles
bin/magento setup:di:compile                                   # production mode only
bin/magento setup:static-content:deploy                        # production mode only
bin/magento cache:flush

Use the same theme names you built at installation, and run lynx:compile afterwards if you use it. If you use server-side rendering, restart the Node.js renderer or redeploy the Cloudflare Worker afterwards, so the renderer matches the new version. Your designs and page layouts are kept.