DOCSEARCHbyAlgolia
Submit Docs

EverShop Development Documentation

website·Indexed 34 days ago

https://evershop.io/

Developer guides for EverShop, featuring documentation on theme components (such as VariantSelector, Form, and various input fields), module functions for managing widgets, cron jobs, and coupons, and API utilities for customer authentication and order shipment management.

Tokens
275.1K
Snippets
1.3K
Records
1.7K
Agent score
62%

What's inside EverShop

  1. Overview of EverShop Payment Gateway Architecture

    A payment gateway in EverShop consists of five primary components. This structure serves as the blueprint for implementing any payment method within the system.
    PieceFileJob
    Registrationbootstrap.tsDeclares the method, its payment statuses, and availability
    Checkout componentpages/frontStore/checkout/Stripe.tsxMounts into checkout page; provides name, form, and button renderers
    Payment intent APIapi/createPaymentIntent/Creates the Stripe PaymentIntent and returns the client secret
    Webhookapi/stripeWebHook/Receives events and updates order payment status
    Admin settingspages/admin/paymentSetting/StripePayment.tsxManages keys, display name, and capture mode

  2. Overview of EverShop Themes

    Themes in EverShop control the look and feel of the storefront (frontStore). They allow developers to override React components, add new page components, customize styles, and serve static assets without modifying the core codebase. Themes act as an overlay; if a matching component exists in the theme, it takes precedence over the core version. Note that themes only affect the storefront; the admin panel must be customized using extensions instead.

  3. Overview of the EverShop sitemap pipeline

    The sitemap is assembled from collectors, which are named sources of canonical, root-relative URLs. The pipeline follows these steps:

    1. Collectors emit SitemapEntry paths.
    2. The generator expands each path into one absolute, localized URL per enabled locale.
    3. The renderer serializes them into child files named sitemap-<name>.xml and a main sitemap.xml index.

    Paths emitted by collectors must be canonical and root-relative (e.g., /women/shoes/awesome-shoes). They must not be absolute URLs or include locale prefixes.

  4. Overview of the EverShop Event Emitter

    The Event Emitter module provides an asynchronous event system for EverShop. Events are persisted in a database table before being processed, ensuring reliability even if the application crashes or restarts. This architecture decouples event emitters from their handlers, allowing processing to occur outside the request-response cycle.

  5. Overview of EverShop Blog API access and routing

    The Blog API manages posts, categories, tags, comments, and reactions. It consists of 14 endpoints divided into two access levels:

    • Private: 11 endpoints requiring an admin access token (JWT).
    • Public: 3 endpoints allowing unauthenticated writes for storefront visitors (comments and reactions).

    Key Technical Details:

    • All {id} path parameters must be the entity's uuid, not the integer primary key.
    • There are no GET endpoints in the REST API; blog content must be retrieved using GraphQL queries (blogPost, blogPosts, blogCategories, blogTags, and blogComments).
    # Private Endpoints (Require Admin JWT)
POST   /api/blog/posts
PATCH  /api/blog/posts/{id}
DELETE /api/blog/posts/{id}
POST   /api/blog/categories
PATCH  /api/blog/categories/{id}
DELETE /api/blog/categories/{id}
POST   /api/blog/tags
PATCH  /api/blog/tags/{id}
DELETE /api/blog/tags/{id}
PATCH  /api/blog/comments/{id}
DELETE /api/blog/comments/{id}

# Public Endpoints (Unauthenticated)
POST   /api/blog/comments
POST   /api/blog/comments/{id}/like
POST   /api/blog/posts/{id}/react

  6. Overview of the EverShop Product API

    The EverShop Product API is a RESTful interface that allows developers to programmatically manage products within an EverShop store. It provides a set of endpoints to create, update, retrieve, and delete product data.

  7. Overview of EverShop Metafields

    Metafields allow merchants to attach structured data to core entities. This system consists of two parts: a definition (which describes the field's owner type, namespace, key, data type, and validations) and values (which are stored in the owning table's meta_data JSONB column).

    Metafield definitions are stored as database rows and can be created, updated, or deleted at runtime via the admin UI, REST calls, migrations, or cron jobs; they are not bootstrap-locked.

  8. Overview of the CheckboxField component

    The CheckboxField component is a versatile form input that supports both single checkbox and checkbox group modes. It integrates with React Hook Form via the Controller and automatically manages array values for multiple selections. Key features include support for horizontal or vertical layouts, the ability to disable specific options, and full TypeScript type safety using generics.

  9. Overview of EverShop View Architecture

    EverShop is a Multi-Page Application (MPA) that uses React for rendering. Each page has its own layout and components, resulting in a separate JavaScript bundle per page to optimize load times. The system uses Server-Side Rendering (SSR) for fast time-to-content and SEO, followed by client-side hydration to make the page interactive.

  10. Overview of Evershop Shipment Logic

    In Evershop, an order can have multiple shipments. A shipment consists of specific (order_item, qty) pairs assigned to a single carrier.

    Key concepts include:

    • Shipment items: Every shipment must explicitly list the order_item_id and quantity; there is no shortcut to ship an entire order.
    • Phase: Shipments exist in one of three phases: shipped, delivered, or canceled. There is no 'pending' phase.
    • Rollup: The order.shipment_status is a derived value based on the items shipped and is automatically recomputed after any shipment write operation.

  11. Overview of EverShop Storefront Features

    EverShop provides a comprehensive e-commerce platform focused on store performance and management. Key capabilities include:

    • Customizable Content Blocks: Use dynamic widgets such as Main Menus, Hero Banners, New Arrivals, and Latest Articles to personalize the storefront and optimize user experience.
    • Product Management: Tools for managing product variants (size, color, price, stock), organizing products into categories, and creating collections (e.g., Hot Deals, New Arrivals) to highlight specific items.
    • Checkout and Order Management: A fast checkout process with integrated payment providers and real-time order tracking and fulfillment workflows.
    • Integrations: Support for third-party services including Stripe, PayPal, Algolia, Klarna, Netlify, and Mailchimp.

  12. Overview of EverShop Packages

    A package represents an admin-managed box or envelope size used for shipping calculations. Products are linked to packages via product.package_id.

    Key fields include:

    • name: A unique label (e.g., "Standard Box").
    • length, width, height: Outer dimensions based on the store's dimensionUnit setting. Length and width must be > 0; height can be 0 for envelopes.
    • weight: The tare weight (weight of the empty package) based on the store's weightUnit setting. Defaults to 0.
    • is_default: A boolean indicating the default package preselected for new products. Exactly one package must be the default at all times.

    Note: Numeric values (length, width, height, weight) are stored as Postgres decimals and are returned as strings in API responses (e.g., "30.00").