create-magic-storefront 0.1.2 → 0.2.0

package/template/lib/i18n.ts

@@ -57,6 +57,22 @@ const en = {
     `${count} ${plural('en', count, { one: 'review', other: 'reviews' })}`,
   recommendUs: (percent: number) => `${percent}% recommend us`,
   leaveReview: 'Leave a review',
+  // Blog
+  blog: 'Blog',
+  allArticles: 'All articles',
+  featured: "Editor's picks",
+  readingTime: (minutes: number) => `${minutes} min read`,
+  relatedArticles: 'Read also',
+  productsInArticle: 'Products in this article',
+  wasHelpful: 'Was this article helpful?',
+  helpful: 'Yes',
+  notHelpful: 'No',
+  helpfulCount: (count: number) => `Helpful for ${count}`,
+  thanksForVote: 'Thank you for your feedback',
+  searchArticles: 'Search articles',
+  sortNewest: 'Newest',
+  sortPopular: 'Popular',
+  tag: 'Tag',
   // Product
   addToCart: 'Add to cart',
   addedToCart: 'Added to cart.',
@@ -156,6 +172,21 @@ const ru: Messages = {
     `${count} ${plural('ru', count, { one: 'отзыв', few: 'отзыва', other: 'отзывов' })}`,
   recommendUs: (percent) => `${percent}% рекомендуют нас`,
   leaveReview: 'Оставить отзыв',
+  blog: 'Блог',
+  allArticles: 'Все статьи',
+  featured: 'Выбор редакции',
+  readingTime: (minutes) => `${minutes} мин чтения`,
+  relatedArticles: 'Читайте также',
+  productsInArticle: 'Товары из статьи',
+  wasHelpful: 'Статья была полезной?',
+  helpful: 'Да',
+  notHelpful: 'Нет',
+  helpfulCount: (count) => `Полезно: ${count}`,
+  thanksForVote: 'Спасибо за отзыв',
+  searchArticles: 'Поиск по статьям',
+  sortNewest: 'Новые',
+  sortPopular: 'Популярные',
+  tag: 'Тег',
   addToCart: 'В корзину',
   addedToCart: 'Добавлено в корзину.',
   couldNotAdd: 'Не удалось добавить в корзину.',
@@ -248,6 +279,21 @@ const uz: Messages = {
   reviewsCount: (count) => `${count} ta sharh`,
   recommendUs: (percent) => `${percent}% bizni tavsiya qiladi`,
   leaveReview: 'Sharh qoldirish',
+  blog: 'Blog',
+  allArticles: 'Barcha maqolalar',
+  featured: 'Muharrir tanlovi',
+  readingTime: (minutes) => `${minutes} daqiqa o'qish`,
+  relatedArticles: "Shuningdek o'qing",
+  productsInArticle: 'Maqoladagi mahsulotlar',
+  wasHelpful: "Maqola foydali bo'ldimi?",
+  helpful: 'Ha',
+  notHelpful: "Yo'q",
+  helpfulCount: (count) => `Foydali: ${count}`,
+  thanksForVote: 'Fikringiz uchun rahmat',
+  searchArticles: 'Maqolalardan qidirish',
+  sortNewest: 'Yangilari',
+  sortPopular: 'Ommaboplari',
+  tag: 'Teg',
   addToCart: "Savatga qo'shish",
   addedToCart: "Savatga qo'shildi.",
   couldNotAdd: "Savatga qo'shib bo'lmadi.",

package/template/lib/site.ts

@@ -0,0 +1,12 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+
+/**
+ * The storefront's public origin for absolute URLs (sitemap, canonical links): `SITE_URL`, else
+ * the shop's primary domain.
+ */
+export function siteOrigin(shop: Pick<Schema<'Shop'>, 'primaryDomain'>): string {
+  return (
+    process.env.SITE_URL?.replace(/\/+$/, '') ??
+    `https://${shop.primaryDomain ?? process.env.MAGICSTORE_SHOP_DOMAIN}`
+  );
+}

package/template/llms.txt

@@ -11,12 +11,15 @@ Every storefront — hand-written or generated — imports the SDK **only** thro
 | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------- |
 | `@magicstoreai/storefront-client` | `createStorefrontClient`: one typed method per API `operationId`, `MagicStoreError`, `paginate`, `Schema<>` | anywhere, no React      |
 | `@magicstoreai/hydrogen`          | React: `MagicStoreProvider`, `useCart`, `useCustomer`, `useWishlist`, `<Money>`, `<Image>`, …               | client (`"use client"`) |
-| `@magicstoreai/hydrogen/core`     | The same state without React: `CartController`, `CustomerSessionController`, `formatMoney`, variants        | anywhere                |
+| `@magicstoreai/hydrogen/core`     | The same state without React: `CartController`, `CustomerSessionController`, `formatMoney`, variants, blog | anywhere                |
 | `@magicstoreai/hydrogen/server`   | `nextCacheFetch` (cache tags), `createWebhookHandler` (signed webhooks → revalidation)                      | server, edge            |
-| `@magicstoreai/hydrogen/seo`      | `pageMeta`, `productJsonLd`, `breadcrumbJsonLd`, `jsonLdScript`                                             | anywhere                |
+| `@magicstoreai/hydrogen/seo`      | `pageMeta`, `productJsonLd`, `articleMeta`, `articleJsonLd`, `breadcrumbJsonLd`, `jsonLdScript`              | anywhere                |
 
 Never import from `src/` or `dist/` of a package, and never call `/api/v2/storefront/…` by URL —
-call the client method. `npx create-magic-storefront check` fails on either.
+call the client method. A server component takes only components (`<Image>`, `<Money>`, …) from
+`@magicstoreai/hydrogen`, a client module; functions and classes (`paginationState`,
+`MagicStoreError`, `formatMoney`) come from `/core`, `/server`, `/seo` or
+`@magicstoreai/storefront-client`. `npx create-magic-storefront check` fails on any of these.
 
 ## Start
 
@@ -24,15 +27,15 @@ call the client method. `npx create-magic-storefront check` fails on either.
 npm create magic-storefront@latest my-shop -- --shop shop.example.uz
 ```
 
-scaffolds a Next.js App Router storefront (home from the merchant's sections, catalog, product,
-search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or install the packages:
+scaffolds a Next.js App Router storefront (home from the merchant's sections or your own, catalog,
+product, search, blog, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or install the packages:
 `npm i @magicstoreai/storefront-client @magicstoreai/hydrogen`.
 
 ## Docs
 
 - `PAGES.md` (in a scaffolded storefront; `examples/starter/PAGES.md` in the SDK repository): how to
-  build each page type — home from the `/home` sections, collection, product, search, cart,
-  checkout, account — with its data calls, cache tags, SEO and required states.
+  build each page type — home (from the `/home` sections or custom), collection, product, search,
+  blog, cart, checkout, account — with its data calls, cache tags, SEO and required states.
 - [Hydrogen catalogue](node_modules/@magicstoreai/hydrogen/CATALOGUE.md): every export with its props
   or signature, an example, and the API operations it calls. In the SDK repository:
   `packages/hydrogen/CATALOGUE.md`.
@@ -40,7 +43,8 @@ search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or install
   idempotency, retries, errors, pagination.
 - [Hydrogen README](node_modules/@magicstoreai/hydrogen/README.md): provider, hooks, server helpers.
 - The API itself (normative): the backend repository's `docs/api/v2/` — `standards.md` (wire format,
-  every error code), `authentication.md`, `cart.md`, `checkout.md`, `customer.md`, `webhooks.md`.
+  every error code), `authentication.md`, `cart.md`, `checkout.md`, `customer.md`, `blog.md`,
+  `webhooks.md`.
   Operation shapes: `Schema<'Name'>` and the client's method types, generated from the OpenAPI spec.
 
 ## Two credentials
@@ -65,8 +69,30 @@ Public catalog reads need no customer. Render them on the server with a client w
 - Lists paginate with `page` + `perPage` (default 24, max 100); read `meta.pagination`, or
   `<Pagination>`. Sorts order (`sort=-createdAt`), filters narrow (`filter[onSale]=true`).
 - A missing value is `null`, never `0` or `""`: show a fallback.
-- The home page is `GET /home`: an ordered list of sections, one `type` each
-  (`GET /theme/section-schema` has every type's JSON Schema). Render an unknown type as nothing.
+- The home page is yours to design. `GET /home` (an ordered list of sections, one `type` each;
+  `GET /theme/section-schema` has every type's JSON Schema) is optional: render it to let the
+  merchant arrange the page from the admin, or compose a custom home from catalog and content
+  data. When you render it, an unknown type renders as nothing.
+
+## Blog
+
+- Only when `shop.features.blog` is on: at least one article is readable in the response language.
+  `shop.blog` is the blog home's `{ title, description }` or `null`.
+- `blogArticlesIndex` (12 a page; `sort`, `q`, `filter[category|author|tag|featured]`),
+  `blogArticlesShow`, `blogArticlesRelated`, `blogCategoriesIndex`, `blogAuthorsIndex`. An unknown
+  `sort` or filter is `422 VALIDATION_FAILED`, never ignored.
+- Articles are strict about language: one not written in the response locale is a `404`, with no
+  fallback. Build `hreflang` only from `availableLocales` (`articleMeta` does).
+- `bodyHtml` is sanitized by the server. Split it with `articleBodyBlocks()` (`/core`, server-safe):
+  `<product-embed handle>` → a product card, `<oembed url>` → media, `<aside data-callout>` → a
+  callout. Fetch the embedded products in one `productsIndex({ query: { 'filter[handles]' } })` per
+  `embeddedProductFilters(article.products)` value, put them back in order with
+  `orderEmbeddedProducts`, and drop a marker whose product did not come back.
+- «Was this helpful?»: `useArticleVote(handle, helpfulCount)`. A guest votes as the browser
+  (`X-Anonymous-Id`, `anonymousId()`), a customer as themselves. Report reads with
+  `useAnalytics().articleView(article.id)` (`ARTICLE_VIEW`).
+- Blog reads are cached under `magicstore:pages` (`PAGES_UPDATED`); view and vote counters may be
+  up to 10 minutes old.
 
 ## Credentials in the browser