Configuration

Snapds works with zero configuration and adds structure only when your team needs it. There are three optional layers.

Level 1 — Auto introspection

By default Snapds parses your TypeScript components to determine props, types, and default values. No file is required.

Level 2 — Team / workspace

Add a snapds.config.json at the repo root for shared, committable overrides: package registrations, excluded components, custom snippets, per-prop tweaks, and AI skills config. In a monorepo, each sub-app can have its own config that inherits from a root via extends. You can also generate and load this file directly from the Settings panel — see Export & import config. See Workspace config file below for the full schema.

Level 3 — User settings

Personal package registrations and selections live in your workspace .vscode/settings.json under snapds.packages and snapds.skills.

Settings reference

snapds.packages

An array of registered packages. Each item:

Selections are stored per package as excluded / manual lists — Snapds never persists a full allow-list, so new upstream components always surface automatically instead of being silently hidden.

snapds.skills

An object controlling agent-skill export (see Skills for agents):

Workspace config file (snapds.config.json)

A committable file for team-wide overrides. Snapds walks up from the active editor file toward the workspace root and uses the nearest snapds.config.json it finds. Editing the file invalidates the introspection cache automatically.

// snapds.config.json
{
  "version": "1",
  "packages": [
    {
      "name": "@acme/ui",
      "importPath": "@acme/ui",
      "excluded": ["InternalOnly"],
      "manual": ["PolymorphicButton"],
      "overrides": {
        "Button": {
          "snippet": "<Button variant=\"primary\">$1</Button>",
          "props": {
            "variant": { "defaultValue": "primary" },
            "internalId": { "hidden": true }
          }
        }
      }
    }
  ],
  "skills": {
    "enabled": true,
    "formats": ["claude", "cursor"],
    "destination": "workspace",
    "autoGenerate": false
  },
  "scopeFilters": ["@acme"]
}

Monorepo extends

In a monorepo where different apps share a base config but have different package registrations, use extends to inherit and override:

/monorepo
├── snapds.config.json            ← shared skills config, scope filters
└── apps/
    ├── mobile/
    │   └── snapds.config.json    ← extends root, overrides packages
    └── web/
        └── snapds.config.json    ← extends root, overrides packages

// apps/web/snapds.config.json
{
  "extends": "../../snapds.config.json",
  "packages": [
    { "name": "@acme/web-ui", "importPath": "@acme/web-ui" }
  ]
}

Resolution rules:

• Snapds walks up from the active file and uses the nearest snapds.config.json.
• The extends chain is followed recursively (cycle-safe).
• Child values win on deep merge; arrays are replaced (not concatenated).
• Packages are merged per-name — a child package entry overrides only the fields it sets.

Managing components in the Settings panel

The Components tab of the Settings panel is where you pick which components each package contributes to the gallery and skills.

• Scope filters — chips above the list narrow it to one or more npm scopes (e.g. @acme, @radix-ui). Two uppercase meta-buckets lead the row: LOCAL (in-repo component sources — see below) and UNSCOPED (packages with no npm scope, like lucide-react or cmdk), so both stay reachable when a filter is active. Selecting chips ORs them together; typing in the filter box narrows further. Active chips are persisted to scopeFilters.
• Select all / Deselect all — open a package card and use the toggle at the top of the component list to select or clear every component in one action. The button flips its label to reflect the current state — handy for packages that export hundreds of components.
• Local component sources — in-repo design systems (shadcn or your own folder) are supported alongside npm packages. A components.json is auto-detected and offered via a one-click banner; you can also register any folder with + Local folder (Snapds derives the import alias from your tsconfig paths, or asks for it). Local sources show a LOCAL badge with their import alias printed under the name (e.g. → @/components/ui), group under the LOCAL filter chip, inject imports from that path alias (e.g. @/components/ui/button), and re-index live as you edit their files. The Components tab carries a short hint — and, when nothing is selected yet, a guided empty state — spelling out the difference between npm packages (node_modules) and local folders (path alias) so the two paradigms are clear. A manually-added folder you no longer want shows a Remove (trash) button that unregisters it for good.
• Hide packages you don’t need — every card in Available has a hide (eye) button that drops it from the list, useful when the workspace pulls in packages you’ll never inject. Hidden ones collapse behind a Show hidden (N) toggle; reveal them and click the eye again to unhide. This declutter is personal and workspace-local (snapds.hiddenPackages in workspace state) — it isn’t written to snapds.config.json and doesn’t affect teammates. Auto-detected sources are hidden rather than removed (they’d re-appear on the next scan); only manually-added local folders can be truly removed.
• Discard changes — reverts unsaved component selections to the last saved state without closing the panel.

Export & import config

The Settings panel has two buttons at the top right:

Export config generates a snapds.config.json from your current settings. Options:

• Include my overrides — optionally bundle your local component overrides into the file.
• Replace (default when no file exists) / Merge (only write changed fields) — choose when a file already exists.

Load config imports a config file into your local settings. Before applying, a preview shows exactly what will change (packages added / removed / updated, overrides count, skills and scope filter changes). You can also opt in to applying any component overrides included in the file.

When Snapds detects a snapds.config.json at startup that differs from your current settings, it shows a notification. The notification reappears whenever the file content changes — so if a teammate updates the config, you’ll be prompted on your next launch. A banner in the Settings panel also lets you load or review the config at any time.