Configuration

The root configuration object passed to defineConfig().

import { defineConfig } from "@porulle/core";

export default defineConfig({ /* CommerceConfig */ });

Top-level fields

| Field | Type | Default | Description | |-------|------|---------|-------------| | storeName | string | — | Display name of the store | | version | string | "0.0.1" | Semantic version of the store configuration | | database | DatabaseConfig | required | Primary database connection | | databaseAdapter | DatabaseAdapter | — | Pre-built database adapter. When provided, bypasses database config. | | auth | AuthConfig | See defaults | Authentication and authorization settings | | entities | Record<string, EntityConfig> | — | Custom entity type definitions keyed by entity slug | | cart | CartConfig | See defaults | Cart behavior and hooks | | checkout | CheckoutConfig | See defaults | Checkout hooks | | orders | OrdersConfig | See defaults | Order lifecycle hooks | | inventory | InventoryConfig | See defaults | Inventory hooks | | shipping | ShippingConfig | — | Shipping calculation strategy | | payments | PaymentAdapter[] | — | Payment gateway adapters | | storage | StorageAdapter | — | File/media storage adapter | | email | EmailAdapter | — | Transactional email sender | | tax | TaxConfig | — | Tax calculation adapter and origin address | | analytics | AnalyticsConfig | — | Analytics and reporting settings | | search | SearchConfig | — | Search adapter and facet defaults | | jobs | JobsConfig | — | Background job processing | | schema | Array<Record<string, unknown>> | — | App-level Drizzle table definitions merged at boot. Must also add file paths to drizzle.config.ts. | | hooks | Record<string, Array<Function>> | — | Global hook functions keyed by hook name (e.g., "orders.afterCreate") | | plugins | CommercePlugin[] | — | Plugin config-transform functions, applied in array order | | logLevel | "fatal" \| "error" \| "warn" \| "info" \| "debug" \| "trace" | "info" | Pino log level | | rateLimits | RateLimitsConfig | See defaults | Per-tier rate limiting thresholds (requests per minute) | | middleware | MiddlewareHandler[] | — | Hono middleware applied to all routes | | routes | (app: Hono, kernel: unknown) => void | — | Callback to register custom Hono routes. Cast kernel to Kernel to access services and database. |

---

DatabaseConfig

database: {
  provider: "postgresql";
  options?: Record<string, unknown>;
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | provider | "postgresql" | required | Database provider. PostgreSQL is the only supported database. | | options | Record<string, unknown> | — | Provider-specific connection options |

---

RateLimitsConfig

rateLimits: {
  api?: number;
  auth?: number;
  checkout?: number;
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | api | number | 100 | Max requests per minute for general API routes | | auth | number | 10 | Max requests per minute for authentication endpoints | | checkout | number | 5 | Max requests per minute for checkout creation |

When a client exceeds the limit, the server responds with 429 Too Many Requests.

---

AuthConfig

interface AuthConfig {
  defaultOrganizationId?: string;
  strictOrgResolution?: boolean;
  storeResolver?: (request: Request) => string | null | Promise<string | null>;
  requireEmailVerification?: boolean;
  sessionDuration?: number;
  socialProviders?: Record<string, { clientId: string; clientSecret: string }>;
  twoFactor?: { enabled: boolean; requiredForRoles?: string[] };
  apiKeys?: { enabled: boolean; defaultPermissions?: string[] };
  roles?: Record<string, RoleDefinition>;
  trustedOrigins?: string[];
  enableDevKey?: boolean;
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | defaultOrganizationId | string | — | Organization ID for single-store deployments. See Identity and Store Resolution. | | strictOrgResolution | boolean | false | When true, requests where storeResolver returns null are rejected with HTTP 503. | | storeResolver | (request: Request) => string \| null \| Promise<string \| null> | — | Resolves which organization a request belongs to in multi-store SaaS deployments. | | requireEmailVerification | boolean | true | Require email verification before account activation | | sessionDuration | number | 604800 (7 days, in seconds) | Session lifetime in seconds | | socialProviders | Record<string, { clientId: string; clientSecret: string }> | — | OAuth provider credentials keyed by provider name | | twoFactor | { enabled: boolean; requiredForRoles?: string[] } | { enabled: false } | Two-factor authentication settings | | apiKeys | { enabled: boolean; defaultPermissions?: string[] } | { enabled: false } | Enable API key authentication | | roles | Record<string, RoleDefinition> | See below | Role definitions mapping role names to permission sets | | trustedOrigins | string[] | — | Origins allowed for CSRF protection | | enableDevKey | boolean | true in dev, false in prod | Enable the dev-staff-key API key. Set to false in production. |

Default roles

| Role | Permissions | |------|-------------| | owner | *:* | | admin | *:* | | manager | catalog CRUD, inventory, orders, cart | | customer | catalog:read, cart, orders:read:own, customers:read:self, customers:update:self |

RoleDefinition

interface RoleDefinition {
  permissions: string[];
}

Permissions use "module:action" or "module:action:scope" format. "*:*" grants all.

---

EntityConfig

interface EntityConfig {
  fields: EntityFieldDefinition[];
  variants: EntityVariantConfig;
  fulfillment: string;
  hooks?: EntityHooks;
}

| Field | Type | Description | |-------|------|-------------| | fields | EntityFieldDefinition[] | Custom field definitions. The catalog service validates entity metadata against these on create/update. | | variants | EntityVariantConfig | Variant support configuration | | fulfillment | string | Fulfillment strategy: "physical", "digital", "digital-download", "digital-access" | | hooks | EntityHooks | Lifecycle hooks scoped to this entity type |

EntityFieldDefinition

| Field | Type | Description | |-------|------|-------------| | name | string | Field identifier | | type | "text" \| "number" \| "boolean" \| "date" \| "json" \| "relation" \| "select" | Data type | | unit | string | Unit of measurement (for "number" fields, e.g., "g", "ml") | | schema | unknown | Validation schema for the field value | | target | string | Target entity slug (for "relation" fields) | | options | string[] | Allowed values (for "select" fields) |

EntityVariantConfig

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Whether this entity supports variants | | optionTypes | string[] | Variant option type names (e.g., ["size", "color"]) |

---

CartConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | ttlMinutes | number | 10080 (7 days) | Cart time-to-live in minutes | | hooks.beforeAddItem | BeforeHook[] | [] | Before adding an item | | hooks.afterAddItem | AfterHook[] | [] | After adding an item | | hooks.beforeRemoveItem | BeforeHook[] | [] | Before removing an item | | hooks.afterRemoveItem | AfterHook[] | [] | After removing an item | | hooks.beforeUpdateQuantity | BeforeHook[] | [] | Before updating item quantity | | hooks.afterUpdateQuantity | AfterHook[] | [] | After updating item quantity |

---

CheckoutConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | hooks.beforeCreate | BeforeHook[] | [] | Before checkout is created. May mutate checkout data. | | hooks.afterCreate | AfterHook[] | [] | After checkout completes and order is created |

---

OrdersConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | hooks.beforeCreate | BeforeHook[] | [] | Before order creation | | hooks.afterCreate | AfterHook[] | [] | After order creation | | hooks.beforeStatusChange | BeforeHook[] | [] | Before order status transition | | hooks.afterStatusChange | AfterHook[] | [] | After order status transition | | hooks.beforeDelete | BeforeHook[] | [] | Before order deletion |

---

InventoryConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | hooks.afterAdjust | AfterHook[] | [] | After an inventory level adjustment |

---

ShippingConfig

interface ShippingConfig {
  type: "flat" | "weight_based";
  flatRate: number;
  freeShippingThreshold?: number;
  brackets: Array<{ upToGrams: number; cost: number }>;
  fallbackCost: number;
}

| Field | Type | Description | |-------|------|-------------| | type | "flat" \| "weight_based" | Shipping calculation strategy | | flatRate | number | Fixed shipping cost. Used when type is "flat". | | freeShippingThreshold | number | Order subtotal above which shipping is free | | brackets | Array<{ upToGrams: number; cost: number }> | Weight-based cost brackets. Used when type is "weight_based". | | fallbackCost | number | Shipping cost when no bracket matches |

---

TaxConfig

| Field | Type | Description | |-------|------|-------------| | adapter | TaxAdapter | Tax calculation adapter instance | | defaultFromAddress.country | string | ISO country code | | defaultFromAddress.postalCode | string | Postal/ZIP code | | defaultFromAddress.state | string | State or province code | | defaultFromAddress.city | string | City name | | defaultFromAddress.line1 | string | Street address |

---

AnalyticsConfig

| Field | Type | Description | |-------|------|-------------| | models | AnalyticsModel[] | Plugin-contributed analytics model definitions | | customSchemaPath | string | Path to a directory containing custom .js analytics model files |

---

SearchConfig

| Field | Type | Description | |-------|------|-------------| | adapter | SearchAdapter | Search engine adapter instance | | defaultFacets | string[] | Facet field names returned by default in search results |

---

JobsConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | adapter | JobsAdapter | — | Background job queue adapter. When omitted, uses in-memory queue (dev only). | | tasks | TaskDefinition[] | — | Task definitions registered at startup. Each specifies a slug and handler. | | autorun.enabled | boolean | — | Enable automatic job polling | | autorun.intervalMs | number | 5000 | Polling interval in milliseconds |