Project Structure
Where does your code go, and what can you change? You fork the Storefront Application V3 and own every file in it. storefront.config.ts holds the settings for your shop, and src/ splits into three directories that decide what a file may import: src/server runs on the server, src/client runs in the browser, and src/shared is the contract both sides read. Commerce logic stays in the @scayle/storefront package, which arrives as a dependency and which you extend rather than edit.
Repository layout
Your code and package code
You restructure, rename, and delete files under src/ freely. The SCAYLE packages arrive as dependencies and sit in node_modules, where you read them but do not edit them.
The SCAYLE packages are @scayle/storefront, @scayle/storefront-api, @scayle/storefront-build, and one CMS package per vendor. Tech Stack says what each one does. You subclass what you want to change in @scayle/storefront, covered on Extending the SDK. Your fork keeps the CMS package your shop uses.
Restructure three files with care. src/server/index.ts builds the Hono app and adds the storefront runtime, and the order of its middleware decides what later stages can read (see Request Lifecycle). src/server/registries.ts needs a factory for every registry slot, and TypeScript reports a missing one there. src/client/ssr.ts wraps the Vue render twice, once for tracing and once to collect the module preload hints a page sends. Dropping the tracing wrapper compiles cleanly and costs you the render span, so nothing points at the loss.
Path aliases
Imports use named aliases, not relative paths out of a directory. tsconfig.json declares them for TypeScript, and vite.config.ts repeats the ones the bundler resolves.
| Alias | Resolves to |
|---|---|
@server/* | src/server/* |
@client/* | src/client/* |
@shared/* | src/shared/* |
@assets/* | src/client/assets/* |
@cms-server/* | src/server/cms/providers/<CMS_PROVIDER>/* |
@cms-client/* | src/client/cms/providers/<CMS_PROVIDER>/* |
@cms-shared | src/shared/types/cms/<CMS_PROVIDER> |
@test/* | src/test/* |
@/* | src/* |
The last two resolve in fewer places than the rest. @test/* is declared in tsconfig.json and vitest.config.ts, not in the Vite build, so it works in tests and in your editor. @/* is declared in tsconfig.json alone, so it type-checks but resolves in no build and no test run. Reach for @client/*, @server/*, or @shared/* instead.
Import rules ESLint enforces
eslint.config.mjs sets import-x/no-restricted-paths zones that fail the lint run as errors, so a crossed boundary stops at your editor rather than in production.

The rules behind the arrows:
src/servermust not import fromsrc/client.src/clientmust not import fromsrc/server, with one exception:src/server/api/index.ts, which exports the oRPC router.src/client/plugins/orpcServer.tsimports the router itself, so the exception covers a real value and not only a type.src/sharedmust not import from either side. It is the contract, so it depends on neither.
Two more rules apply across src/**. import-x/no-cycle rejects an import cycle up to a depth of five, and no-restricted-imports keeps vitest and @scayle/storefront/test out of production files, because neither is installed in a production build.
The zone rules above catch an alias and a relative path alike.
Placing new code
| You are adding | It goes in | Example in your fork |
|---|---|---|
| A page | src/client/pages/<Name>.vue | Basket.vue |
| The controller for it | src/server/controllers/ | basket.ts |
| Its route pattern | src/shared/routes.ts | routes.basket |
| An oRPC procedure | src/server/api/ | cms.ts |
| A field on a mapped type | src/shared/types/ plus its mapper | Promotion.ts, services/mappers/ |
| A shared type | src/shared/types/ | Basket.ts |
| A component | src/client/components/<domain>/ | components/product/ |
| A composable | src/client/composables/ | useBasket.ts |
| Middleware | src/server/middleware/ | securityHeaders.ts |
| A translation | src/i18n/locales/en_GB.json first | then every other locale file |
| A registry slot type | src/server/types/index.ts | the MapperOverrides block |
A page needs four of those together: the route pattern, the controller, the mount in src/server/ssr-routes.ts, and the Vue file. Pages and Controllers walks through it. A mapper field needs the type and the mapper in one change. Layers and Data Flow covers what shape a field may take, and Extending the SDK covers why the mapper matters and which mapper produces which type.
Translate a new key in all locales covers adding a key and the lint rule that reports a missing one.
The CMS provider directories
Your shop runs one CMS. The directories exist for all of them:
CMS_PROVIDER picks which one your build uses. It accepts scayle, storyblok, contentful, contentstack, or amplience, and defaults to scayle, a placeholder that renders without a real CMS behind it so you can run the storefront before you connect one. Vite reads the variable at build time and points @cms-server, @cms-client, and @cms-shared at the matching directories, so provider-independent code imports through the alias and never names a vendor. An unknown value fails the build with a message naming the valid ones, rather than surfacing later as a missing directory.
TypeScript resolves those three aliases to the scayle directories, since tsconfig.json cannot read a build variable. tsconfig.storyblok.json, tsconfig.contentful.json, tsconfig.contentstack.json, and tsconfig.amplience.json point them at the other providers, which is how a typecheck covers the provider you actually ship.
Set CMS_PROVIDER once, when you set up your project. The other four directories take part in no build after that, so delete them or leave them alone.