Common Patterns

Conventions, error handling, pagination, and other patterns used across the SDK.

Updated March 29, 2026

On this page

Server vs Client Data Fetching

The DashForDevs SDK works in both server and client environments. Understanding when to use each is key to building fast storefronts.

Server Components (Recommended for Initial Load)

Fetch data in server components for SEO and faster page loads:

typescript

// app/products/page.tsx — Server Component (default)
import dash from "@/lib/dash"

export default async function ProductsPage() {
  const { products, pagination } = await dash.products.list({ limit: 20 })

  return (
    <div>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  )
}

Client Components (For Interactive Features)

Use client components for cart, auth, and real-time updates:

typescript

"use client"
import dash from "@/lib/dash"
import { useState } from "react"

export function AddToCartButton({ productId, sizeId }) {
  const [loading, setLoading] = useState(false)

  async function handleAdd() {
    setLoading(true)
    await dash.cart.add({ productId, sizeId, quantity: 1 })
    setLoading(false)
  }

  return <button onClick={handleAdd} disabled={loading}>Add to Cart</button>
}

Error Handling

All SDK methods throw on failure. Wrap calls in try/catch:

typescript

try {
  const { product } = await dash.products.get("my-product")
} catch (error) {
  // error.message contains the API error description
  // error.status contains the HTTP status code
  console.error("Failed to load product:", error.message)
}

See Error Codes for a full reference of error types.

Pagination

List endpoints return a pagination object alongside results:

typescript

const { products, pagination } = await dash.products.list({
  limit: 12,
  offset: 0,
})

// pagination = { total: 150, limit: 12, offset: 0, has_more: true }

To load the next page, increment the offset:

typescript

const page2 = await dash.products.list({
  limit: 12,
  offset: 12,
})

See Pagination for more advanced patterns.

Working with Product Variations

Products can have attributes (like strain, color, flavor) with options, each containing sizes:

typescript

const { product } = await dash.products.get("blue-dream")

// Access variations
product.attributes.forEach(attr => {
  console.log(attr.name) // "Strain"
  attr.options.forEach(option => {
    console.log(option.value, option.sizes) // "Blue Dream", [{label: "1g", price: "9.99"}]
  })
})

For performance, you can split loading between server and client using core + options endpoints.

Cart Persistence

The SDK automatically persists the cart ID in localStorage. Carts survive page refreshes and browser restarts:

typescript

// First visit — creates a new cart
await dash.cart.add({ productId: "prod_abc", sizeId: "size_123", quantity: 1 })

// Later visit — cart is automatically restored
const { items } = await dash.cart.get()
console.log(items) // Previous items still there

When a customer logs in, merge the guest cart with their account using cart migration.

Authentication Flow

DashForDevs supports OTP (email code) and password-based authentication:

typescript

// 1. Request OTP
await dash.auth.requestOTP("customer@example.com")

// 2. Verify the code the customer received
const { customer, access_token } = await dash.auth.verifyOTP({
  email: "customer@example.com",
  code: "123456",
})

// 3. Customer is now authenticated — tokens stored automatically
console.log(dash.auth.isAuthenticated) // true
console.log(dash.auth.customer)        // { id, email, first_name, ... }

See the full Authentication guide for all flows.

Global Store Data

Fetch store-wide settings (name, logo, currency, social links) with a single call:

typescript

const data = await dash.getGlobalData()

// data.global = {
//   store_name: "My Store",
//   logo: "https://...",
//   currency: "USD",
//   social_media: { instagram: "...", ... }
// }

This is ideal for layouts and footers. See getGlobalData() for the full response shape.

TypeScript Tips

The SDK exports all types. Import them for better autocomplete:

typescript

import type { Product, CartItem, Category, Pagination } from "dash4devs"

function ProductCard({ product }: { product: Product }) {
  return <h2>{product.name}</h2>
}

Next Steps

Products — Fetching and displaying products
Cart — Building a shopping cart
Authentication — Customer login and registration
SDK Reference — Complete method reference

Common Patterns

Conventions, error handling, pagination, and other patterns used across the SDK.

Updated March 29, 2026

On this page

Server vs Client Data Fetching

The DashForDevs SDK works in both server and client environments. Understanding when to use each is key to building fast storefronts.

Server Components (Recommended for Initial Load)

Fetch data in server components for SEO and faster page loads:

typescript

// app/products/page.tsx — Server Component (default)
import dash from "@/lib/dash"

export default async function ProductsPage() {
  const { products, pagination } = await dash.products.list({ limit: 20 })

  return (
    <div>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  )
}

Client Components (For Interactive Features)

Use client components for cart, auth, and real-time updates:

typescript

"use client"
import dash from "@/lib/dash"
import { useState } from "react"

export function AddToCartButton({ productId, sizeId }) {
  const [loading, setLoading] = useState(false)

  async function handleAdd() {
    setLoading(true)
    await dash.cart.add({ productId, sizeId, quantity: 1 })
    setLoading(false)
  }

  return <button onClick={handleAdd} disabled={loading}>Add to Cart</button>
}

Error Handling

All SDK methods throw on failure. Wrap calls in try/catch:

typescript

try {
  const { product } = await dash.products.get("my-product")
} catch (error) {
  // error.message contains the API error description
  // error.status contains the HTTP status code
  console.error("Failed to load product:", error.message)
}

See Error Codes for a full reference of error types.

Pagination

List endpoints return a pagination object alongside results:

typescript

const { products, pagination } = await dash.products.list({
  limit: 12,
  offset: 0,
})

// pagination = { total: 150, limit: 12, offset: 0, has_more: true }

To load the next page, increment the offset:

typescript

const page2 = await dash.products.list({
  limit: 12,
  offset: 12,
})

See Pagination for more advanced patterns.

Working with Product Variations

Products can have attributes (like strain, color, flavor) with options, each containing sizes:

typescript

const { product } = await dash.products.get("blue-dream")

// Access variations
product.attributes.forEach(attr => {
  console.log(attr.name) // "Strain"
  attr.options.forEach(option => {
    console.log(option.value, option.sizes) // "Blue Dream", [{label: "1g", price: "9.99"}]
  })
})

For performance, you can split loading between server and client using core + options endpoints.

Cart Persistence

The SDK automatically persists the cart ID in localStorage. Carts survive page refreshes and browser restarts:

typescript

// First visit — creates a new cart
await dash.cart.add({ productId: "prod_abc", sizeId: "size_123", quantity: 1 })

// Later visit — cart is automatically restored
const { items } = await dash.cart.get()
console.log(items) // Previous items still there

When a customer logs in, merge the guest cart with their account using cart migration.

Authentication Flow

DashForDevs supports OTP (email code) and password-based authentication:

typescript

// 1. Request OTP
await dash.auth.requestOTP("customer@example.com")

// 2. Verify the code the customer received
const { customer, access_token } = await dash.auth.verifyOTP({
  email: "customer@example.com",
  code: "123456",
})

// 3. Customer is now authenticated — tokens stored automatically
console.log(dash.auth.isAuthenticated) // true
console.log(dash.auth.customer)        // { id, email, first_name, ... }

See the full Authentication guide for all flows.

Global Store Data

Fetch store-wide settings (name, logo, currency, social links) with a single call:

typescript

const data = await dash.getGlobalData()

// data.global = {
//   store_name: "My Store",
//   logo: "https://...",
//   currency: "USD",
//   social_media: { instagram: "...", ... }
// }

This is ideal for layouts and footers. See getGlobalData() for the full response shape.

TypeScript Tips

The SDK exports all types. Import them for better autocomplete:

typescript

import type { Product, CartItem, Category, Pagination } from "dash4devs"

function ProductCard({ product }: { product: Product }) {
  return <h2>{product.name}</h2>
}

Next Steps

Products — Fetching and displaying products
Cart — Building a shopping cart
Authentication — Customer login and registration
SDK Reference — Complete method reference