# Nyxel ## Bridge theme URL: /docs/bridge A future Liquid companion for Shopify-native theme app blocks that cannot render headlessly. Bridge theme Some Shopify apps expose theme app extensions that Shopify renders through Liquid theme infrastructure. An Astro storefront cannot execute those app blocks directly. Bridge is a future, narrowly scoped Liquid companion for stores that need one of those surfaces. It is not another implementation of the storefront. Intended responsibility Bridge would publish a minimal Shopify theme capable of rendering an approved app block on a Shopify-owned route. The Astro storefront could embed that result when an iframe is acceptable, with explicit sizing, loading, and error behavior. Display-oriented widgets such as reviews, loyalty summaries, or sizing tools are the clearest candidates. SEO-critical markup, cart mutations, customer identity, and scripts that assume full theme ownership require separate evaluation. Required safeguards A Bridge integration needs an explicit assignment between an app block and an Astro placement, a stable origin policy, responsive iframe sizing, and clear behavior in Shopify theme preview. It must not redirect ordinary storefront traffic into a partial Liquid theme. The hosted platform also needs to explain which surface owns configuration and how a merchant diagnoses an unavailable block. Until those requirements are implemented, Bridge remains future work rather than a hidden dependency of the core storefront. --- ## CLI URL: /docs/cli Run Nyxel development, validation, inspection, generation, build, and smoke commands. CLI @nyxel/cli is the repository’s command-line entry point for theme development and validation. It is available through the monorepo after pnpm install. There is no global installation or project scaffolder yet. Run the binary through the root script or pnpm exec nyxel. Develop From the repository root, pnpm dev builds the Node-consumed packages and starts the contract watchers, Astro storefront, and editor host. Add --verbose when you need the raw process output. For one application, use its package filter or run nyxel dev --storefront from apps/storefront. Validate a component After changing a component contract or template, start with the storefront check: It performs static extraction, manifest validation, template validation, component usage checks, and the Astro host typecheck. Add --fast for extraction and manifest validation only while iterating, or --json when another tool needs structured diagnostics. Use inspection commands when the extracted result is unclear: inspect component shows the source contract, renderer, normalized manifest, generated entry, and diagnostics. doctor checks the Node version, Astro integration, renderer adapters, Canvas and Preview endpoints, TypeScript setup, and required project paths. Cross-surface gates The storefront check does not validate the editor library or every public package. Use the broader commands at a coherent handoff or release boundary: check:handoff covers component contracts, runtime, adapters, Astro integration, storefront, editor library, and editor host. smoke exercises the live HTTP contracts and therefore requires the storefront and editor services. check:packages inspects packed exports. build verifies every application and package in dependency order. Generate and build The generator creates a typed section or block shell: nyxel build validates the storefront registry before the production Astro build. Generated code is a starting point; choose settings and regions that express the component’s real behavior, then verify it in Canvas and Preview. --- ## Nyxel Connect URL: /docs/connect The Shopify-facing provisioning and release control plane. Nyxel Connect Partial: Nyxel Connect is the Shopify-facing host for projects, provider connections, revisions, and releases. It establishes the production ownership boundary without placing provider credentials or durable deployment work in the storefront or editor. The repository contains a framework-neutral @nyxel/connect package and a standalone apps/connect SvelteKit host. The state machine, Shopify installation flow, Redis storage, scoped editor handoff, GitHub/Vercel clients, review deployment, and scheduled promotion routes are implemented and checked in the monorepo. It is not a finished hosted service. Customer-owned GitHub App and Vercel authorization, webhook reconciliation, rollback, and a live merchant release still need end-to-end proof. !Nyxel Connect showing provider readiness, merchant onboarding, and the release model. Four authorities Connect coordinates four systems without pretending to replace them: | Authority | Owns | | --------- | ------------------------------------------------------------------------------------ | | Shopify | Installation identity, catalog, commerce data, and checkout | | GitHub | The customer-owned storefront repository and generated commits | | Vercel | Project configuration, Preview deployments, and production deployment artifacts | | Nyxel | Project identity, document revisions, release state, and bounded editor capabilities | A Nyxel Project stores stable provider resource IDs rather than relying on repository, team, or domain names that can change. Provider access tokens remain server-only. Editor handoff Connect creates a single-use authorization code for one Project. The standalone editor exchanges it for an encrypted, short-lived capability, removes the code from the URL, and scopes subsequent document, Canvas, Preview, and Release requests to that Project. The editor does not receive Shopify, GitHub, Vercel, or Redis credentials. Connect proxies the narrow operations it is allowed to perform and rejects requests for another Project. Release states Saving documents is not publishing. Creating a Release captures an immutable Revision, writes that saved document set to a release branch, creates a Vercel Preview, and becomes ready only after the deployment is ready. A ready Release can be promoted immediately or scheduled. The scheduled worker acts from the durable Release record rather than browser state. Closing the editor therefore cannot cancel a confirmed schedule. Failed provider operations stay attached to the Release instead of being represented as a vague Save error. Current limit The implementation currently uses server-side bootstrap credentials for GitHub and Vercel. The intended customer-owned authorization model is still Planned, and the full flow has not been live-proven. The public Nyxel demo does not expose Review or Publish controls. Bridge is optional. It will only be provisioned when a merchant needs an approved Shopify Liquid app-block surface; it is never the primary storefront. --- ## Content models URL: /docs/content-models Decide which content belongs in Shopify and which presentation belongs in Nyxel. Content models Nyxel uses Shopify as the durable source for commerce and structured store content. It does not introduce a second database for products, collections, pages, metafields, or metaobjects. Choose the owner by meaning Content belongs in Shopify when it describes the business or a commerce resource independently of one page layout. Product specifications, collection descriptions, store locations, size guides, FAQ entries, and reusable editorial records are examples. Nyxel owns how that content appears: which section renders it, where that section sits, which layout variant is selected, which color scheme applies, and which source path supplies a setting. | Question | Owner | | --------------------------------------------------------------- | ---------------------------- | | What is the product title, price, inventory, or featured image? | Shopify | | Which testimonials or FAQ records exist? | Shopify metaobjects | | Where does the testimonial section appear? | Nyxel template | | How many columns and which color scheme does it use? | Nyxel component settings | | Which metaobject list feeds it? | Nyxel dynamic-source binding | This division avoids synchronization work and gives an author one clear place to change each kind of information. Metaobjects Shopify metaobjects are a good fit for reusable structured records. A metaobject definition can represent a testimonial, feature, store location, size guide, or campaign record. Nyxel can then bind a compatible component setting or repeater to the route’s resolved metaobject data. The component contract should express the presentation it needs, not mirror the entire remote schema. For example, a testimonial card might accept quote, attribution, and portrait settings. The binding layer maps those settings to fields on the selected metaobject. Future authoring support The runtime already supports explicit source paths and resource-shaped values. Future platform work can add richer metaobject discovery, field-aware pickers, and safer list previews while keeping Shopify authoritative. Nyxel does not need a parallel content-model designer to provide those improvements. The editor can surface Shopify definitions and let the component contract determine which fields are compatible. --- ## Dynamic sources URL: /docs/dynamic-sources Bind component settings and repeaters to Shopify route and commerce data. Dynamic sources A dynamic source connects a component setting to data already available for the active storefront route. It lets one template describe many products, collections, pages, or articles without copying resource values into template JSON. !Nyxel collection route showing products supplied by collection data, with filtering and sorting. Static values and bindings A setting usually resolves from either a stored value or a binding: The first value is authored directly. The second reads featuredImage from the product in the current source frame. The component receives both as ordinary resolved values; it does not need to know which one came from a binding. The Inspector shows a source picker only when a setting and source value are compatible. Text settings can bind to textual fields, media settings to images, resource settings to matching Shopify resources, and list-capable settings to lists. Source scopes The route loader creates a source context for the page. Common scopes include product, collection, page, blog, article, cart, and shop. A repeater adds a local frame for each item, which makes scopes such as closest:product or closest:line available to descendants. Use the narrowest meaningful scope. A product card inside a collection loop should bind to closest:product; a product-page hero can bind to the route-level product. This keeps the component reusable when it moves into another composition. Lists and repeaters The loop block reads a list source and renders its child region once per item. Each iteration creates a new source frame, so nested blocks can bind to the active item without receiving manually threaded props. A collection grid commonly uses this shape: The collection route remains responsible for pagination, filters, sorting, locale, and market. The loop is responsible for presentation of the supplied list. Resolution rules Resolution is deterministic. The runtime validates the binding shape, locates its scope, walks the path, coerces the result according to the setting definition, and falls back to the contract default when the value is missing or incompatible. Canvas receives serialized source data in its render request. Preview and public routes build request-scoped sources through Astro middleware and route loaders. Components therefore use the same binding semantics in all three surfaces. Resource pickers Resource pickers store a Shopify reference when an author chooses a specific item. Starter templates should stay store-independent. When a preset needs representative route data, bind to a route scope or a built-in default resource rather than embedding a gid://shopify/... value. Metaobjects and metafields can participate in the same model as their query and editor support expands. See Content models for the ownership boundary. --- ## Editor hosting URL: /docs/editor-platform/hosting-study The supported split-origin editor model and a future same-origin deployment option. Editor hosting Nyxel runs the editor and storefront as separate applications. In local development the editor connects to the storefront over CORS-enabled development endpoints; in production a platform service will authenticate and proxy the equivalent operations. Why the applications stay separate The storefront serves merchant HTML and executes theme components. The editor manages privileged documents, drafts, selection state, and authoring controls. Separate builds prevent theme CSS and component dependencies from entering editor chrome and make it possible to deploy the two surfaces under different security policies. @nyxel/editor remains portable because it receives data and callbacks rather than importing storefront modules. Canvas uses a renderer interface and Preview uses a route URL, so the library does not depend on a particular hosting topology. Optional same-origin profile A platform may place both applications behind one public origin through an authenticated proxy. That can simplify cookies and demonstrations, but it does not combine their packages or trust boundaries. Any same-origin profile must preserve development endpoint isolation, Shadow DOM CSS boundaries, Preview session authorization, route precedence, and the same storefront/editor browser workflows as the split-origin model. It should be introduced only when the production authentication and deployment design can enforce those invariants. --- ## Visual Editor URL: /docs/editor How Canvas, Preview, the Navigator, the Inspector, and document actions work together. Visual Editor The editor is a standalone Svelte application. It connects to a storefront over HTTP, loads its component registry and JSON documents, and edits those documents through a typed action API. !Nyxel editor showing a product page Canvas, page tree, and section Inspector. The everyday workflow Choose a template, select a node in the Navigator or Canvas, then change its settings in the Inspector. The active page is split into Header, Template, and Footer so shared shell content remains separate from route content. Canvas starts with desktop and mobile artboards on a wide screen. Each artboard header opens a resolution menu with desktop, laptop, tablet, and phone presets; removal is the final destructive action in that menu. Circular controls before, between, and after the artboards insert another frame, briefly highlight it, and provide a timed quick-remove state. Adding and removing frames animates both layout reflow and the bounded viewport, with reduced-motion support. A compact minimap shares one surface with recenter and zoom controls. On a constrained editor viewport the Navigator or Inspector appears in a bottom sheet. Canvas pages grow to the height of their rendered sections; the editor stage supplies pan and zoom instead of placing an independent storefront scrollbar inside each artboard. Selection outlines and labels use the editor accent color. Canvas remains selectable while the Inspector is available. Preview disables editing controls because it represents the interactive storefront, not an editable overlay. In the Editor view, the Preview control also owns responsive inspection: click it again to switch the live route between desktop and mobile widths. The Library keeps a separate resizable layout control for isolated component work. Canvas rendering The editor owns the current Yjs drafts and projects them to JSON for every render request. The storefront’s development render endpoint composes that snapshot with the same Astro runtime used by public routes and returns HTML, CSS, asset URLs, head metadata, markers, and diagnostics. The editor installs the response into Shadow DOM. Revision numbers make the request race-safe: an older response cannot overwrite a newer edit. If rendering fails, the last successful Canvas remains visible and the editor shows the new diagnostic separately. Canvas does not hydrate storefront components. Links, submissions, and cart actions are intercepted, and the storefront snapshot uses a regular cursor rather than suggesting that those controls will activate. Node selection reads data-nyxel-* markers from the local DOM, so hover and click feedback do not wait for another server render. Initial renders and mode changes show a preparation state; later render requests keep the last successful Canvas visible while an update indicator reports the pending resolution. Preview sessions Preview loads the actual storefront route with a development-only snapshot token. Unsaved page, group, and theme changes are therefore visible before Save. Links preserve the session while the user navigates between supported routes. Preview is read-only from the editor’s perspective, but storefront interaction remains real. Selecting a node in the Navigator can focus the corresponding labeled section on the live route without adding editing controls to Preview. The focus treatment clears sticky storefront chrome, then disappears when Preview is opened without a selection. Product options, add-to-cart, collection filters, search, and other hydrated behavior should be verified there. !Nyxel Preview focused on the section selected in the Navigator while the storefront route remains interactive. Documents, actions, and undo Header, page, footer, and theme settings each have a local Yjs document. They keep separate persistence boundaries while an editor session coordinates selection, rendering, and save state across them. Every UI mutation and agent tool goes through the same DocumentAction dispatcher. Actions validate component settings, region acceptance, node existence, and capacity constraints before opening a transaction. One user or agent command becomes one undoable transaction. Loading, restoration, and system synchronization do not enter local undo history. Save serializes ordinary template and theme JSON. Raw Yjs updates are not the durable project format. Editor integration boundary @nyxel/editor is a portable library. It receives registry data, templates, theme settings, a Canvas renderer, source context, and persistence callbacks. It does not import theme components, Astro virtual modules, or storefront routes. apps/editor is the host application that wires those dependencies to the local storefront. In the partial Nyxel Connect flow it can exchange a one-use handoff, use a project-scoped Canvas renderer, and surface a review release without receiving provider credentials. A hosted platform can replace the development HTTP handlers without changing the editor component model. --- ## Introduction URL: /docs Build visually editable Shopify storefronts with Astro, Svelte, and typed component contracts. Introduction Nyxel is a pre-release toolkit for building visually editable Shopify storefronts. It keeps the concepts that make Shopify themes understandable—sections, blocks, templates, settings, and theme configuration—while using Astro for storefront routing and composition and Svelte for the primary component and editor experience. !Nyxel editor showing a product page Canvas, page tree, and section Inspector. Start with the working model A developer defines a storefront component and its editable settings in one file. A template JSON document arranges those components into Header, Template, and Footer regions. The editor loads the component manifest and template documents from the storefront, then lets an author change the composition without changing component source. Canvas is the editing surface. It displays a server-rendered storefront snapshot inside isolated Shadow DOM, so selection and overlays stay local to the editor. Preview loads the real storefront route and is where navigation, product forms, cart behavior, and responsive interaction are tested. Shopify remains the source of truth for catalog and commerce data. Nyxel stores presentation: component contracts, template composition, theme settings, and bindings from component settings to Shopify resources. What you can work with The repository includes a standalone editor, an Astro storefront, a reference theme, a documentation site, the partial Nyxel Connect control plane, and publish-ready package boundaries for component contracts, runtime behavior, framework adapters, and command-line tooling. The local workflow supports: - composing Header, Template, and Footer documents; - adding, moving, duplicating, hiding, renaming, and removing nodes; - editing typed settings and color schemes; - binding compatible settings to route and commerce data; - rendering Svelte, Astro, and React components through one manifest contract; - saving ordinary JSON while Yjs manages local draft transactions and undo; - exercising product, collection, search, cart, locale, and error routes in the reference storefront. Nyxel is not yet a hosted service. Partial: Nyxel Connect now implements Shopify installation sessions, Redis-backed project and release records, one-use editor handoffs, GitHub and Vercel provider clients, Preview deployments, and scheduled production promotion. The provider authorization model still uses bootstrap server credentials, and the full customer-owned installation flow has not been proven end to end. Local file-writing and privileged development APIs under /nyxel/* remain unavailable in ordinary production builds; the public Nyxel demo enables a bounded adapter for mock-shop data, Canvas/Preview rendering, and isolated seven-day draft sessions. Project status Nyxel is a personal, pre-release project with a serious working implementation. The local editor and reference storefront are Built for development and demonstration. Repository setup and onboarding are Partial: the supported path is cloning this monorepo, and there is no project generator or production deployment guide. Nyxel Connect is also Partial: its contracts and host implementation exist, but a credentialed merchant installation and release has not been live-proven. Nyxel has not been tested for live merchant traffic. Bugs and breaking changes should be expected. Source is available under the Nyxel Source Available License, which permits learning, local development, and operating a storefront for your own Shopify store; reselling or hosting Nyxel as a product requires permission. Run the repository The supported entry point is the monorepo: The development supervisor starts the storefront and editor together. Run the documentation site separately with pnpm dev:site. Nyxel Connect is an independent host and starts with pnpm --filter @nyxel/connect-host dev. Read Architecture next for the package and application boundaries. If you want to author a component, go directly to Sections and blocks. Core terms | Term | Meaning | | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | | Storefront | The Astro application that owns public routes, Shopify request context, composition, theme CSS, and development endpoints. | | Editor | The standalone Svelte application that owns drafts, document actions, Canvas selection, and inspector controls. | | Canvas | Non-hydrated storefront HTML rendered into Shadow DOM for direct selection and editing. | | Preview | The real storefront route rendered from the editor’s unsaved snapshot. | | Template | Durable JSON describing an ordered tree of sections, blocks, settings, and named regions. | | Component contract | Static TypeScript metadata that defines a component’s settings, regions, editor presentation, and render policy. | | Connect | The partial Shopify-facing control plane for authenticated projects, revisions, releases, and provider coordination. | --- ## Architecture URL: /docs/project-structure Applications, packages, origins, request flow, and persistence boundaries in the Nyxel monorepo. Architecture Nyxel separates deployable applications from reusable packages. The storefront and editor run on different origins in development because they have different security, build, and deployment responsibilities. Application boundaries apps/storefront owns public routes, Shopify request context, theme files, component source, template JSON, and development-only editor endpoints. It contains no editor panels or selection overlays. apps/editor is a thin host for @nyxel/editor. It points at a storefront origin, fetches manifests and documents, and provides persistence and rendering callbacks. The editor library never imports the storefront’s components or virtual modules. apps/connect is a separate SvelteKit host for the partial production control plane. It verifies Shopify sessions, stores Nyxel-owned project and release state, coordinates GitHub and Vercel through server-only clients, and issues bounded editor capabilities. It is not part of the normal local storefront/editor supervisor. apps/site publishes the documentation and blog. It does not share the storefront runtime or act as a deployment host for the editor. Development origins The standard local ports are: | Service | Origin | Responsibility | | ---------- | ----------------------- | ------------------------------------------------------------------- | | Storefront | http://localhost:5273 | Routes, commerce, preview sessions, Canvas rendering, document APIs | | Editor | http://localhost:5274 | Editing UI and local draft orchestration | | Site | http://localhost:5280 | Documentation and blog | | Connect | http://localhost:5450 | Optional project, provider, and release control plane | The editor host can use another allocated port when an isolated worktree is running. Set VITESTOREFRONTORIGIN to choose the storefront it controls. Request flow Astro middleware builds one request-scoped context containing URL, locale, market, cookies, headers, Shopify client, cart identity, preview session, and route sources. Route loaders resolve the page template and commerce data. @nyxel/astro recursively composes nodes and dispatches each one to its renderer adapter. The editor uses separate development calls for registry data, theme configuration, templates, presets, schema defaults, Canvas rendering, and Preview session snapshots. Those file-backed endpoints are not mounted in production. In the partial Connect flow, the Shopify host creates a one-use handoff for one project. The editor exchanges it for a short-lived encrypted capability, then sends project-scoped document and render requests back through Connect. Provider credentials stay in the host. This shape is implemented, but the customer-owned provider authorization flow remains incomplete. Persistence boundaries Template documents live under apps/storefront/src/lib/templates/. A kind field distinguishes route pages, shared groups, and saved sections. Theme settings use their own JSON document. While editing, each persisted document has a Yjs representation. Header, page, footer, and theme stay separate so saving one boundary does not silently rewrite another. Save projects the selected documents back to validated JSON. Package consumption Workspace builds use source exports where hot module replacement is valuable and built dist entries where Node or Astro requires them. Package verification checks the publish shape separately from the workspace shape. @nyxel/connect keeps the provider and release vocabulary independent from the SvelteKit host. When a change crosses contracts, runtime, storefront, or editor boundaries, run the root handoff gate instead of relying on one application’s typecheck. CLI lists the commands and their scopes. --- ## Save, preview, and publish URL: /docs/publishing Understand local draft state, JSON persistence, Preview sessions, and the future production release flow. Save, preview, and publish Nyxel separates editing a document from releasing a storefront change. The local repository implements draft editing, Save, and unsaved Preview sessions. Nyxel Connect contains a Partial production release implementation, but it has not been proven with a customer-owned provider installation. Local draft state The editor loads header, page, footer, and theme JSON into separate Yjs documents. Actions update those documents immediately, Canvas renders the latest projection, and the dirty indicator compares the current state to the last saved state vector. Undo and redo operate on user and agent actions. Loading, restoration, and system synchronization do not appear as author history. Save Save validates the selected document boundary and writes ordinary JSON through the storefront development API. It does not persist Yjs binary updates. Reloading the editor reconstructs the same document tree from JSON. Template files remain reviewable source artifacts, which makes local development compatible with normal version control and code review. Preview before Save Preview sessions let the real Astro route render unsaved page, group, and theme snapshots. A short-lived token identifies the session, and same-origin links preserve it while the user navigates. This is the surface for verifying route behavior and hydrated interaction. Canvas is intentionally non-interactive; Preview is where product forms, cart, filters, search, and locale behavior must work with the draft applied. Production publishing A hosted release flow needs authenticated durable storage, environment ownership, deployment status, rollback, and an auditable relationship between a saved revision and the storefront build serving it. Those concerns do not belong in the local file API. Partial: @nyxel/connect defines and tests the Project, Revision, and Release state machine. apps/connect adds Redis-backed records, Shopify OAuth and session verification, short-lived editor handoffs, server-only GitHub and Vercel clients, immutable Preview deployments, immediate promotion, and a scheduled-publish worker. The editor can create and monitor a review Release when it is launched with a Connect project capability. The missing proof is significant. Provider access currently uses bootstrap server credentials rather than a complete customer-owned GitHub App and Vercel authorization flow. Webhook reconciliation, production rollback, operational hardening, and a live merchant release remain Planned. Until those are proven, the public editor demo saves an isolated draft but does not expose publishing controls. The sequence stays explicit: save the documents, capture an immutable Revision in a review Release, inspect its Preview, then publish that Release now or on a schedule. Save and Publish are never synonyms. --- ## Roadmap URL: /docs/roadmap What Nyxel supports now and which platform capabilities come next. Roadmap Nyxel’s local architecture is functional: typed components, mixed renderer composition, JSON templates, Yjs-backed drafts, Canvas, Preview sessions, Shopify route data, and a reference storefront operate together in the monorepo. Now The immediate product is the developer workflow. A developer can clone the repository, run the storefront and editor, author a typed component, compose templates visually, bind Shopify data, test the real route in Preview, save JSON, and validate the result through the CLI. The reference theme covers the core storefront routes and interaction patterns needed to exercise that workflow. It is a foundation for theme development, not a catalog of every storefront feature. Future The next platform boundary is secure persistence and release management. Partial: Nyxel Connect now has a standalone host, Shopify installation sessions, Redis-backed project and release records, bounded editor handoffs, GitHub/Vercel provider clients, Preview deployment creation, deployment polling, and scheduled promotion. It still needs customer-owned provider authorization, live installation proof, webhook reconciliation, production rollback, and operational hardening against real merchant infrastructure. Developer onboarding also needs a supported project creation flow, published package releases, and a deployment guide that does not assume the monorepo. Collaboration can build on the existing action and Yjs model after one authenticated editor session is reliable. That includes presence, shared cursors, comments, and conflict-aware remote synchronization. A Liquid Bridge theme may provide narrowly scoped access to Shopify-native theme app extensions. It remains separate from the Astro storefront and should only be introduced where a real app-block requirement cannot be met through a headless integration. The roadmap does not require every framework adapter or commerce feature to expand at once. New capability should enter when it advances a complete developer or merchant workflow and can be verified on the real storefront surface. --- ## Sections and blocks URL: /docs/sections Author typed storefront components with settings, regions, presets, and hydration policy. Sections and blocks A Nyxel component is an ordinary Svelte, Astro, or React component with one static TypeScript contract. The contract tells the registry and editor what the component is, which values can be edited, where children may be placed, and whether the browser should hydrate it. !Nyxel Inspector showing typed settings for the storefront header. A minimal Svelte section The setting keys connect the entire workflow. heading produces a typed settings.heading value, an editor control, a default, validation rules, and a persisted override when the author changes it. Settings Builders describe both data and control behavior. Text, rich text, numbers, ranges, checkboxes, selects, URLs, colors, media, icons, resource pickers, list pickers, and dynamic-source-compatible values share one normalized representation. Presentation entries such as header() and paragraph() organize the Inspector but do not become persisted settings. Numeric controls normalize to numbers at the control boundary. List resource pickers return arrays. Defaults live in the contract and templates store sparse overrides. Settings should describe meaningful component choices. Mechanical styling belongs in reusable theme tokens or the component’s own CSS; an unrestricted “custom CSS” field is not a substitute for a clear contract. Named regions Regions define where child nodes may be inserted: The runtime preserves each region’s order. The editor uses the same constraints for add menus and drag targets, and every renderer receives the same semantic child groups in its native syntax. Presets and route restrictions Presets provide useful starting trees rather than empty components. A preset can include settings, nested blocks, regions, and dynamic source bindings. Keep starter data generic: bind route resources such as the current product instead of committing store-specific Shopify IDs. enabledOn and disabledOn restrict where a component can be added. Use them for real structural rules, such as a cart surface that only belongs on the cart template, rather than as a substitute for resilient component design. Hydration server is the default policy. Use load, idle, visible, or media only when the component needs browser behavior. Astro owns mixed-framework recursion, so a Svelte parent can receive a React or Astro child without either component becoming responsible for framework dispatch. Extraction and diagnostics The scanner parses .svelte module scripts, .astro frontmatter, and .tsx named exports. It evaluates only literal objects, arrays, recognized builder calls, and local static constants; it never imports the component during registry scanning. Computed property names, environment reads, arbitrary function execution, and unknown spreads are rejected with stable NXY* diagnostics. Run pnpm nyxel inspect component to see the extracted contract and normalized manifest, then pnpm nyxel check before handing off a component change. !Nyxel Components library showing the storefront header component and its settings. --- ## Commerce boundaries URL: /docs/storefront-sdk/commerce-boundaries What Shopify owns, what Nyxel owns, and how interactive storefront surfaces coordinate. Commerce boundaries Shopify remains authoritative for catalog, pricing, inventory, markets, carts, checkout, customers, and orders. Nyxel consumes those capabilities and controls how they are presented in an editable storefront. !Nyxel reference storefront cart drawer with a product image, quantity, subtotal, and checkout action. Shopify owns durable commerce state The request-scoped Storefront API client reads products, collections, navigation, metafields, metaobjects, and market context. Hydrogen cart handlers create and mutate the Shopify cart, while Shopify’s checkout URL remains the handoff for payment and order creation. Nyxel does not copy that state into template JSON. A product section receives the current product through its source context. A cart surface subscribes to the Hydrogen cart store. A collection route turns URL filter and sort state into the corresponding Storefront API request. Nyxel owns presentation and composition Nyxel decides which product sections appear, how blocks are arranged, which component settings are editable, and how route resources bind into those settings. It also owns the reference storefront’s responsive shells, drawers, empty states, loading feedback, and error presentation. This includes interaction quality at the presentation boundary. Add-to-cart must provide visible feedback, the cart drawer and mobile navigation must use a consistent modal pattern, quantity changes must update totals, and collection filters must preserve understandable URL state. Independent islands Astro may hydrate the header, product form, and storefront client as separate Svelte islands. Data libraries can still use their normal request and mutation contracts, but UI commands should not rely on a module-local Svelte store being shared across compiled island boundaries. Nyxel uses a small page-level event for cart drawer requests. After a successful product-form mutation, the drawer refreshes the Hydrogen cart and opens. The same event lets the header cart button open the surface. Cart contents and totals still come from Hydrogen; the browser event carries intent, not duplicated commerce state. Modal interaction The mobile menu, cart drawer, and collection filter surface darken and disable the page behind them, provide a clear close action, constrain scrolling to the panel, respond to Escape, and restore focus when they close. Their content differs, but panel width, spacing, header hierarchy, and overlay behavior use one visual language. Future platform boundary A hosted editor needs authenticated access to templates, settings, previews, and Shopify resources. It does not need to become the owner of cart, checkout, or catalog data. Keeping that boundary intact makes the local architecture suitable for a platform without introducing a second commerce system. --- ## Storefront runtime URL: /docs/storefront-sdk How Astro composes templates, creates request context, resolves themes, and hydrates interactive components. Storefront runtime The storefront is an Astro server application. It resolves a route, loads Shopify data and a Nyxel template, then recursively composes the template through framework adapters. !Nyxel reference storefront product page for Slides in light mode. From request to HTML Astro middleware creates a request-local context with the URL, locale, market, headers, cookies, Shopify client, cart identity, and Preview session. The route layer adds resources such as the active product or collection and selects the corresponding template document. @nyxel/astro walks the template tree. For each node it looks up the normalized manifest, resolves settings and dynamic bindings, applies theme values, renders named child regions, and dispatches the component to its Svelte, Astro, or React adapter. Astro owns recursion because it is the one layer that can compose all supported renderers. A component only needs to understand its semantic props: Server-first rendering Components render on the server unless their contract declares a hydration policy. load, idle, visible, and media map to Astro client directives. Interactive islands should remain small and communicate across framework boundaries through explicit browser events or HTTP contracts rather than assuming shared component state. The header, product form, and cart drawer illustrate this boundary. They can hydrate independently, while cart data is managed by Hydrogen and open/close commands cross islands through a page-level event. Routes and commerce The reference storefront includes home, product, collection, page, search, cart, password, sitemap, and error behavior, with locale-prefixed forms where the request context supplies a locale. Explicit API routes handle cart and search before any catch-all theme route. !Nyxel reference storefront collection page with filtering and sorting controls. Collection state is URL-backed. Filter and sort controls update query parameters, route data refreshes through the Shopify request context, and the component renders applied filters and result state from that URL. Cart mutations use Hydrogen’s cart handlers and preserve Shopify checkout as the final purchase surface. Theme CSS The reference theme combines Tailwind utilities with four Nyxel-owned layers: | Layer | Responsibility | | -------------- | ----------------------------------------------------------------- | | Theme tokens | Type, spacing, radius, layout, and semantic aliases | | Element styles | Classless HTML defaults using theme and color-scheme variables | | Primitives | Shared buttons, page width, rich text, cards, and layout behavior | | Runtime theme | Merchant values and generated [data-color-scheme] variables | Component CSS should use these tokens instead of hard-coded theme colors. A component can select or inherit a color scheme; nested controls such as market and theme switchers must retain their own readable foreground and surface variables. Canvas responses include the same scoped CSS, runtime variables, fonts, and absolute asset URLs. Shadow DOM prevents the theme reset from changing editor chrome. Development services The Astro integration mounts development-only registry, template, preset, schema-default, Canvas render, and Preview session handlers. Their business logic lives in framework-neutral runtime services, while Astro converts Requests and Responses at the host boundary. A production editor platform will implement authenticated persistence and rendering behind equivalent contracts. The file-backed development endpoints are never a production API. --- ## Why Nyxel URL: /docs/why-nyxel Why Nyxel combines Shopify’s theme model with Astro composition and Svelte-first authoring. Why Nyxel Nyxel is my personal attempt to answer one question: can a custom storefront keep the clear authoring contract that makes Shopify themes useful? Headless storefronts give developers control over routing, rendering, deployment, and component architecture. They often remove a useful Shopify workflow at the same time: developers define a constrained set of components, and store operators compose those components visually without becoming frontend developers. Nyxel brings that workflow to a custom storefront. Keep the legible parts of Shopify themes A Shopify theme has an understandable contract between code and content. A section schema defines controls. Template JSON arranges sections. Shopify resources provide commerce data. Nyxel retains those responsibilities while expressing the component contract in TypeScript and rendering the result through Astro. | Shopify theme concept | Nyxel equivalent | | ----------------------- | --------------------------------------------------------- | | Section schema | Static TypeScript component contract | | section.settings | Typed settings prop with resolved defaults and bindings | | Blocks inside a section | Ordered children in named regions | | Template JSON | Versioned page and group documents | | Theme settings | Token-oriented CSS variables and color schemes | | Theme editor preview | Shadow DOM Canvas plus real-route Preview | This is useful for teams that understand Shopify themes but need a custom storefront. The developer still controls the available components and their behavior. The editor changes composition and configured values, not arbitrary source code. Why Astro owns the storefront Astro provides one server-side owner for routing, request middleware, recursive composition, and selective hydration. Nyxel’s composer can dispatch a node to Svelte, native Astro, or React while keeping framework mixing at explicit boundaries. Server HTML is the default. A component opts into client JavaScript through its contract only when interaction requires it. The same composer renders public routes, Preview sessions, and Canvas snapshots, which reduces the chance that the editor shows a different component tree from the storefront. Why Svelte remains primary The editor and reference theme use Svelte because component files stay close to HTML and CSS, reactive state is compact, and the authoring experience is already strong for visual storefront work. Astro and React adapters expand the component boundary without changing what the editor needs to understand. The editor reads normalized manifests. It does not branch on the source language of a component. Why Canvas and Preview are separate Editing and storefront interaction need different behavior. Canvas intercepts navigation and form actions so a click can select the nearest component marker. Preview runs the actual route so links, variants, cart mutations, locale changes, and responsive behavior can operate normally. Keeping both surfaces makes the distinction explicit: Canvas answers “what am I editing?” and Preview answers “does the storefront work?” Product boundary Nyxel is a presentation and composition system for Shopify storefronts. It is not a commerce backend, a replacement checkout, or a general-purpose CMS. Products, inventory, prices, markets, carts, customers, orders, metafields, and metaobjects continue to belong to Shopify. The source is available to inspect and run under Nyxel’s custom license, but the project is pre-release and not proven for live merchant traffic. Future work focuses on turning the local workflow into a secure hosted platform without weakening those boundaries. ---