How to Customize an ECNext Storefront

An independent store should feel specific to its brand without forking every commerce rule into page components. ECNext separates public build identity, storefront presentation, localized content, and domain behavior so each layer can change for the right reason.

1. Set the deployment identity

The deployment name, description, logo, URL, and default locale come from NEXT_PUBLIC_* build values. The storefront studio can override the customer-facing name, logo, and homepage content at runtime; the domain and infrastructure identity remain deployment settings. Admin runtime identity can support authentication and email behavior, but changing it does not rebuild storefront metadata, canonical URLs, robots, or sitemap output.

Use the brand deployment preview in Admin Settings to compare the compiled storefront identity with the editable runtime values before releasing a site.

2. Choose and publish a storefront

Open Admin → Storefront studio. Choose Essentials for general retail, Atelier for an editorial collection, Spotlight for a featured product, or Supply for catalog search and procurement. Enter storefront branding, upload images, write the English and Chinese homepage copy, and select which discovery sections appear.

Save a draft, open its protected preview, then publish it. Restore the previous version if needed. Export the design JSON to reuse presentation settings in another independent store; images and product references still need to belong to that store.

3. Establish the visual language

• src/app/globals.css owns global tokens such as color, typography, radius, and density.
• src/components/ui contains reusable design-system primitives.
• src/components/storefront owns the catalog, product, cart, buyer, header, footer, and home presentation.

Keep brand styling in these presentation layers. Do not copy price selection, inventory authorization, or procurement state rules into visual components.

4. Localize market-facing copy

English and Simplified Chinese messages live under src/config/locale/messages. Replace navigation, merchandising, trust, policy, and support copy per market while preserving stable message keys. Additional locales should be introduced with complete routing, messages, metadata, and formatting coverage.

5. Replace integrations at their boundary

Payment, email, storage, analytics, and customer-service providers are configured through Admin Settings and infrastructure adapters, using the merchant's own credentials — merchandise checkout reads the same payment configuration. Destination tax rules and shipping zones, methods, and rates are operator data edited in Admin, not code: a store changes what it charges by changing those records. A live carrier-rating or carrier-tracking integration is the one boundary still unbuilt — tracking events are recorded against a shipment rather than polled from a carrier — and it should follow the same adapter boundary when it lands.

6. Preserve the single-store contract

A customized site receives its own database, storage credentials, encryption key, and provider accounts. Avoid adding a runtime storeId to shared commerce records: create another deployment when creating another store.

The studio provides built-in layouts and bounded presentation settings. General drag-and-drop page composition and executable third-party theme packages remain separate extension work. Theme selection does not change account permissions, prices, stock, or existing orders.