Project Settings (deeep.json)

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

{
  "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.

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.

{
  "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.

{
  "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 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

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

Get Started

Reference

Project Settings (deeep.json)

Configuration structure

Project fields

Project settings fields

Stack detection

Detected values

Frameworks

Languages

Styling

Style modes

Discovery configuration

CLI discovery

Storybook discovery

Legacy configuration

Best practices

​Configuration structure

​Project fields

​Project settings fields

​Stack detection

​Detected values

​Frameworks

​Languages

​Styling

​Style modes

​Discovery configuration

​CLI discovery

​Storybook discovery

​Legacy configuration

​Best practices

Configuration structure

Project fields

Project settings fields

Stack detection

Detected values

Frameworks

Languages

Styling

Style modes

Discovery configuration

CLI discovery

Storybook discovery

Legacy configuration

Best practices