VSCode Vuetify IntelliSense Extension Development

Expert guidance for working with the Vuetiful Vuetify VSCode extension codebase - a sophisticated utility class autocomplete system for Vuetify 3.

Project Overview

This VSCode extension provides IntelliSense (autocomplete and hover documentation) for Vuetify 3 utility classes. It extracts utility classes from Vuetify CSS files at runtime and provides intelligent completions in Vue, HTML, JavaScript, and TypeScript files.

Build & Development Commands

Use these commands for development and packaging:

```bash

Build the extension for production

npm run build

Build in watch mode (development)

npm run watch

Lint TypeScript files

npm run lint

Package the extension for distribution

npm run package

```

Architecture Understanding

Pipeline Architecture

The extension uses a clean pipeline with separation of concerns:

1. **VuetifyExtractor** (`src/extractor.ts`) - Main orchestrator coordinating extraction

2. **VuetifyFinder** (`src/finder.ts`) - Locates Vuetify in node_modules (monorepo-aware)

3. **CSSParser** (`src/parser.ts`) - Parses CSS with `css-tree` to extract utilities

4. **VuetifyCache** (`src/cache.ts`) - Two-tier caching (memory + VSCode workspace state)

5. **VuetifyWatcher** (`src/watcher.ts`) - Watches package.json and CSS file changes

6. **Providers** (`src/providers/`) - VSCode language providers for completions/hover

Data Flow

```

Extension Activation

→ VuetifyExtractor.extractAll()

→ VuetifyFinder.findAll() [locates Vuetify in node_modules]

→ VuetifyCache.get() [checks cache]

→ CSSParser.parseCSS() [if cache miss]

→ VuetifyCache.set() [stores results]

→ Providers registered with VSCode

```

Key Design Patterns

Type System

Core data structures in `src/types.ts`:

Development Workflow

When Adding Features

1. **Read the relevant modules first** - Understand existing patterns before modifying

2. **Follow the pipeline** - Each module has a single responsibility

3. **Preserve strict TypeScript** - All strict checks are enabled

4. **Update types** - Add new interfaces to `src/types.ts` when needed

5. **Test with logging** - Enable detailed logging for debugging

When Debugging

1. Enable detailed logging:

- Set `vuetifulVuetify.enableLogging: true` in VSCode settings

- View logs in Output panel (select "Vuetiful Vuetify")

2. The `Logger` class (`src/logger.ts`) provides contextual logging per module

3. Check the pipeline flow:

- Is Vuetify being found? (Finder logs)

- Is cache being hit? (Cache logs)

- Are utilities being parsed? (Parser logs)

Monorepo & Package Manager Support

The finder (`src/finder.ts`) searches multiple locations intelligently:

**When extending finder logic**: Always test with multiple package managers and monorepo structures.

CSS Parsing Strategy

The parser (`src/parser.ts`) uses sophisticated filtering:

**When adding utility categories**: Update `UTILITY_PREFIXES` constant and category mapping logic.

Build System

Uses `esbuild` (configured in `esbuild.config.js`):

TypeScript Configuration

Strict configuration ensures code quality:

**Never disable strict checks** - Fix the underlying issue instead.

Code Modification Guidelines

1. **Read before writing** - Understand existing implementation patterns

2. **Preserve architecture** - Don't bypass the pipeline

3. **Maintain caching** - Cache invalidation is critical for correctness

4. **Test multi-workspace** - Test with multiple workspace folders

5. **Test monorepos** - Test with pnpm, yarn workspaces, lerna

6. **Validate CSS parsing** - Ensure new Vuetify utilities are captured

7. **Keep providers simple** - Complexity belongs in extractor/parser

8. **Log appropriately** - Use the Logger class for debugging info

Common Tasks

Adding Support for New Utility Patterns

1. Update `UTILITY_PREFIXES` in `src/parser.ts`

2. Add category mapping logic if needed

3. Update description generation for new category

4. Test with real Vuetify CSS file

Improving Cache Performance

1. Check cache hit rates in logs

2. Verify hash-based invalidation is working

3. Consider memory cache size limits

4. Ensure workspace state persistence works

Supporting New File Types

1. Add language selector in provider registration (extension.ts)

2. Test completion trigger characters

3. Verify hover works in new file type

Debugging Extraction Failures

1. Enable logging and check Output panel

2. Verify Vuetify installation is found

3. Check CSS file path resolution

4. Validate CSS parsing isn't throwing errors

5. Inspect cache entries for corruption