A Next.js App Router starter for @ominity/next: CMS pages,
commerce, sign-in and customer accounts, built on the Ominity TypeScript SDK as is.
- The SDK directly. Server components call
ominity(locale)and client componentsuseOminitySdk(); both are the plain@ominity/api-typescriptclient and use its types (Product,Category,Cart,Order, …). Nothing is wrapped. - One provider.
src/components/providers.tsxrendersOminityProvider; components use the hooks from@ominity/next/react(useAuth,useUser,useCustomer,useCart,useCheckout,useOrders, …). - One route file for the API.
src/app/api/[...ominity]/route.tsserves everything the browser needs (sign-in, cart and checkout, customer accounts, the SDK gateway, tracking, forms, draft mode, dev tool). - One page file.
src/app/[[...path]]/page.tsxresolves every URL to a CMS page, product, category or one of the starter's own pages, for every locale strategy, and renders it with that page's view fromsrc/app/[[...path]]/_views(cms,commerce,auth,account). - Tailwind CSS and shadcn-style UI components.
npm install
cp .env.example .env.local
npm run devSet at least OMINITY_API_URL and OMINITY_API_KEY, plus OMINITY_AUTH_CLIENT_ID, OMINITY_AUTH_CLIENT_SECRET and
OMINITY_AUTH_SESSION_SECRET for sign-in. Open http://localhost:3000.
src/
app/
[[...path]]/page.tsx every page: resolves the URL, renders its view
[[...path]]/_views/ what each kind of page renders, by domain: cms, commerce, auth, account
api/[...ominity]/route.ts every API route, from @ominity/next/routes
layout.tsx, not-found.tsx, sitemap.ts
lib/
ominity/config.ts environment
ominity/sdk.ts ominity(locale): the server SDK (API key, server-only)
ominity/site.ts channel, routing, link resolver
ominity/routes.ts the starter's own pages and their localized paths
ominity/pages.ts URL → page resolution
ominity/registry.tsx CMS component registry
locales/routes/{lang}.json localized paths: login (`auth/login`), cart, checkout, account, product (`p/{sku}-{slug}`), …
locales/ui/{lang}.json UI copy
components/
providers.tsx one OminityProvider for auth, accounts, cart, wishlist, tracking, dev tool
auth/, account/, commerce/ sign-in, account portal, cart → checkout → payment
cms/, site/, ui/ CMS blocks, header, shadcn-style UI
In a server component:
import { ominity } from "@/lib/ominity/sdk";
const products = await ominity(locale).commerce.products.list({ include: "offers", limit: 24 });In a client component, through the gateway route with the signed-in user's session (no API key in the browser):
import { useOrders, useOminityCustomerSdkPaginatedQuery } from "@ominity/next/react";
const orders = useOrders({ pageSize: 10 });
// Anything without a dedicated hook is the SDK itself:
const payments = useOminityCustomerSdkPaginatedQuery(
(sdk, { customerId, page, limit, signal }) => sdk.commerce.customerPayments.list({ customerId, page, limit }, { signal }),
);See docs/architecture.md.
- Add its path to
src/locales/routes/{lang}.json, e.g."returns": "account/returns". - Add its view to the domain file in
src/app/[[...path]]/_views(title, optionalmetadata,render). The type check fails until every route has a view.
Remove a feature by deleting its route entries, its views and its components.
docs/architecture.mddocs/configuration.mddocs/routing.mddocs/commerce.mddocs/auth.mddocs/customer-accounts.mddocs/component-registry.mddocs/forms.md
npm run dev·npm run build·npm run start·npm run lint·npm run typecheck
-
OMINITY_API_URL,OMINITY_API_KEY,NEXT_PUBLIC_SITE_URL -
OMINITY_AUTH_CLIENT_ID,OMINITY_AUTH_CLIENT_SECRETand a realOMINITY_AUTH_SESSION_SECRET -
OMINITY_LOCALE_SEGMENT_STRATEGYand the paths insrc/locales/routes -
OMINITY_CHECKOUT_ALLOW_GUEST,OMINITY_TRACKING_ENABLED,OMINITY_DRAFT_TOKEN -
OMINITY_DEV_TOOL=false - Check canonical redirects and
/sitemap.xml