---
title: "Project Settings (deeep.json)"
sidebarTitle: "Project Settings"
description: "Comprehensive reference for deeep.json settings. Configure component globs, Storybook index locations, build commands, and Git repository links."
keywords: "deeep.json schema reference, project configuration, component patterns"
icon: "sliders-horizontal"
---

The `deeep.json` file in your repository root stores the link between your local project and deeepSpace, plus the settings used to discover and sync your components.

Run commands from the repository root containing this file: the CLI loads configuration from the current working directory, not by searching parent directories. Discovery paths are relative to the Git root.

The file is maintained by the CLI and may also be rewritten after other successful commands. Use valid JSON and repository-relative paths without `..`; paths resolving outside the repository are rejected. Repair malformed JSON before reinitializing, since `--force` does not bypass configuration loading.

---

## Configuration structure

```json
{
  "project": {
    "name": "My Awesome Project",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "projectSettings": {
      "framework": "react",
      "language": "tsx",
      "styling": "tailwind",
      "styleMode": "external",
      "remBaseFontSize": 16,
      "customInstructions": ""
    },
    "gitRepoName": "my-org/my-awesome-project",
    "gitRepoUrl": "https://github.com/my-org/my-awesome-project",
    "version": 1
  },
  "discovery": {
    "type": "CLI",
    "componentIndexJsonPath": ".deeep.index.json",
    "components": [
      "src/components/**/*.{js,jsx,mjs,ts,tsx,vue}",
      "packages/*/src/components/**/*.{js,jsx,mjs,ts,tsx,vue}"
    ],
    "exclude": [
      "**/*.test.*",
      "**/*.spec.*",
      "**/*.stories.*",
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/coverage/**"
    ]
  }
}
```

---

## Project fields

| Field | Type | Description |
|-------|------|-------------|
| `project.name` | string | Name of the linked deeepSpace project |
| `project.uuid` | string | Unique identifier of the deeepSpace project |
| `project.projectSettings` | object | Tech stack and code-generation preferences |
| `project.gitRepoName` | string | Connected Git repository name, for example `owner/repo` |
| `project.gitRepoUrl` | string | URL of the connected Git repository |
| `project.version` | number | Project version saved when linking; component sync does not refresh this value |

---

## Project settings fields

| Field | Type | Description |
|-------|------|-------------|
| `projectSettings.framework` | string | Frontend framework |
| `projectSettings.language` | string | Programming language / JSX flavor |
| `projectSettings.styling` | string | Styling technology |
| `projectSettings.styleMode` | string | How styles are organized |
| `projectSettings.remBaseFontSize` | number | Base font size used for `rem` conversions |
| `projectSettings.customInstructions` | string | Free-text instructions for code generation |
| `projectSettings.storybookUrl` | string | Remote Storybook URL updated after successful hosting; the local discovery URL is stored separately in `discovery.storybookUrl` |

---

## Stack detection

After initialization, the CLI detects `framework`, `language`, `styling`, and `styleMode` and asks whether to update the remote project settings. After sync, it skips this prompt when those four values already match. Declining keeps the existing settings; an API update failure is reported as a warning. Other preferences such as `remBaseFontSize` and `customInstructions` are not inferred by stack detection.

Detection uses the root `package.json` and source-file signals. Review its suggestion in monorepos or mixed-framework repositories. Editing local `projectSettings` alone is not a general remote-settings update command.

## Detected values

### Frameworks

| Value | Description |
|-------|-------------|
| `react` | React |
| `reactNative` | React Native |
| `vue` | Vue |
| `angular` | Angular |
| `svelte` | Svelte |
| `none` | No framework detected |

### Languages

| Value | Description |
|-------|-------------|
| `js` | JavaScript |
| `ts` | TypeScript |
| `jsx` | JavaScript with JSX |
| `tsx` | TypeScript with JSX |
| `none` | No language detected |

### Styling

| Value | Description |
|-------|-------------|
| `css` | Plain CSS |
| `scss` | SCSS / Sass |
| `less` | Less |
| `tailwind` | Tailwind CSS |
| `styledJs` | CSS-in-JS (for example styled-components or Emotion) |
| `none` | No styling detected |

### Style modes

| Value | Description |
|-------|-------------|
| `external` | Styles in separate files |
| `scoped` | Scoped styles (for example CSS modules or Vue scoped styles) |
| `dynamic` | Dynamic CSS-in-JS |
| `none` | No style mode detected |

The detector does not emit `inline`. Framework detection does not imply full source-analysis support: for example, `svelte` is detected as a stack value, but `.svelte` files are not scanned by CLI discovery. See [discovery coverage](/reference/component-index).

---

## Discovery configuration

The `discovery` object tells the CLI how to find your components.

### CLI discovery

Use this method when you want the CLI to scan your source files directly.

```json
{
  "discovery": {
    "type": "CLI",
    "componentIndexJsonPath": ".deeep.index.json",
    "components": [
      "src/components/**/*.{js,jsx,mjs,ts,tsx,vue}"
    ],
    "exclude": [
      "**/*.test.*",
      "**/*.spec.*",
      "**/*.stories.*",
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/coverage/**"
    ]
  }
}
```

| Field | Description |
|-------|-------------|
| `type` | Must be `CLI` |
| `componentIndexJsonPath` | Output path; defaults to `.deeep.index.json` when omitted |
| `components` | Glob patterns for component source files |
| `exclude` | Glob patterns to ignore |

### Storybook discovery

Use this method when your components are documented with Storybook.

```json
{
  "discovery": {
    "type": "STORYBOOK",
    "storybookConfigDirectory": ".storybook",
    "storybookIndexJsonPath": "storybook-static/index.json",
    "componentIndexJsonPath": ".deeep.index.json",
    "stories": [
      "src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
    ],
    "exclude": [
      "**/node_modules/**",
      "**/dist/**"
    ]
  }
}
```

| Field | Description |
|-------|-------------|
| `type` | Must be `STORYBOOK` |
| `storybookConfigDirectory` | Path to your `.storybook` config directory |
| `storybookIndexJsonPath` | Path to the generated Storybook `index.json` |
| `componentIndexJsonPath` | Output path; defaults to `.deeep.index.json` when omitted |
| `stories` | Saved story-pattern metadata; does not filter the generated Storybook index in the current implementation |
| `exclude` | Saved exclusion metadata; does not filter Storybook entries in the current implementation |
| `storybookUrl` | Optional deployed base URL starting with `http://` or `https://`; included in Storybook sync metadata |
| `hostStorybook` | Boolean, default `false`; enables hosting after sync, unless an existing URL causes it to skip |

The generated Storybook index determines the story set. `storybookConfigDirectory` defaults to `.storybook` during index generation; `storybookIndexJsonPath` must be configured. `hostStorybook` can also be used with CLI discovery when the repository has a Storybook build script. See [Storybook discovery and hosting](/guides/storybook) for full behavior.

---

## Legacy configuration

When there is no nonempty `discovery` object, the CLI recognizes the older `project.discoveryType` values `cli` and `storybook` case-insensitively and supplies default discovery settings. It removes that legacy field from the loaded project. Run `deeep init --force` to review and save explicit settings for the current layout.

## Best practices

1. **Keep `deeep.json` in version control** so the whole team uses the same project link and discovery rules.
2. **Do not edit `uuid` or `gitRepoUrl` manually** unless you know the values are correct.
3. **Use `deeep init --force`** to safely change discovery settings or relink the project.
4. **Verify discovery with `deeep sync --dry-run`** before syncing to deeepSpace.