DOCSEARCHbyAlgolia
Submit Docs

Nimara Documentation

website·Indexed 32 days ago

https://docs.nimara.store

Developer guides for setting up and managing Nimara storefronts, including local development with Docker, Saleor CMS configuration, Stripe and Universal Commerce Protocol (UCP) integrations, and deployment via Terraform to Vercel.

Tokens
11.2K
Snippets
44
Records
83
Agent score
52%

What's inside Nimara

  1. Overview of Nimara Stripe Integration

    Nimara provides a serverless TypeScript-based Stripe integration built with Next.js, designed for deployment on Vercel. It integrates with Saleor to support Stripe Payment Intents, multi-channel Stripe configurations, Stripe Tax calculations, and automated webhook setup via Stripe keys.

  2. Overview of Universal Commerce Protocol (UCP) in Nimara

    Nimara implements the Universal Commerce Protocol (UCP) version 2026-04-08, an open standard for agentic commerce. This allows AI agents and platforms to interact with the storefront for product discovery, cart management, checkout, and order retrieval via a shared REST API. All UCP endpoints are served under the path /api/ucp/{channelSlug}/.

  4. Understand the Nimara automated release process

    Releases are triggered automatically after a push to main passes the full CI workflow. The process follows these steps:

    1. The Release workflow checks out the successful commit and runs semantic-release to determine if a new version, tag, or GitHub release is required based on Conventional Commit history.
    2. Vercel independently builds affected applications from main and updates production domains upon success.
    3. Documentation is published from the same commit after the Release workflow succeeds.

    There are no separate release branches or promotion merges.

  5. Understand Nimara storefront i18n architecture

    The storefront utilizes a shared i18n package and message composition system. It identifies itself by passing app: "storefront" to the @nimara/i18n's createRequestConfig method. This configuration ensures the storefront receives both common and storefront message bundles, including any locale-specific overrides.

  6. Understand Nimara i18n architecture and file structure

    Nimara uses a shared i18n package with feature-based message files and locale overrides. Base English messages are the source of truth, and regional overrides only contain keys that differ from the base English version to ensure key stability across locales.

    File Locations:

    • Base English Messages: packages/i18n/src/messages/en/
    • Regional Overrides: packages/i18n/src/messages/<locale>/ (e.g., en-GB)

    Message File Mapping:

    • common.json: Contains shared namespaces such as common, errors, form-validation, and stock-errors.
    • storefront.json: Contains storefront-specific namespaces such as home, cart, checkout, auth, account, and order.
    • marketplace.json: Contains marketplace-specific namespaces (e.g., marketplace.*, vendor products, orders, collections).

  7. Create and manage Static Pages

    Static pages are used for standalone content like "About Us" or "Contact" pages and do not require attributes.

    Step 1: Define the Static Page Type

    1. Go to Saleor dashboard → Configuration → Content Management → Page Types.
    2. Click Create page type, enter the name Static page, and save.

    Step 2: Create a Static Page instance

    1. Go to Saleor dashboard → Content → Create content.
    2. Select Static page as the page type.
    3. Provide the following details:
      • Title: The page title (e.g., "About Us").
      • Slug: The URL path (e.g., /about-us).
      • Content: Use the rich text editor for text, images, and links.

  9. Implement daily development workflow at Nimara

    Nimara utilizes trunk-based development where main is the sole long-lived branch and the source for all releases and Vercel production deployments. Every commit to main must be safe to release. Developers should start changes from the latest main, keep branches focused on a single releasable change, and aim to merge within two working days. For larger tasks, use backward-compatible slices, feature flags (default-off), or branch by abstraction.
    git switch main
git pull --ff-only origin main
git switch -c feat/my-new-feature

  10. Configure storefront navigation and footer menus

    Manage the links for your website's header and footer using the Navigation settings:

    1. Navigate to Saleor dashboard → Configuration → Miscellaneous → Navigation.
    2. Click Create menu to create the following specific menus:
      • navbar: Manages links displayed in the website's header navigation.
      • footer: Manages links displayed in the footer section.
    3. To add links, select a menu and click Create new item. Menu items can link to:
      • Categories
      • Collections
      • Static Pages (created in the Content section)
      • External or internal URLs

  11. Run the Nimara Stripe App locally

    Because Saleor pushes payment webhooks to the app, the app must be reachable via a public URL. Use a tunneling service (like ngrok, cloudflared, or untun) to expose port 4000 to the internet.
    # Start the dev server
pnpm dev:stripe

# In another shell, expose port 4000 via your chosen tunnel
# Example: ngrok http 4000

  12. Submit a Pull Request to Nimara

    To contribute changes to Nimara, push your branch and open a PR against the main branch. Requirements for merging include:

    1. A Conventional Commit title.
    2. Included testing evidence.
    3. Passing status for Linters & Tests.
    4. Passing status for all four Vercel projects: nimara-docs, nimara-ecommerce, nimara-ecommerce-stripe, and nimara-marketplace.