@vtex/faststore 0.0.6 → 0.0.8

package/skills/storefront-asset/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: storefront-asset
+description: FastStore extension authoring with @vtex/faststore. Scaffold a storefront Asset, write its API side (defineSubgraph) or UI side (defineComponent), and fix storefront-* Findings until vtex extension validate is green. Use when creating or editing an Asset whose asset.yaml says kind storefront.
+---
+
+# FastStore extension
+
+A FastStore extension is a **storefront Asset**: one package at `extensions/<ext>/<asset>/` whose
+`asset.yaml` says `kind: storefront`. It holds at most one **API side** (fields it adds to the
+storefront graph) and at most one **UI side** (components a store places). An extension holds at
+most one storefront Asset. The Asset depends on `@vtex/faststore` alone, and `vtex extension` loads
+the checks from that same package, so the code and its checks share one version.
+
+Run the CLI from the Account Repo root as `pnpm extension <command>`, the script
+`vtex extension init` writes. With stdout piped it prints JSON and puts its messages on stderr.
+`pnpm extension commands --json` describes every command and flag.
+
+The Asset is **green** when `pnpm extension validate <ext>` exits 0. Exit 1 means an error Finding
+and exit 2 means warnings only. An `info` Finding, such as `extension-not-installed`, leaves it
+green.
+
+## Steps
+
+1. **Check the SDK.** Run `pnpm extension validate <ext> --json`. A `provider-invalid` Finding on
+   the Asset's `package.json` that names `@vtex/faststore` ("is not a valid storefront provider")
+   means the installed SDK predates the storefront provider, and none of the checks below ran.
+   `provider-failed` means the provider threw. Either one is the human's to resolve: stop and ask
+   which `@vtex/faststore` to install. Done when neither code appears.
+2. **Create the Asset when it is missing.** On pnpm 11, first set `allowBuilds:` with
+   `esbuild: false` in the root's `pnpm-workspace.yaml`, replacing any placeholder value pnpm wrote
+   there. Without it pnpm refuses esbuild's build script, and `add` ends in `tool-failed` with the
+   Asset's `package.json` but no template. Then `pnpm extension add <ext>/<asset> --kind storefront`
+   writes the API side; add `--template ui` for the UI side. When `<ext>` is new too, pass
+   `--vendor` and `--description`: outside a terminal `add` exits 3 instead of asking. `add` writes
+   `asset.yaml`, `package.json` and the template's files, and installs their packages. An Asset that
+   `add` left without its template, or one made by hand, takes its files and `package.json` fields
+   from the side's reference. Done when the folder holds every file its sides need.
+3. **Read the side's reference, then write the change in its shapes.** A resolver, a GraphQL type,
+   a secret or data from an outside service is the API side:
+   [references/api-side.md](references/api-side.md). A React component, an editable prop or a
+   catalog key is the UI side: [references/ui-side.md](references/ui-side.md). A change that needs
+   both sides reads both, and the Asset takes the both-sides layout below.
+4. **Validate until green.** Run `pnpm extension validate <ext> --json`. For each `storefront-*`
+   Finding, apply the fix in its row of [references/findings.md](references/findings.md), then run
+   it again. Done when it exits 0.
+5. **Run the Asset's own checks.** In the Asset's folder, `pnpm typecheck`, and for an API side
+   `pnpm test`. An Asset made by hand may lack the scripts: run `pnpm exec tsc --noEmit` and
+   `pnpm exec vitest run`. Done when each exits 0.
+
+## Layout
+
+The provider reads an Asset's sides from `package.json` and two paths. A storefront `asset.yaml`
+holds the envelope and an empty body, so nothing in it changes the layout.
+
+| Side | What marks it | Entry |
+| --- | --- | --- |
+| API | `package.json#main`, or, with neither `main` nor `exports["./catalog.json"]`, `src/index.ts` | The declaration module, which `export default`s a `defineSubgraph(...)` |
+| UI | A `src/components/` directory, or `exports["./catalog.json"]` | Every `defineComponent` under `src/components/` |
+
+An Asset with both sides names its declaration through `main` (for example `api/index.ts`) and
+keeps `src/index.ts` as the component barrel. Without `main`, a `src/index.ts` beside a
+`./catalog.json` export is the barrel.
+
+The templates set these `package.json` fields, and an Asset made by hand sets them itself. Both
+sides take `"type": "module"`, a `typecheck` script and `typescript@^5.9.3` in devDependencies;
+`validate` reports `storefront-typescript-unsupported` without TypeScript 5. The API side adds
+`graphql`, `vitest` and a `test` script. The UI side adds `@types/react`, `react` as a peer, and
+these exports:
+
+```json
+"exports": {
+  ".": "./src/index.ts",
+  "./catalog.json": "./dist/catalog.json"
+}
+```
+
+A store lists the Asset's package as a dependency and compiles its components from `src/`.
+
+## Environment
+
+`dev` needs `VTEX_ACCOUNT` in the repo root's `.env`, or `STOREFRONT_CORE_URL` to override the core
+URL derived from the account. `VTEX_WORKSPACE` defaults to `master`. `VTEX_TOKEN`, which is
+optional, and the value of every secret a declaration lists go in the root's `.env.local`, which
+git ignores. Keep the Asset's folder free of `.env` files, so one place holds every value.
+`validate` reads none of them.
+
+## Running it live
+
+`dev` runs until it is stopped, so start it in the background. Start it through the CLI's bin, so a
+stop signal reaches the CLI rather than a pnpm wrapper:
+`node node_modules/@vtex/cli-plugin-extension/dist/bin/vtex-extension.js dev <ext>` from the repo
+root. It serves one local router over every API side and rebuilds each UI side's
+`dist/catalog.json` on every save under `src/`. The first run downloads the Hive Router into
+`.vtex/storefront/`, and the Assets stay `starting` until it lands.
+
+`.vtex/dev-session.json` at the repo root lists each Asset's `status` (`starting`, `ready` or
+`failed`), its `findings`, and, once `ready`, its `details`: the router `url`, the `subgraph` and
+the `catalog`. Query the router `url`; the subgraph's port changes on every reload. A Finding
+leaves the Asset `ready`, so read `findings` after each save. The file's shape is provisional.
+
+One session runs per repo, and a second `dev` exits 1 and names the running one. SIGTERM or SIGINT
+stops it with exit 0 and removes the file.
+
+## Building it
+
+`pnpm extension build <ext>` validates first, then writes each Asset's output to
+`.vtex/build/<ext>/<asset>/` (`--out <dir>` puts it under another root). The API side emits
+`server.mjs` and `extension.graphql`. The UI side emits `catalog.json`, `content-types.json` when
+there is one, and `docs/`. An Asset with an error Finding is `failed` and leaves no folder. The
+output is what the pipeline collects; the UI side's `catalog.json` also lands in the Asset's `dist/`,
+where its export points, so a store build finds it. `--json` prints each Asset's status.

package/skills/storefront-asset/references/api-side.md

@@ -0,0 +1,153 @@
+# The API side
+
+The API side is one declaration module: `src/index.ts`, or the file `package.json#main` names when
+the Asset has a UI side too.
+
+## The declaration
+
+```ts
+import { defineSubgraph, gql } from '@vtex/faststore/graphql';
+
+const REVIEWS_BY_SLUG: Record<string, Array<{ id: string; rating: number; text: string }>> = {
+  'sample-product-slug': [{ id: '1', rating: 5, text: 'Replace this with data from your own source.' }],
+};
+
+export default defineSubgraph({
+  vendor: 'acme',
+
+  typeDefs: gql`
+    extend type Product @key(fields: "slug") {
+      slug: String! @external
+      reviews: [Review!]!
+    }
+
+    type Review {
+      id: ID!
+      rating: Int!
+      text: String!
+    }
+  `,
+
+  extends: ['Product'],
+
+  resolvers: {
+    Product: {
+      reviews: (product: { slug: string }) => REVIEWS_BY_SLUG[product.slug] ?? [],
+    },
+  },
+});
+```
+
+`@vtex/faststore/graphql` exports `defineSubgraph`, `gql` and the types `SubgraphContext`,
+`SubgraphDefinition` and `SubgraphResolvers`. `defineSubgraph` returns its argument unchanged; the
+provider builds the schema from it.
+
+| Field | What it is |
+| --- | --- |
+| `vendor` | Required. Matches `^[a-z][a-z0-9]*$`: lowercase letters and digits, starting with a letter. It prefixes every name the Asset contributes. |
+| `typeDefs` | SDL in a `gql` tag, with bare names. Write `@key` and `@external` on the entity you extend; the provider injects the federation preamble. |
+| `extends` | The core entities the SDL extends. `Product`, keyed by `slug`, is the only one. |
+| `resolvers` | Keyed by bare names. The provider renames the keys to the prefixed names and adds each entity's `__resolveReference`. |
+| `secrets` | Optional. The environment names the resolvers read; see Secrets. |
+| `name` | Optional. The subgraph name; the package name by default. |
+
+## The vendor prefix
+
+The build prefixes every name the Asset contributes with `<vendor>_`: fields added to `Product`,
+root `Query` and `Mutation` fields, and each declared type with every reference to it. The
+declaration above exposes `Product.acme_reviews` of type `[acme_Review!]!`. Write bare names in the
+declaration and let the build add the prefix. The `@key` field of an extended entity keeps its core
+name.
+
+## The resolver context
+
+A resolver's third argument has exactly these five keys:
+
+| Key | Value |
+| --- | --- |
+| `ctx.account` | The `x-vtex-account` header, `''` when absent |
+| `ctx.workspace` | The `x-vtex-workspace` header, `''` when absent |
+| `ctx.headers` | `x-vtex-locale`, `x-vtex-segment` and `x-vtex-session`, each only when the request carried it |
+| `ctx.token` | The raw `authorization` header, `''` when absent |
+| `ctx.secrets` | The declared secret names that are set, mapped to their values |
+
+```ts
+import type { SubgraphContext } from '@vtex/faststore/graphql';
+
+const reviews = (product: { slug: string }, _args: unknown, ctx: SubgraphContext) =>
+  fetchReviews(product.slug, { apiKey: ctx.secrets.ACME_API_KEY, account: ctx.account });
+```
+
+## Secrets
+
+`secrets: ['ACME_API_KEY']` declares the environment names the Asset reads. Each name matches
+`^[A-Z][A-Z0-9_]*$`. The provider rejects `PATH`, `HOME`, `PWD`, `SHELL`, `TMPDIR` and any name
+that starts with `VTEX_` or `NODE_`. A declared name that is not set is absent from `ctx.secrets`;
+`dev` logs one warning for each. Values come from the repo root's `.env` and `.env.local`; keep
+secret values in `.env.local`, which git ignores. A resolver reads them through `ctx.secrets` only.
+
+## The capability boundary
+
+The provider lints the declaration and every `./` or `../` module it imports. Each rule is an error
+Finding at the line it flags:
+
+| Rule | What it flags | What to write instead |
+| --- | --- | --- |
+| `process-env` | Any `process.env` member access | Declare the name in `secrets` and read `ctx.secrets` |
+| `fs-import` | A runtime import of `fs` or `fs/promises`, bare or `node:` | Fetch the data from a service |
+| `child-process-import` | A runtime import of `child_process` | Call a service over HTTP |
+
+Static `import`, `import x = require()`, `require()`, dynamic `import()` and value re-exports all
+count; type-only imports do not. The lint does not walk packages, so route every secret through `ctx.secrets` even when a
+dependency could read the environment: the deployed server scrubs the declared names from its
+environment after boot.
+
+## The test
+
+`src/index.test.ts` sits beside the declaration. It builds the subgraph with `buildSubgraph` from
+`@vtex/faststore/cli` and resolves the field through `_entities`, the join a federated query makes:
+
+```ts
+import { buildSubgraph } from '@vtex/faststore/cli';
+import { graphql } from 'graphql';
+import { describe, expect, it } from 'vitest';
+import definition from './index';
+
+describe('acme extension', () => {
+  it('builds a subgraph and resolves the sample field via _entities', async () => {
+    const schema = buildSubgraph(definition);
+
+    const result = await graphql({
+      schema,
+      source: `
+        query ($representations: [_Any!]!) {
+          _entities(representations: $representations) {
+            ... on Product {
+              acme_reviews {
+                rating
+                text
+              }
+            }
+          }
+        }
+      `,
+      variableValues: {
+        representations: [{ __typename: 'Product', slug: 'sample-product-slug' }],
+      },
+    });
+
+    expect(result.errors).toBeUndefined();
+    const entities = result.data?._entities as Array<{ acme_reviews: Array<{ rating: number }> }>;
+    expect(entities[0]?.acme_reviews[0]?.rating).toBe(5);
+  });
+});
+```
+
+The test sees the built schema, so it queries the prefixed name (`acme_reviews`). `buildSubgraph`
+and `_entities` are the whole surface a test uses.
+
+## What validate checks here
+
+`validate` runs the capability lint, loads the declaration and builds the subgraph, which is where
+the `vendor` grammar, the `extends` list, the secret names and the SDL fail. It then composes the
+slice with the storefront core schema. `dev` runs the same checks at boot and on every save.

package/skills/storefront-asset/references/findings.md

@@ -0,0 +1,40 @@
+# The Findings
+
+Every code `vtex extension validate` reports for a storefront Asset. All are errors. `file` is
+relative to the repo root, and a Finding with a `range` points at its line and column. `dev` reports
+the API-side and UI-side codes for the same faults and replaces them on every reload, and never the
+two kind rules. `build` validates each Asset first, so it reports every code `validate` does before
+it writes, plus `storefront-build-failed`.
+
+## The Asset's code
+
+| Code | Trigger | On | Fix |
+| --- | --- | --- | --- |
+| `storefront-typescript-unsupported` | The Asset's `typescript` is missing or has no TypeScript 5 compiler API, so the capability lint did not run | `package.json` | `pnpm add -D typescript@^5.9.3` in the Asset's folder |
+| `storefront-capability-process-env` | A `process.env` member access in the declaration or a module it imports | The source line | Declare the name in `secrets` and read `ctx.secrets` |
+| `storefront-capability-fs-import` | A runtime import of `fs` or `fs/promises` | The source line | Fetch the data from a service; a resolver has no filesystem |
+| `storefront-capability-child-process-import` | A runtime import of `child_process` | The source line | Call a service; a resolver spawns no process |
+| `storefront-declaration-invalid` | `main` names no file; the declaration does not bundle or import; it does not `export default defineSubgraph(...)`; or the build rejects it: a `vendor` outside `^[a-z][a-z0-9]*$`, an `extends` entry other than `Product`, a `@key` other than `slug`, a secret name outside the grammar, or SDL that does not parse | The declaration entry | The message names the field or the SDL error. On a UI-only Asset's `src/index.ts`, add `exports["./catalog.json"]`: without it the barrel was read as a declaration |
+| `storefront-composition-failed` | The built slice does not compose with the storefront core schema: a type or field that collides with core's, or a federation directive the composer rejects. In `dev`, also a conflict between two Assets' slices | The declaration entry | Change the SDL as the message says. Keep `@key(fields: "slug")` on `Product` and bare names elsewhere |
+| `storefront-catalog-export-missing` | The Asset has `src/components/` and `package.json#exports` has no `./catalog.json` key | `package.json` | Add `"./catalog.json": "./dist/catalog.json"` and `".": "./src/index.ts"` to `exports` |
+| `storefront-catalog-export-invalid` | The `./catalog.json` export names no file, or a path that is not `./`-relative, has `..` or resolves outside the Asset through a link; `dev` and `build` write where it points, so the catalog goes to `dist/` meanwhile | `package.json` | Point the export at a file inside the Asset: `"./catalog.json": "./dist/catalog.json"` |
+| `storefront-catalog-invalid` | The catalog build threw: no component under `src/components/` (`NoExtensionComponents`), two components with one name, a fragment spread with no definition (`UnresolvedSpread`), no `package.json#name` (`MissingPackageName`), or a top-level `defineActions` | `package.json` | The message names the file or component. Add a `defineComponent`, rename the duplicate, drop the spread, set `name`, or remove `defineActions` |
+| `storefront-build-failed` | The build step after `validate` passed failed: no or invalid `tsconfig.json`, a TypeScript diagnostic, the `server.mjs` bundle, two component docs sharing a basename, or the catalog | `package.json` | The message is the runner's error. Fix what it names and run `pnpm extension build` again |
+
+`storefront-declaration-invalid`, `storefront-catalog-invalid` and `storefront-build-failed` carry
+the build's own error verbatim in their message: read it before changing code.
+
+## The kind rules
+
+`validate` and `build` check these before either side; `dev` does not.
+
+| Code | Trigger | On | Fix |
+| --- | --- | --- | --- |
+| `storefront-one-per-extension` | The extension already has a storefront Asset, and this one is its second | The Asset's `asset.yaml`, at `kind` | Merge the two into one Asset with both sides, or move this one to its own extension |
+| `storefront-store-extension-not-installed` | A store under `stores/` depends on the Asset's package, and an account that uses that store does not list the extension under `installed:` in `accounts.yaml` | The store's `package.json` | Add `<vendor>.<ext>@<range>` to each such account's `installed:`, or drop the dependency |
+
+## The provider's own faults
+
+`provider-invalid` on the Asset's `package.json` means the installed `@vtex/faststore` has no
+storefront provider. `provider-failed` means the provider threw. Both belong to the SDK, so the
+human decides which `@vtex/faststore` to install.

package/skills/storefront-asset/references/ui-side.md

@@ -0,0 +1,94 @@
+# The UI side
+
+The UI side is the set of components under `src/components/`, each registered with
+`defineComponent` from `@vtex/faststore`, and the barrel `src/index.ts` a store imports them from.
+The provider builds a catalog of the registrations. A store reads the catalog to place the
+components and compiles them from `src/`; the Asset ships no JavaScript build.
+
+## A component
+
+```tsx
+import { defineComponent } from '@vtex/faststore';
+import type { ComponentPropsWithRef } from 'react';
+
+/** Props for {@link HeroBanner}. Extends all native `<section>` attributes. */
+export type HeroBannerProps = ComponentPropsWithRef<'section'> & {
+  /** The headline text. */
+  title?: string;
+};
+
+export const HeroBannerDefinition = defineComponent<HeroBannerProps>({
+  name: 'HeroBanner',
+  importPath: '@acme/reviews-ui',
+  component: HeroBanner,
+  editor: { label: 'Hero Banner', category: 'content' },
+  schema: {
+    title: { type: 'string', label: 'Title' },
+  },
+});
+
+export function HeroBanner({ title, className, ...props }: HeroBannerProps) {
+  return (
+    <section {...props} className={className} data-fs-hero-banner="">
+      <h1>{title}</h1>
+    </section>
+  );
+}
+```
+
+| Field | What it is |
+| --- | --- |
+| `name` | The exported function's name. |
+| `importPath` | The Asset's `package.json#name`. A store imports the component from there. |
+| `component` | The function. A function declaration hoists, so the definition may come first. |
+| `editor` | `label`, the name an editor shows, and `category`, a free string that groups it. `description` and `icon` are optional. |
+| `schema` | The editable props. Each has a `type` (`string`, `number`, `boolean`, `object`, `array` or a list of string literals), an optional `label` and an optional `default`; an `array` may name its allowed elements in `items`. Values are serializable: strings, numbers, booleans, objects and arrays of them. |
+
+The provider finds definitions by a static scan of `src/components/`, recursive, skipping
+`*.test.tsx`, `*.stories.tsx` and `generated/`. Export each one as a top-level `const` named
+`<Component>Definition` whose argument is an object literal.
+
+The root element carries `data-fs-<component>=""` as its identity, and `data-fs-<component>-<prop>`
+for each prop that changes its look. The component accepts `className` and renders it. A store
+styles it through those attributes, so the component ships no CSS.
+
+## The barrel
+
+`src/index.ts` re-exports every component and its definition:
+
+```ts
+export type { HeroBannerProps } from './components/HeroBanner';
+export { HeroBanner, HeroBannerDefinition } from './components/HeroBanner';
+```
+
+It is the `exports["."]` target. With `exports["./catalog.json"]` set, the provider reads it as the
+barrel, never as a declaration.
+
+## The catalog
+
+Each registration becomes one catalog entry keyed `<packageName>:<Component>`, for example
+`@acme/reviews-ui:HeroBanner`. The package name, taken verbatim from `package.json#name`, is the
+namespace, so two Assets never collide.
+
+`dev` builds `dist/catalog.json` at boot and on every save under `src/`; `exports["./catalog.json"]`
+points there, and git ignores `dist/`. `build` writes the same file there beside its output folder,
+so a store built after `pnpm extension build` finds it without a `dev` loop. `validate` builds the
+catalog into the Asset's `.vtex/storefront/` scratch folder and leaves `dist/` as it is. A failed
+build keeps the previous `catalog.json` until the next save fixes it.
+
+A store sees the Asset as a UI side through the `./catalog.json` export alone. Without it, no store
+sees the components, and `validate` reports `storefront-catalog-export-missing`. The export must
+name a `./` path inside the Asset, since `dev` and `build` write the catalog where it points; one
+that does not is `storefront-catalog-export-invalid`, and the catalog goes to `dist/` meanwhile.
+
+## Props and content only
+
+Keep each component to its props and editor content. A GraphQL fragment spread fails the catalog
+build with `UnresolvedSpread` (reported as `storefront-catalog-invalid`), because no convention yet
+names where a storefront Asset's generated fragments live.
+
+## What validate checks here
+
+`validate` fails a UI side whose `package.json` lacks the `./catalog.json` export, whose
+`src/components/` declares no component, that has two components with one name, or that spreads a
+fragment with no definition.

package/src/styles/tailwind.css

@@ -63,4 +63,31 @@
   [data-fs-card-entry-fieldset] {
     min-inline-size: 0;
   }
+
+  /* Baseline look and viewport bound for the select popup. Nothing else styles it, and a matter-composed
+     popup is portaled out of reach of a store's descendant selectors, so unstyled it is transparent text
+     drawn over the next field, content-wide and free to run past the viewport. `--anchor-width` and
+     `--available-height` are set on the positioner by Base UI; the latter bounds the popup (not the list)
+     to the viewport. Preflight's `border-box` counts the 1px border inside that bound, and the flex column
+     hands the leftover height, minus any composed scroll arrows, to the list, so a tall popup never
+     overruns the viewport by the border or the arrows. `@layer base` so any merchant utility class (`max-h-60`,
+     `overflow-*`) outranks it under Tailwind 4's layer order. */
+  [data-fs-select-popup] {
+    max-height: var(--available-height);
+    display: flex;
+    flex-direction: column;
+    min-width: var(--anchor-width);
+    background-color: var(--color-bg);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+  }
+
+  /* The list, not the popup, is the scroll container: that is the Select contract (`SelectList` is the
+     "scrollable container"), and Base UI's scroll arrows watch the list's scroll position, so a popup
+     that scrolled instead would leave them inert. `min-height: 0` lets the flex item shrink below its
+     content so the popup's bound reaches it. */
+  [data-fs-select-list] {
+    min-height: 0;
+    overflow-y: auto;
+  }
 }