Typescript Shims

TypeScript Shims Skill

Purpose

Generate TypeScript declaration files (shims) to enable type-safe imports of non-TypeScript modules in a Vue 3 application.

Output

Create the files:

• /src/shims-vue.d.ts
• /src/shims-svg.d.ts

Configuration Requirements

Vue Component Shims (shims-vue.d.ts)

Purpose

Enable TypeScript to recognize and properly type .vue single-file components when imported into TypeScript files.

Requirements

• Module Declaration: Declare a module pattern for *.vue files
• Vue Integration: Import the appropriate component type from the Vue package
• Component Type: Type the default export as a Vue component definition
• Generic Typing: Use appropriate generic parameters to allow flexibility in component props, emits, and other options

Key Concepts

• Without this file, TypeScript cannot understand what a .vue file exports
• The shim tells TypeScript that any .vue import is a valid Vue component
• Should use Vue 3's component typing system (not Vue 2's)
• Must align with your Vue version's type definitions

SVG Asset Shims (shims-svg.d.ts)

Purpose

Enable importing SVG files in multiple ways: as Vue components or as URL strings.

Requirements

SVG as Component Import

• Module Declaration: Declare a module pattern for *.svg files
• Component Type: Type the default export as a Vue component
• Use Case: Allows inline SVG usage as <MySvgIcon /> in templates

SVG as URL Import

• Module Declaration: Declare a module pattern for *.svg?url files (with query parameter)
• String Type: Type the default export as a string (URL path)
• Use Case: Allows using SVG as image source: <img :src="logoUrl" />

Key Concepts

• Supports Vite's asset handling with query parameters
• Two import styles for different use cases:
  • Direct import: treats SVG as inline component
  • Query parameter import: treats SVG as static asset URL
• Aligns with modern bundler conventions (Vite, Webpack 5+)

Implementation Guidelines

Vue Shims Best Practices

• Import component types from the main Vue package (not from separate type packages)
• Use the most current component definition types available in your Vue version
• Keep generic parameters flexible unless specific constraints are needed
• Ensure compatibility with <script setup> and Options API components

SVG Shims Best Practices

• Support both component and URL import patterns
• Use query parameter syntax that matches your bundler (typically ?url for Vite)
• Keep shims minimal and focused on typing, not implementation
• Consider supporting additional query parameters if your build tool offers them (e.g., ?raw, ?component)

Validation

After generating the shims:

1. Vue Import Test: Verify you can import .vue files without TypeScript errors
2. SVG Component Test: Verify you can import and use SVG as a component
3. SVG URL Test: Verify you can import SVG with ?url suffix and use as string
4. IDE Support: Check that autocomplete and type hints work for these imports
5. Build Success: Ensure the application builds without type errors

Integration Notes

TypeScript Configuration

• Include these shim files in your tsconfig.json include array
• Example: "include": ["src/**/*.d.ts"] or explicitly list the shim files

Build Tool Compatibility

• Vite: Uses ?url query parameter syntax for asset URLs
• Webpack: May use different loaders; adjust query parameters as needed
• Other Bundlers: Consult documentation for asset import conventions

Vue Version Compatibility

• Vue 3: Use modern component type definitions (e.g., DefineComponent)
• Future Versions: Adopt new type definitions as Vue evolves
• Type-only Imports: Consider using import type for type-only imports to avoid runtime overhead

Extension Possibilities

As your application grows, you may need additional shims for:

• Image Files: .png, .jpg, .webp imports
• Font Files: .woff, .woff2, .ttf imports
• JSON Files: If not covered by TypeScript's resolveJsonModule
• CSS Modules: .module.css, .module.scss imports
• Web Workers: .worker.ts imports
• WASM Modules: .wasm imports

Follow the same pattern: declare the module, specify the import type, and ensure alignment with your bundler's behavior.

Philosophy

These shims exist to:

• Bridge the Gap: Connect TypeScript's type system with non-TypeScript assets
• Enable Type Safety: Catch import errors at compile time rather than runtime
• Support Modern Workflows: Work seamlessly with modern build tools and asset handling
• Stay Minimal: Provide just enough typing without overcomplicating

Future Compatibility

When TypeScript or Vue evolves:

• Update to use the latest component type definitions from Vue
• Adopt new TypeScript declaration syntax as it becomes available
• Adjust module patterns to match bundler conventions
• Maintain the core principle: type-safe imports for all asset types
• Remove deprecated type definitions and replace with modern equivalents