![\"A](\"https://evershop.io/assets/images/storefront-8ef74389fc1ddad76ad209bb740a8dda.jpg\")
There are four ways to change how the storefront looks, and they are not equal. Each step down this ladder gives you more control and costs you more on every upgrade.
\nStart at step 1 and stop as soon as the design is achieved. A theme built entirely on steps 1 and 2 survives a major EverShop upgrade untouched. A theme that forks twenty components does not — as the React 17 → 19 upgrade demonstrated, forked components keep their old assumptions and break silently.
\n\n
Everything visible above — type scale, colours, card layout, grid columns — is reachable from steps 1 and 2. Reach for step 4 only when the structure has to change.
\n| Step | Technique | Upgrade cost | Use when |
|---|---|---|---|
| 1 | Design tokens | None | Colour, radius, spacing, type scale |
| 2 | CSS against core class hooks | Near zero | Layout tweaks, decoration, spacing on specific blocks |
| 3 | Additive components in existing Areas | Low | Adding something core does not render |
| 4 | Component override | High — you own it forever | The markup or behaviour itself must change |
Most re-skins are entirely a token exercise. Core's components are built on CSS custom properties, so redefining them in your theme's tailwind.css restyles every component at once, including ones added in future releases.
:root {
--primary: oklch(0.55 0.18 264);
--primary-foreground: oklch(0.98 0 0);
--radius: 0.75rem;
}
See Styling for the full token set and the Tailwind v4 setup.
\nIf your theme replaces TailwindCss.tsx and ships its own tailwind.css, it must carry over the class-based @custom-variant dark (&:is(.dark *)) line. Without it every dark: utility inside the shared ui/* primitives activates from the OS setting while your .dark tokens stay inactive — half-dark components on a light page.
Core markup carries stable, semantic class names intended as styling targets. Writing CSS against them changes appearance without owning any component.
\n.category__hero { padding-block: 4rem; }
.product__grid { gap: 2.5rem; }
.product__filters { border-inline-end: 1px solid var(--divider); }
Verified hooks include header__middle__left, category__hero, product__grid, product__filters and variant-option-list. Inspect the rendered page to find others.
@layerTailwind v4 puts its utilities in @layer utilities. Unlayered author CSS wins against any layered rule regardless of specificity, so a plain rule beats core's utilities. Put the same rule inside a layer and it loses — which reads as \"my CSS is being ignored\".
To add something core does not render, drop a component into an existing Area rather than forking the component that surrounds it. Your file is additive: core's component keeps receiving upgrades, and yours keeps rendering beside it.
\n// themes/my-theme/src/pages/productView/SizeGuideLink.tsx
export default function SizeGuideLink() {
return <a href=\"/size-guide\" className=\"text-sm underline\">Size guide</a>;
}
export const layout = {
areaId: 'productNameAfter',
sortOrder: 10
};
Useful storefront Areas include productNameBefore, productNameAfter, productPageMiddleRight, beforeCategoryInfo and searchPageBottom. See View System for how Areas resolve and Templating for the full list.
Only when the markup or behaviour itself must change. npm run theme:twizz ejects a core component and its relative-import closure into your theme, after which you own that file permanently — it stops receiving fixes, accessibility improvements and framework migrations.
Before overriding, check whether steps 1–3 get you there. If you must override:
\naria-describedby wiring and keyboard-reachable Add-to-Cart quietly disappear._() calls and defaultProps are the two that fail silently.Say the design calls for product cards with a coloured badge, tighter grid spacing and the price above the title.
\n.product__grid { gap: … }.productNameBefore.Three of the four requirements never touch a core component.
\nEverShop v2.2.1 is out. It is the largest release since 2.0: four months of work that adds a visual page builder, a blog module, typed custom fields on every entity, a completely rebuilt shipping and fulfillment stack, built-in cloud file storage and product recommendations — on top of a move to React 19.
\nIt also fixes several security vulnerabilities, so upgrading promptly is recommended.
\n\nA new core module gives you drag-and-drop storefront editing at /admin/page-builder.
![\"The](\"https://evershop.io/assets/images/page-builder-75fe8f776be9710a073147c0e9da242b.jpg\")
You compose widgets into your theme's areas and edit text and images directly on the canvas. Everything you change goes into a draft that only you see — one draft per admin, per theme — so two people can work on the same store without colliding, and nothing reaches shoppers until you publish.
\nWhen the draft is ready you can publish it immediately or schedule a rollout. Rollout plans stay editable and cancelable right up until they run, so a campaign scheduled for Friday can still be adjusted on Thursday.
\nThe editor also gives you a layers panel, per-widget styling controls, device preview modes, undo/redo tracked per route, and a \"Globals\" view for areas that appear on every page.
\nFor theme developers: a route opts into the builder by adding \"editable\": true to its route.json. Thirteen core routes ship with it, including the homepage, category, product, search, cart, checkout and the blog pages.
A full blog module — posts, categories, tags, comments and reactions — with storefront pages, an RSS feed and page-builder widgets.
\nComment moderation policy lives on the category, not the post: each category is open, moderated or closed, which lets you run an open comment section on tutorials while locking it on announcements. Posts support four reaction types; comments support likes.
![\"Creating](\"https://evershop.io/assets/images/blog-comment-policy-a459ed1b5e1a75210d8986780129152d.jpg\")
Blog posts and categories are also metafield owners (below), so you can add your own typed fields to them.
\nTyped custom fields, now on products, categories, collections, customers, orders, blog posts, blog categories and the shop itself.
\nTen field types ship — short text, long text, rich text, integer, number, boolean, date, colour, URL and nested groups — each available as a single value or a list. Values are validated on write against the definition, and every field declares whether it is visible to customers or admin-only, so a field marked internal never reaches the storefront GraphQL schema.
\n![\"Defining](\"https://evershop.io/assets/images/metafields-ff72a9b397fe7a6284b53819baade374.jpg\")
The part worth knowing for theme authors: a theme can declare its own field definitions in theme.json. They are provisioned when the theme is activated and re-checked on every boot, with attribution recorded so you can see which theme created which field. A new <Metafield> component renders them on the storefront.
This is the largest change in the release, and the one most likely to affect existing extensions.
\nShipping is now provider-based. The old flat zone → method → rate model is gone. Zones now have providers attached to them, and each provider supplies its own methods — either statically or by quoting live rates against a carrier API, with a per-provider timeout so a slow API degrades that one provider instead of hanging checkout. Your existing zones, methods and rates are migrated automatically into a built-in Core provider that behaves like the old system.
\nZones also became multi-country: a single \"EU\" zone can now cover every member state instead of needing one zone per country.
\n![\"The](\"https://evershop.io/assets/images/shipping-providers-95f9536ee7946f2c2e98b61f91dc9208.jpg\")
Fulfillment went multi-shipment. An order can now be shipped in several packages, each with its own items, status, tracking number and purchased label. The order's own shipment status became a rollup computed from those shipments — pending, partially_shipped, shipped, partially_delivered, delivered, partially_canceled or canceled — so an order with two of three parcels dispatched reports that accurately rather than being either \"shipped\" or not.
![\"A](\"https://evershop.io/assets/images/shipments-5eb94b2bb4195ce363e29b26234c16d0.jpg\")
Carriers are a registry. An extension can register a carrier that creates labels, generates tracking URLs and pushes status updates back into EverShop. Purchased labels are stored against the shipment. A custom carrier ships in core for manual tracking numbers.
Packages round it out: define your box and envelope sizes once, assign one to each product, and dimensions flow through the cart into the order and on to the carrier when a label is bought.
\nS3, Azure Blob and Google Cloud Storage are now built into core — previously these were separate extensions.
\n![\"The](\"https://evershop.io/assets/images/cloud-storage-001a63a84cfe35e4c89b4f9c46352f32.jpg\")
Credentials are configured on a new System Setting page and applied per call, so switching providers takes effect without a restart. Environment variables override the stored settings for anyone who prefers to keep secrets out of the database, and secrets that come from the environment render masked in the admin. The storage host is automatically allowed for the image optimizer, so images served from your bucket keep working without extra configuration.
\nFour new shelves, all with page-builder widgets:
\nEach product can inherit the global rules, override them, or pin manual picks — and the edit page previews exactly what shoppers will see, with the reason each match was chosen.
\n![\"The](\"https://evershop.io/assets/images/recommendations-468dfce866af70951f437c089246f287.jpg\")
The framework moved from React 17 to React 19. Because EverShop resolves React through a single hoisted copy, your theme and extensions run on it too.
\nMost of the breaking changes fail silently — no build error, just a blank area or an ignored default at runtime. Upgrading Your Theme And Extensions To React 19 walks through every one and its fix.
\n/about-us rather than /page/about-us), with the old paths permanently redirecting.This release fixes unauthenticated SSRF, an IDOR on customer endpoints, stored XSS, and an account-takeover path via a missing authorization check on customer update. All high-severity dependency alerts were cleared. If you are running 2.1.x, upgrade.
\nThe full list is in the changelog. The ones most likely to affect you:
\n| Change | What to do |
|---|---|
| React 19 | defaultProps is ignored on function components, propTypes is gone, and react-toastify was replaced by sonner. See the migration guide. |
| Shipping providers | The shipping_method and shipping_zone_method tables are dropped. Extensions built on them must move to the provider registry. Your data migrates automatically. |
| Multi-shipment | Order and shipment went one-to-many. order.shipment_status is now derived — never write it directly. Shipment statuses must declare a phase. |
| Widget storage | widget was renamed to widget_instance and placement moved to its own table. Direct SQL against the old table breaks. |
| Settings moved out of config.json | Currency, timezone, units, branding, catalog and tax options are admin settings now, with config kept as a fallback — except themeConfig.logo, which was removed outright. |
| Dropped columns | category.include_in_nav (use the menu widgets) and url_rewrite.language. |
| Build and deps | The --skip-minify flag and build-fast script were removed; node-cron went 3 → 4, so verify custom job schedules. |
npm install @evershop/evershop@2.2.1
npm run build
npm run start
Or with Docker:
\ndocker pull evershop/evershop:2.2.1
This release applies 32 database migrations, several of which transform data or drop legacy tables — the shipping tables are replaced by the provider model, widget is renamed, and shipment statuses are collapsed and recomputed. Migrations run automatically on first start and there is no down-migration. Take a backup before you begin.
After upgrading:
\nthemeConfig.logo was removed with no fallback.include_in_nav.Thanks to everyone who contributed to this release and to those who reported the issues it fixes. The upgrade path from 2.1.2 was rehearsed against a seeded store before release — but if you hit something, open an issue.
", "url": "https://evershop.io/blog/release-notes-v2-2-1", "title": "EverShop v2.2.1: Page Builder, Blog, Metafields and a Rebuilt Shipping Stack", "summary": "The largest EverShop release since 2.0 — a visual page builder, a blog module, typed custom fields, pluggable shipping providers, multi-shipment fulfillment, built-in cloud storage and React 19.", "date_modified": "2026-08-12T00:00:00.000Z", "author": { "name": "Evershop Team", "url": "https://evershop.io" }, "tags": [ "release" ] }, { "id": "https://evershop.io/blog/upgrading-to-react-19", "content_html": "EverShop 2.2.1 upgraded the framework from React 17 to React 19.
\nBecause EverShop resolves React through a single hoisted copy (a webpack alias), your theme and your extensions run on the same React as the core. There is no opt-out: once you upgrade EverShop, your components are React 19 components.
\n\nNone of the changes below produce a build error. Your theme compiles, the server starts, and the damage shows up at runtime as a blank area, an ignored default value, or a hydration mismatch that only appears in production. Read the whole page before upgrading a live store.
Search your theme and extension source for each of these:
\n| Search for | Status | Fix |
|---|---|---|
defaultProps | Ignored on function components | ES default parameters |
propTypes | Removed from React | Delete, or use TypeScript |
react-toastify | No longer a dependency | sonner, via the core re-export |
ReactDOM.render, ReactDOM.hydrate | Removed | createRoot / hydrateRoot |
findDOMNode | Removed | Refs |
String refs (ref=\"name\") | Removed | Callback refs or useRef |
_( at module scope | Freezes the translation | Call it inside the component |
useState(window...) | Hydration mismatch | Read it in useEffect |
defaultProps is ignored on function componentsThis is the change most likely to break an EverShop theme, because the component system itself used to rely on it.
\nReact 19 ignores Component.defaultProps on function components entirely. It does not warn at build time. Your component simply receives undefined where it used to receive a default.
// Before — silently broken on React 19
function ProductBadge({ label, tone }) {
return <span className={`badge badge--${tone}`}>{label}</span>;
}
ProductBadge.defaultProps = { tone: 'default' };
// After
function ProductBadge({ label, tone = 'default' }) {
return <span className={`badge badge--${tone}`}>{label}</span>;
}
Area caseIf you previously passed components into an Area by assigning to Area.defaultProps.components, that channel no longer works — and because an Area with no components renders nothing, the symptom is a blank page section rather than an error.
Use the exported helpers instead:
\nimport { setAreaComponents, getAreaComponents } from '@components/common/Area.js';
// The first argument is a ROUTE id, not an area id, and the second is a nested
// areaId -> componentId map:
setAreaComponents('productView', {
productPageTop: {
mySection: { id: 'mySection', sortOrder: 10, component: { default: MySection } }
}
});
setAreaComponents replaces, it does not mergeIt assigns the whole map for that route, clobbering the one the build already\ngenerated. For a theme or extension that just wants to add to an area, the supported\nroute is still an export const layout = { areaId, sortOrder } in the route folder —\nreach for setAreaComponents only when you genuinely want to take over a route's map.
propTypes is removedReact 19 removed propTypes support. Declarations are ignored; nothing validates and nothing warns. The prop-types package is still installed as a dependency of @evershop/evershop — 37 legacy .jsx files in core still import it — but React no longer reads it, so it has no effect on your components either way.
// Before
MyWidget.propTypes = {
title: PropTypes.string.isRequired,
count: PropTypes.number
};
Delete them. If you want the safety back, write the component in TypeScript and type its props — which is what core does now.
\nreact-toastify → sonnerreact-toastify v6 depended on react-transition-group, which used the removed findDOMNode. It has been replaced by sonner.
// Before
import { toast } from 'react-toastify';
// After — prefer the core re-export so you always match the mounted Toaster
import { toast } from '@components/common/ui/Sonner.js';
toast.success('Saved');
toast.error('Something went wrong');
The toast.* call surface is close to drop-in. Two structural differences:
<ToastContainer /> becomes <Toaster />.Toaster on the storefront, so importing toast and calling it is enough.ReactDOM.render and ReactDOM.hydrate are gone. This only affects you if you wrote custom entry/mount code — normal page and widget components are mounted by EverShop.
// Before
ReactDOM.hydrate(<App />, container);
ReactDOM.render(<App />, container);
// After
import { createRoot, hydrateRoot } from 'react-dom/client';
hydrateRoot(container, <App />); // server-rendered markup
createRoot(container).render(<App />); // client-only
Also removed: findDOMNode, string refs (ref=\"input\"), and legacy context (contextTypes / getChildContext). Use useRef/callback refs and createContext.
EverShop server-renders every storefront page and hydrates it on the client. React 19 is far stricter about the two renders producing identical markup — a mismatch that React 17 patched over now discards the server HTML and re-renders on the client.
\n_() at module scopeThe translation helper resolves against the active dictionary, which is per-request on the server and per-page on the client. Calling it at module scope freezes the result at import time, so the server and client can disagree.
\nimport { _ } from '@evershop/evershop/lib/locale/translate/_';
// Broken — evaluated once, at import
const SORT_OPTIONS = [
{ value: 'price', label: _('Price') },
{ value: 'name', label: _('Name') }
];
export default function ProductSorting() {
return <Select options={SORT_OPTIONS} />;
}
// Correct — evaluated per render, inside the component
export default function ProductSorting() {
const sortOptions = [
{ value: 'price', label: _('Price') },
{ value: 'name', label: _('Name') }
];
return <Select options={sortOptions} />;
}
This applies to any module-scope const — arrays, objects, and default parameter values.
window, localStorage and document do not exist during the server render. Reading them in a useState initializer makes the first client render differ from the server's.
// Broken — server renders '', client renders the real URL
const [current, setCurrent] = useState(window.location.search);
// Correct
const [current, setCurrent] = useState('');
useEffect(() => {
setCurrent(window.location.search);
}, []);
@types/react must resolve to v19. @types/react@18 against react@^19 produces JSX type errors in a theme's tsc build.@ckeditor/ckeditor5-build-classic, @ckeditor/ckeditor5-react) were removed from core. If your extension imported them through EverShop, add them to your own package.json.A clean build proves almost nothing here, so check behaviour:
\nonRecoverableError reporting, so a mismatch is reported rather than silently swallowed._() calls surface here first.defaultProps component channel.react-toastify import is still in the tree.We are excited to announce the release of Evershop v2.1.1! This release brings highly requested features like reusable UI components based on Shadcn UI, support for digital products, and a significant upgrade to Tailwind CSS v4.
\nWe have completely revamped our UI foundation. We are now adopting Shadcn UI for our component library, providing accessible and customizable components that you can copy and paste into your apps.
\nAlongside this, we've updated dependencies to use Tailwind CSS v4, taking advantage of the latest performance improvements and features in the ecosystem. We also replaced @heroicons/react with lucide-react for a more modern icon implementation.
Selling non-physical goods just got easier. V2.1.1 introduces native support for Digital Products. You can now manage downloadable files, license keys, and other digital assets directly within Evershop.
\nWe've streamlined the development environment: Evershop now runs with just two Webpack instances — one for the backend and one for the frontend—instead of multiple processes. This reduces memory usage and speeds up hot module replacement (HMR), resulting in a faster, smoother development workflow.
\nTo update your Evershop project to v2.1.1, run the standard update command:
\nnpm update @evershop/evershop
This release includes breaking changes, primarily due to the UI architecture shift.
\nWe have deprecated and removed several custom UI components in favor of standard Shadcn UI components. If your custom themes or extensions import the following, you will need to update them:
\n| Removed Component | Replacement |
|---|---|
components/common/Button.tsx | Use Shadcn Button |
components/common/modal/Modal.tsx | Use Shadcn Dialog |
components/admin/Badge.tsx | Use Shadcn Badge |
components/admin/Card.tsx | Use Shadcn Card |
In previous versions, customizing the Tailwind configuration required creating a file named frontstore.tailwind.js in the theme folder.
Starting from v2.1.1 with Tailwind CSS v4, the customization process has changed:
\nTailwindCss.tsx component by running the following command:\nnpm run theme:twizz
tailwind.css file in your theme folder, which you can edit to adjust your Tailwind 4 settings.For example, you can update your tailwind.css as follows:
@import \"tailwindcss\";
@plugin \"@tailwindcss/typography\";
@import \"tw-animate-css\";
@import \"./shadcn.css\";
@custom-variant dark (&:is(.dark *));
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--font-sans: var(--font-sans);
--font-mono: var(--font-geist-mono);
--color-sidebar-ring: var(--sidebar-ring);
--color-sidebar-border: var(--sidebar-border);
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
--color-sidebar-accent: var(--sidebar-accent);
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
--color-sidebar-primary: var(--sidebar-primary);
--color-sidebar-foreground: var(--sidebar-foreground);
--color-sidebar: var(--sidebar);
--color-chart-5: var(--chart-5);
--color-chart-4: var(--chart-4);
--color-chart-3: var(--chart-3);
--color-chart-2: var(--chart-2);
--color-chart-1: var(--chart-1);
--color-ring: var(--ring);
--color-input: var(--input);
--color-border: var(--border);
--color-divider: var(--divider);
--color-destructive: var(--destructive);
--color-accent-foreground: var(--accent-foreground);
--color-accent: var(--accent);
--color-muted-foreground: var(--muted-foreground);
--color-muted: var(--muted);
--color-secondary-foreground: var(--secondary-foreground);
--color-secondary: var(--secondary);
--color-primary-foreground: var(--primary-foreground);
--color-primary: var(--primary);
--color-popover-foreground: var(--popover-foreground);
--color-popover: var(--popover);
--color-card-foreground: var(--card-foreground);
--color-card: var(--card);
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
--radius-2xl: calc(var(--radius) + 8px);
--radius-3xl: calc(var(--radius) + 12px);
--radius-4xl: calc(var(--radius) + 16px);
}
:root {
--radius: 0.325rem;
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--card: oklch(1 0 0);
--card-foreground: oklch(0.145 0 0);
--popover: oklch(1 0 0);
--popover-foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
--secondary: oklch(0.97 0 0);
--secondary-foreground: oklch(0.205 0 0);
--muted: oklch(0.97 0 0);
--muted-foreground: oklch(0.556 0 0);
--accent: oklch(0.97 0 0);
--accent-foreground: oklch(0.205 0 0);
--destructive: oklch(0.577 0.245 27.325);
--border: oklch(0.922 0 0);
--divider: oklch(0.922 0 0);
--input: oklch(0.922 0 0);
--ring: oklch(0.708 0 0);
--chart-1: oklch(0.646 0.222 41.116);
--chart-2: oklch(0.6 0.118 184.704);
--chart-3: oklch(0.398 0.07 227.392);
--chart-4: oklch(0.828 0.189 84.429);
--chart-5: oklch(0.769 0.188 70.08);
--sidebar: oklch(0.985 0 0);
--sidebar-foreground: oklch(0.145 0 0);
--sidebar-primary: oklch(0.205 0 0);
--sidebar-primary-foreground: oklch(0.985 0 0);
--sidebar-accent: oklch(0.97 0 0);
--sidebar-accent-foreground: oklch(0.205 0 0);
--sidebar-border: oklch(0.922 0 0);
--sidebar-ring: oklch(0.708 0 0);
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
--card: oklch(0.205 0 0);
--card-foreground: oklch(0.985 0 0);
--popover: oklch(0.205 0 0);
--popover-foreground: oklch(0.985 0 0);
--primary: oklch(0.922 0 0);
--primary-foreground: oklch(0.205 0 0);
--secondary: oklch(0.269 0 0);
--secondary-foreground: oklch(0.985 0 0);
--muted: oklch(0.269 0 0);
--muted-foreground: oklch(0.708 0 0);
--accent: oklch(0.269 0 0);
--accent-foreground: oklch(0.985 0 0);
--destructive: oklch(0.704 0.191 22.216);
--border: oklch(1 0 0 / 10%);
--input: oklch(1 0 0 / 15%);
--ring: oklch(0.556 0 0);
--chart-1: oklch(0.488 0.243 264.376);
--chart-2: oklch(0.696 0.17 162.48);
--chart-3: oklch(0.769 0.188 70.08);
--chart-4: oklch(0.627 0.265 303.9);
--chart-5: oklch(0.645 0.246 16.439);
--sidebar: oklch(0.205 0 0);
--sidebar-foreground: oklch(0.985 0 0);
--sidebar-primary: oklch(0.488 0.243 264.376);
--sidebar-primary-foreground: oklch(0.985 0 0);
--sidebar-accent: oklch(0.269 0 0);
--sidebar-accent-foreground: oklch(0.985 0 0);
--sidebar-border: oklch(1 0 0 / 10%);
--sidebar-ring: oklch(0.556 0 0);
}
The email service architecture has been simplified to use a single instance.
\nUpgrade Extensions:
\nUpdate your Sendgrid or Resend extension to the latest version:
npm update @evershop/sendgrid
Update Configuration:
\n {
\"system\": {
\"notification_emails\": {
\"from\": \"noreply@example.com\",
\"order_confirmation\": {
\"enabled\": true,
\"templatePath\": null
},
\"customer_welcome\": {
\"enabled\": true,
\"templatePath\": null
},
\"reset_password\": {
\"enabled\": true,
\"templatePath\": null
}
}
}
}
templatePath lets you manage an email template from source instead of using\nEverShop's default. It is a path relative to the project root; omit it or set it\nto null to keep the built-in template. Note the reset-password key is\nreset_password — not customer_password_reset.
Test Email Delivery:
\nAfter upgrading, send a test email (e.g., password reset or order confirmation) to verify that your configuration works as expected.