Getting started

This page takes you from an empty directory to a themed, block-composable storefront — first running on your machine, then live on a generated preview URL. Eight steps, and the only credential you need is the one for the final deploy.

1. Prerequisites

Install and sign in to the CLI now, so the last step is one command:

npm install -g @revenexx/cli
revenexx login --token <your-token> --tenant <your-tenant-slug>

The create and deploy command groups come from a CLI plugin, so they're present when the CLI is built with it — see Scaffolding.

2. Scaffold the theme

revenexx create theme my-storefront
cd my-storefront

create theme stamps the whole theme contract, not just a folder:

The manifest is the file worth opening first. Full field-by-field walkthrough: Theme anatomy.

3. Run it — with no credentials at all

npm install
npm run dev

Open the printed URL and you have a working shop: a catalog, product pages, a cart, and a checkout.

Nothing is needed to get there. Every commerce and pages domain in the theme resolves through a service key, and every one of those keys defaults to mock, served from fixture data bundled with the layer. No API key, no tenant, no environment variables, no seeding step. Onboarding a developer onto a theme project is a clone and an install.

This is the fact to keep in mind for the rest of the project: you can build blocks, wire pages, style the whole thing, and demo it on a plane. Real data is a switch you flip per domain when you're ready — see Service modes.

4. Open the visual editor

The Blökkli editor runs inside your theme, on a route the theme itself serves:

/admin/edit?page=<page-id>

Cockpit embeds that route in an iframe under Experience Studio → Pages, which is how an editor reaches it in practice — and because the editor executes in your theme, what they see is your real components rendering real props.

One requirement makes this work. The editor anchors to the element with id nuxt-root, and Nuxt's default root id is __nuxt:

export default defineNuxtConfig({
  app: {
    rootId: 'nuxt-root',
  },
})

A scaffolded theme, and any theme extending @revenexx/cover-theme, already has this. If you build directly on @revenexx/cover, set it yourself — without it the editor fails to attach.

5. Edit one block

A block is an ordinary Vue component with one extra call. Six lines is a real, complete block:

<script setup lang="ts">
const props = defineProps<{ label: string }>()

defineBlokkli({
  bundle: 'badge',
})
</script>

<template>
  <span v-blokkli-editable:label>{{ props.label }}</span>
</template>

Two things are happening. The component's props become the editor's content fields — an editor filling in "Label" is setting props.label. And bundle is the id that ties this component to its entry in theme.json; get the two out of sync and the block renders as unknown.

Change the template, save, and the editor canvas updates. Then go deeper: How a block works.

6. Point it at real data

Two things switch a domain from fixtures to the live platform.

First, the connection. Set it through Nuxt's runtime config environment variables:

NUXT_REVENEXX_API_URL=https://api.revenexx.com
NUXT_REVENEXX_TENANT=<your-tenant-slug>
NUXT_REVENEXX_API_KEY=<your-api-key>

Second, the service keys. Flip only the domains you care about in your own app.config.ts:

export default defineAppConfig({
  productService: 'api',
  categoryService: 'api',
  // everything else still resolves to mock
})

That per-domain granularity is deliberate: you can run live products against a mocked cart while you build the product pages, instead of choosing between "all mocks" and "full production wiring".

7. Deploy it

From the theme directory:

revenexx deploy theme .

That one command finds or creates the site by name, uploads the code, builds it, registers the theme, and installs it on your tenant. The subcommand is deploy theme — not deploy sites-theme.

When the build reaches ready, open the generated preview URL. Every deployment gets one that points at that exact build forever, plus hosts keyed to the commit and the branch — see Previews.

On the preview, check the things that never show up in npm run dev: view source to confirm the pages really server-render, and confirm the domains you switched to api resolve for real.

8. Where to go next

Pick the group that matches what you're doing next.

• Build the theme — the layer chain, overriding the base layer, design tokens, the framework matrix.
• Compose pages with Blökkli — option types, shells and fields, and the ninety bundles you inherited.
• Connect commerce data — the BFF pattern, auth headers, catalog, cart, checkout, search, media, forms.
• Build and deploy — build configuration, compute, environment variables, Git-connected deploys.
• Run it in production — deployment statuses, rollbacks, custom domains, logs, publishing to the marketplace.

Prefer a slower, guided version of the same ground? Build a storefront theme is the tutorial track.