Conventions, error handling, pagination, and other patterns used across the SDK.
Updated
The DashForDevs SDK works in both server and client environments. Understanding when to use each is key to building fast storefronts.
Fetch data in server components for SEO and faster page loads:
// 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>
)
}
Use client components for cart, auth, and real-time updates:
"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>
}
All SDK methods throw on failure. Wrap calls in try/catch:
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.
List endpoints return a pagination object alongside results:
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:
const page2 = await dash.products.list({
limit: 12,
offset: 12,
})
See Pagination for more advanced patterns.
Products can have attributes (like strain, color, flavor) with options, each containing sizes:
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.
The SDK automatically persists the cart ID in localStorage. Carts survive page refreshes and browser restarts:
// 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.
DashForDevs supports OTP (email code) and password-based authentication:
// 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.
Fetch store-wide settings (name, logo, currency, social links) with a single call:
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.
The SDK exports all types. Import them for better autocomplete:
import type { Product, CartItem, Category, Pagination } from "dash4devs"
function ProductCard({ product }: { product: Product }) {
return <h2>{product.name}</h2>
}