How v7 works

A v7 site has two loops running through it. In the request loop, a visitor asks for a URL and the site turns stored JSON into a rendered page. In the authoring loop, a developer's TypeScript types become Studio forms, and what editors save becomes the JSON the request loop reads. This page walks through both, then shows how the packages split the work.

The request path

When a request arrives, the framework binding (@decocms/tanstack or @decocms/nextjs) hands its path to the runtime in @decocms/blocks. The runtime holds the site's content in memory as the decofile: a flat map from block names to JSON.

1. Find the page. A page block is a block with a path (a URL pattern such as /:category/:slug/p) and a list of sections. The runtime picks the most specific pattern that matches. See Pages and routing.
2. Resolve. Content is JSON, but some values in it stand for something else. A value with a __resolveType field names a section, another block, a matcher-guarded variant or a data loader. Resolution follows those names recursively until every value is plain data. A product shelf's products prop, for example, becomes the result of a VTEX search. See Blocks and sections and Matchers and variants.
3. Section loaders. After resolution, each section can have a server function that adds props (device, search params, its own data). See Loaders and actions.
4. Render. The binding renders the sections as React. Sections an editor marked async in Studio render as a skeleton first and are fetched separately, so the first byte isn't held up by slow data. See Deferred sections.

On TanStack Start, all of this runs inside a Cloudflare Worker that also owns an edge cache, CMS redirects and the admin endpoints; see The Worker request pipeline. On Next.js, it runs inside Server Components.

The authoring path

Editors never write JSON by hand. Studio builds a form for every section from its TypeScript Props type, and saves what editors enter as blocks.

The generate command from @decocms/blocks-cli reads your sections, loaders and installed apps and writes generated files into .deco/. The most important one, meta.gen.json, is the JSON Schema Studio builds its forms from. In development the TanStack Vite plugin reruns the generators as you edit; on Next.js you run generate before dev and build. See Schema generation and Code generation.

The runtime exposes HTTP endpoints, called the admin protocol, for schema reads, content reads, previews, loader calls and authorized content reloads. Current Studio uses repository-backed content editing; its Publish action opens and merges a PR, and the deployment integration applies that content. See Site Editor and the v7 admin protocol.

What happens when an editor publishes

After Studio publishes, the site's deployment integration applies the merged repository content. Separately, a compatible delivery client can call POST /.decofile, either with the full decofile or a delta of changed blocks. The instance that receives it swaps its in-memory decofile in one step, clears its loader cache and invalidates the schema ETag, so requests that start after the swap see the new content.

What makes the change last depends on how the site is deployed:

• By default, content ships with the code. The build bundles .deco/blocks/ into the server, and a new instance starts from that bundled copy. A runtime reload changes only the memory of the instance that received it, so content that has to survive a restart or reach every instance must be in .deco/blocks/ in the deployed build. Studio's working branch and publish PR preserve content in the repository; the production build applies the merged snapshot.
• With Fast Deploy (TanStack on Workers, opt-in), content lives in Cloudflare KV keyed by deployment. An authorized runtime reload or CI content-sync writes there, and the other Worker isolates running the same deployment pick it up on their next revision check (about every ten seconds) without a redeploy. See Deploying and Fast Deploy.

The packages and their graph

The framework is five packages. The dependency graph only points one way, so the runtime never depends on a binding and the two bindings never depend on each other.

Package                  depends on
───────────────────────  ─────────────────────────────────────────────
@decocms/blocks          nothing from Deco (the runtime)
@decocms/blocks-admin    blocks
@decocms/blocks-cli      blocks
@decocms/tanstack        blocks, blocks-admin, blocks-cli
@decocms/nextjs          blocks, blocks-admin

The companion apps (@decocms/apps-*) build on @decocms/blocks and @decocms/apps-commerce. An app is configured from a block in the decofile and registers its loaders, actions and sections when the site starts. See Apps.

Each package ships plain TypeScript source rather than a bundled build, so the runtime state (the decofile, the section registry) exists exactly once in your app. How v7 is built explains why that matters.

Next steps

• Blocks and sections: the content model in detail.
• Content and the decofile: where content lives and how it reaches the runtime.
• Pages and routing: how a path finds a page.
• Site Editor and the v7 admin protocol: the endpoints compatible v7 clients can call.
• How v7 is built: the package split and module state.