Project Settings Reference

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.

The file is created and updated automatically by deeep init and deeep sync. You can also edit it manually, but invalid JSON or unsafe paths will cause the CLI to fail.

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	Current project version

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

Supported 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
`inline`	Styles inline in the component
`scoped`	Scoped styles (for example CSS modules or Vue scoped styles)
`dynamic`	Dynamic CSS-in-JS
`none`	No style mode detected

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`	Path where the generated component index is written
`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`	Path where the generated deeep component index is written
`stories`	Glob patterns that match your story files
`exclude`	Glob patterns to ignore

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.