> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollie.shop/llms.txt
> Use this file to discover all available pages before exploring further.

# Project configuration (ollie.json)

> The ollie.json file that links a project to a store, the components map, stage files, and the init and setup commands that write them

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

```json ollie.json theme={"system"}
{
  "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:

```text theme={"system"}
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.

```bash theme={"system"}
ollieshop init --store-id <store-uuid> [--version-id <version-uuid>] [--stage dev]
```

```json theme={"system"}
{"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.

```bash theme={"system"}
ollieshop setup --dry-run   # show what would move
ollieshop setup
```

```text theme={"system"}
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.

## Related

* [Build Your First Component](/ollie-shop/components/your-first-component.md): declaring and linking a component step by step
* [Ollie Studio](/ollie-shop/studio.md): how publishing writes the map back
* [start](/ollie-shop/cli/start.md): the dev server that reads this file


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.