docs
/
Example apps

Tutorial: the Remix storefront

Run the Remix 2 example, trace loaders/actions, price a cart, and use its implemented reservation flow with current backend behavior.

appmint-examples/remix-store contains catalog, product detail, cart pricing, service availability, booking, lookup and cancellation. It uses app/appmint.server.ts, a local fetch transport. It does not depend on @appmint/js-client and does not implement login, storefront checkout or payment confirmation.

1. Run the checked-in project

git clone https://github.com/JacLight/appmint-examples.git
cd appmint-examples/remix-store
cp .env.example .env.local
npm install

The manifest requires Node 20+ and declares Remix ^2.15.0, React ^18.3.1, and Vite ^5.4.0. Use these project files instead of a newer create …@latest scaffold whose architecture can differ.

APPENGINE_ENDPOINT=https://appengine.appmint.io
ORG_ID=your-org-id
APP_ID=your-app-id
APP_KEY=your-app-key
APP_SECRET=your-app-secret
npm run dev

Open http://localhost:4200. vite.config.ts calls dotenv.config({ path: '.env.local' }) because the server transport reads process.env. Client import.meta.env and server environment loading are different mechanisms; never expose these credentials under VITE_ variables.

RouteImplementation
/app/routes/_index.tsx: catalog loader
/product/:skuapp/routes/product.$sku.tsx: detail loader
/cartapp/routes/cart.tsx: browser cart
POST /api/priceapp/routes/api.price.tsx: pricing action
/bookapp/routes/book._index.tsx: service definitions
/book/:id?date=YYYY-MM-DDapp/routes/book.$id.tsx: availability loader and create action
/bookings?email=…&number=…app/routes/bookings.tsx: lookup loader and cancellation action

2. Keep upstream calls in server modules

The appmint(method, path, body?, customerToken?) helper in appmint.server.ts obtains an app token from profile/app/key and caches it in the server module. Concurrent calls share the pending application exchange. Requests carry orgid and application Authorization; a supplied visitor token is passed separately as x-client-authorization. The helper renews the application token and retries once after a 401. It does not refresh the customer session, create cookies or complete MFA.

Loaders/actions can import this server module. Browser components call the application routes; the .server.ts module boundary prevents bundling it as client code. Keep private values out of loader JSON too: anything returned from a loader is browser-visible.

The catalog loader reads storefront/products; the product loader URL-encodes the SKU. Product list rows are records with fields under row.data. Default catalog calls carry only the application identity. To render personalized prices, resolve the request's session and pass its customer token explicitly.

3. Trace cart pricing

app/cart-storage.ts keeps appmint.demo.cart in browser local storage. Lines include a cached unit price; they are not a synchronized sf_cart. app/routes/cart.tsx sends product lines, coupon and the demo's fixed Dallas address to /api/price.

The action narrows the upstream call to storefront/pricing/calculate-cart and reads an appmint_token cookie. The example has no login route that creates this cookie. Its raw cookie regular expression is a small demonstration; use your framework's session/cookie API in a deployed application.

The action forwards product items, shipping address and coupon together. The browser renders the returned total and handles valid: false for a rejected coupon. On failure it clears the old quote. The endpoint can create a cart ID, but the demo does not persist the edited basket with cart/update or reconcile payment.

Before deployment, add request schema validation, origin/CSRF protection, request-owned session handling, and authoritative product/variant checks. The current pricing service can fall back to input prices when item pricing fails; a 200 response is not proof that every SKU is valid. Replace the fixed address and prevent older quote responses from overwriting newer edits. See server proxy for a concrete validated pricing route.

4. Read service definitions and availability

The booking loader first reads GET crm/reservations/definitions, selects the record whose sk matches the route ID, and returns 404 when it is absent. It uses the definition's officeHours.timezone or UTC and asks the server for slots:

const slots = await appmint('POST', 'crm/reservations/slots', {
  reservationDefinitionId: id,
  serviceDate: date, // YYYY-MM-DD in the business's calendar
  serviceName,
});

This is the existing loader's call shape; id, date, and serviceName come from its route/definition/query resolution. Slot results carry startTime, endTime, businessTimezone, and availability fields. Keep the exact returned instants. Do not derive an end time by adding a display duration, or calculate availability by subtracting local browser bookings from office hours.

The date is a GET form/search parameter, so changing it reloads server availability. todayAt and atBusiness in app/types.ts use the business timezone. A visitor in another timezone should still understand the location/timezone of the offered appointment. Closed-day errors and no available slots are separate outcomes; the example displays both.

5. Create one controlled booking

Use a development service and a controlled customer address: creation can store a customer/reservation and send notifications. Select one offered slot in /book/:id, then submit the form. The server action uses this body:

const created = await appmint<{ name?: string }>('POST', 'crm/reservations/create', {
  reservationDefinitionId: params.id,
  service: form.get('service') || undefined,
  startTime: form.get('startTime'),
  endTime: form.get('endTime'),
  customer: {
    email: String(form.get('email') || '').trim(),
    name: String(form.get('name') || '').trim(),
    phone: String(form.get('phone') || '').trim() || undefined,
  },
  note: String(form.get('note') || '').trim() || undefined,
});

This fragment belongs in the shipped action after form = await request.formData(). The returned record's name is the reservation number used by the example's redirect. Keep that number and read the reservation back. A slot visible a moment ago can be taken by another request; show a create conflict and reload availability instead of claiming the selection was reserved.

The example trusts hidden slot fields enough to submit them to the backend; they remain user-controlled input. A production action should validate the form, enforce abuse/session policy and rely on the backend's capacity/time checks. The current example catches failures and returns status 400; distinguish validation/conflict from upstream 5xx when improving operational handling.

6. Lookup and cancel: understand the actual contract

The example calls:

GET crm/reservations/by-email/:email/:reservationNumber?
DELETE crm/reservations/cancel/:email/:reservationNumber

Path values are URL-encoded. Current lookup matches a complete email/phone case-insensitively, with regular-expression characters escaped; it is not a loose substring search. With no reservation number it can return multiple matching reservations. The lookup controller is public and does not take the current customer as an ownership parameter. Passing a customer token does not by itself restrict that lookup to the signed-in customer. Email/phone knowledge is not proof that the visitor controls that identity; apply a verified session or signed access policy in your own route before exposing sensitive booking details, and review the upstream deployment's public surface.

Cancellation is a DELETE with email and reservation number. In the current backend it marks the booking cancelled, keeps the record, stops reminders and sends the cancellation notice through the update flow. It does not delete the booking. Read it back and expect a cancelled state; the example already renders cancelled/canceled/no-show states. The cancellation route is authenticated under its controller/guard configuration; the example supplies application identity through its server transport.

The example redirects after cancellation to an email-only lookup. If your application restricts guests to one verified booking, preserve the verified booking scope rather than re-opening a broad email lookup. The example's action error is returned as action data, but the current bookings component does not consume useActionData; add visible cancellation failure handling before treating that path as complete for end users.

7. Verify and build

npx tsc --noEmit
npm run build
npm run start

start is remix-serve ./build/server/index.js; unlike dev, it does not hard-code port 4200. Configure your runtime port and server environment when deploying. The Vite build configuration's dotenv call is not a substitute for deployment environment setup. The manifest has no test script.

Test a valid/unknown SKU, invalid coupon, failed pricing request, closed booking day, empty slot list, stale slot at creation, exact reservation lookup and cancelled readback. Test malformed form input and visible cancellation failure. Add independent session and authorization tests before using real customer bookings. Build success does not prove backend connectivity, notifications, provider payment or customer isolation.

The Next.js example demonstrates a catch-all proxy instead of loaders/actions. The SDK reference covers the separate source package and its current API differences.