Project configuration (ollie.json)

A project is a folder with a package.json, a components/ folder, optionally a functions/ folder, and an ollie.json that tells the CLI which store the project belongs to and which folders are components.

ollie.json

{
  "storeId": "7f3c9a1e-5b2d-4e8f-9a6c-1d2e3f4a5b6c",
  "versionId": "0b7e4d2c-9f1a-4c3b-8e5d-6a7b8c9d0e1f",
  "components": {
    "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d": {
      "path": "components/FreeShippingBar",
      "slot": "cart_header_full_page"
    },
    "HelloWorld": {
      "path": "components/HelloWorld",
      "slot": "checkout_header_full_page"
    }
  }
}

Key	Required	Meaning
`storeId`	yes	The store’s UUID. Find it on the store’s dashboard or Settings page in the Admin
`versionId`		The version Studio opens and `start` reports. Without it, the store’s default version
`components`		The components map, see below. Other keys are kept as-is

The file is read by start, whoami and function dev. The record and deploy commands do not read it: they take every id as a flag.

The components map

Each entry maps a key to a folder:

The key is either the component’s UUID, which makes the entry linked to a record in your store, or any alias you like, which makes it unlinked. An unlinked entry gets the temporary id studio-<alias> and shows up in Studio with a Publish button.
path is the folder, relative to the project root. It must contain an index.tsx. It can live outside components/.
slot is where the component renders. Without it the component is built but not placed, and start warns about it.
id can carry the UUID when the key is an alias; usually the key itself is the UUID.

The CLI keeps the map current for you. When Studio publishes an unlinked component, or saves a linked one’s slot, the dev server rewrites the entry under the real UUID. The same folder can appear twice with different keys, for example after Studio’s Duplicate action, which adds <folder>-copy-<id> entries. Folders under components/ that are not in the map are still discovered: the CLI falls back to a legacy meta.json inside the folder, and without one treats the folder as unlinked with no slot.

Stages

A project can hold several configurations, one per stage: ollie.json is the prod stage, and ollie.<stage>.json (for example ollie.dev.json) any other. Select one with --stage <name> or -s, or set OLLIE_STAGE. A stage file is merged over ollie.json key by key: a versionId in ollie.dev.json replaces the one in ollie.json, and so does a components map (the two maps are not combined). ollie.json must exist even when you only use a stage, and a stage file that does not exist is an error:

Stage config not found: ollie.dev.json. Create it or use --stage prod (default).

Studio shows a stage selector while the dev server is connected, so you can preview the components each stage links. Stage names cannot contain dots.

init

Writes the ids to ollie.json (or to ollie.<stage>.json with --stage), merging with what is already there. It does not check that the ids exist and needs no login.

ollieshop init --store-id <store-uuid> [--version-id <version-uuid>] [--stage dev]

{"data":{"file":"ollie.json","storeId":"7f3c9a1e-5b2d-4e8f-9a6c-1d2e3f4a5b6c"}}

init ignores OLLIE_STAGE; pass --stage explicitly.

setup

Migrates a project from the legacy per-folder meta.json files to the components map. For every components/<name>/meta.json (or meta.<stage>.json) that carries an id, it writes the entry into ollie.json (or the stage file) and deletes the meta file. Metas without an id are left alone.

ollieshop setup --dry-run   # show what would move
ollieshop setup

Migrated 2 meta file(s) to config:
  ollie.json  FreeShippingBar  (id a1b2c3d4-…, slot cart_header_full_page)  [removed meta.json]
  ollie.json  GlobalPixels     (id c3d4e5f6-…, slot global_layout_bottom)   [removed meta.json]

Run it once on a project that predates the map; new projects do not need it.

Build Your First Component: declaring and linking a component step by step
Ollie Studio: how publishing writes the map back
start: the dev server that reads this file

Overview

Start Here

AI Coding Agents

Core Concepts

Customization

Ollie Studio

Functions

CLI Reference

Ollie SDK

Analytics & Scripts

Tools & Tips

Product updates

Project configuration (ollie.json)

ollie.json

The components map

Stages

init

setup

​ollie.json

​The components map

​Stages

​init

​setup

​Related

ollie.json

The components map

Stages

init

setup

Related