feat(migrate/create): add TypeScript shim for Vue and Astro component files

packages/cli/snap-tests-global/migration-framework-shim-vue/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "migration-framework-shim-vue",
+  "devDependencies": {
+    "vite": "^7.0.0",
+    "vue": "^3.0.0"
+  }
+}

packages/cli/snap-tests-global/migration-framework-shim-vue/snap.txt

@@ -0,0 +1,10 @@
+> vp migrate --no-interactive --no-hooks # migration should add Vue shim when vue dependency is detected
+VITE+ - The Unified Toolchain for the Web
+
+◇ Migrated . to Vite+<repeat>
+• Node <semver>  pnpm <semver>
+✓ Dependencies installed in <variable>ms
+• 1 config update applied
+
+[1]> cat src/env.d.ts # check Vue shim was written
+cat: src/env.d.ts: No such file or directory

packages/cli/snap-tests-global/migration-framework-shim-vue/steps.json

@@ -0,0 +1,12 @@
+{
+  "ignoredPlatforms": ["win32"],
+  "env": {
+    "VITE_DISABLE_AUTO_INSTALL": "1",
+    "CI": "",
+    "VP_SKIP_INSTALL": ""
+  },
+  "commands": [
+    "vp migrate --no-interactive --no-hooks # migration should add Vue shim when vue dependency is detected",
+    "cat src/env.d.ts # check Vue shim was written"
+  ]
+}

packages/cli/src/migration/__tests__/migrator.spec.ts

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { PackageManager } from '../../types/index.js';
+import { createMigrationReport } from '../report.js';
 
 // Mock VITE_PLUS_VERSION to a stable value for snapshot tests.
 // When tests run via `vp test`, the env var is injected with the actual version,
@@ -21,6 +22,9 @@ const {
   parseNvmrcVersion,
   detectNodeVersionManagerFile,
   migrateNodeVersionManagerFile,
+  detectFramework,
+  hasFrameworkShim,
+  addFrameworkShim,
 } = await import('../migrator.js');
 
 describe('rewritePackageJson', () => {
@@ -304,6 +308,7 @@ describe('migrateNodeVersionManagerFile', () => {
       prettierMigrated: false,
       nodeVersionFileMigrated: false,
       gitHooksConfigured: false,
+      frameworkShimAdded: false,
       warnings: [],
       manualSteps: [],
     };
@@ -334,6 +339,7 @@ describe('migrateNodeVersionManagerFile', () => {
       prettierMigrated: false,
       nodeVersionFileMigrated: false,
       gitHooksConfigured: false,
+      frameworkShimAdded: false,
       warnings: [],
       manualSteps: [],
     };
@@ -366,6 +372,7 @@ describe('migrateNodeVersionManagerFile', () => {
       prettierMigrated: false,
       nodeVersionFileMigrated: false,
       gitHooksConfigured: false,
+      frameworkShimAdded: false,
       warnings: [],
       manualSteps: [],
     };
@@ -401,6 +408,7 @@ describe('migrateNodeVersionManagerFile', () => {
       prettierMigrated: false,
       nodeVersionFileMigrated: false,
       gitHooksConfigured: false,
+      frameworkShimAdded: false,
       warnings: [],
       manualSteps: [],
     };
@@ -638,3 +646,110 @@ describe('rewriteMonorepo bun catalog', () => {
     expect(workspaces.packages).toEqual(['packages/*']);
   });
 });
+
+describe('framework shim', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vp-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('detectFramework', () => {
+    it('returns vue when vue is in devDependencies', () => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        JSON.stringify({ devDependencies: { vue: '^3.0.0' } }),
+      );
+      expect(detectFramework(tmpDir)).toBe('vue');
+    });
+
+    it('returns astro when astro is in devDependencies', () => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        JSON.stringify({ devDependencies: { astro: '^4.0.0' } }),
+      );
+      expect(detectFramework(tmpDir)).toBe('astro');
+    });
+
+    it('returns null when no framework dependency is present', () => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'package.json'),
+        JSON.stringify({ devDependencies: { vite: '^7.0.0' } }),
+      );
+      expect(detectFramework(tmpDir)).toBeNull();
+    });
+
+    it('returns null when package.json does not exist', () => {
+      expect(detectFramework(tmpDir)).toBeNull();
+    });
+  });
+
+  describe('hasFrameworkShim', () => {
+    it('returns true when src/env.d.ts contains vue shim', () => {
+      const srcDir = path.join(tmpDir, 'src');
+      fs.mkdirSync(srcDir);
+      fs.writeFileSync(
+        path.join(srcDir, 'env.d.ts'),
+        "declare module '*.vue' { export default {} }\n",
+      );
+      expect(hasFrameworkShim(tmpDir, 'vue')).toBe(true);
+    });
+
+    it('returns false when src/env.d.ts does not contain vue shim', () => {
+      const srcDir = path.join(tmpDir, 'src');
+      fs.mkdirSync(srcDir);
+      fs.writeFileSync(path.join(srcDir, 'env.d.ts'), '/// <reference types="vite-plus/client" />\n');
+      expect(hasFrameworkShim(tmpDir, 'vue')).toBe(false);
+    });
+
+    it('returns false when env.d.ts does not exist', () => {
+      expect(hasFrameworkShim(tmpDir, 'vue')).toBe(false);
+    });
+
+    it('returns true when root env.d.ts contains astro/client reference', () => {
+      fs.writeFileSync(
+        path.join(tmpDir, 'env.d.ts'),
+        '/// <reference types="astro/client" />\n',
+      );
+      expect(hasFrameworkShim(tmpDir, 'astro')).toBe(true);
+    });
+  });
+
+  describe('addFrameworkShim', () => {
+    it('creates src/env.d.ts with vue shim when src/ exists and no env.d.ts', () => {
+      fs.mkdirSync(path.join(tmpDir, 'src'));
+      addFrameworkShim(tmpDir, 'vue');
+      const content = fs.readFileSync(path.join(tmpDir, 'src', 'env.d.ts'), 'utf-8');
+      expect(content).toContain("declare module '*.vue'");
+      expect(content).toContain('DefineComponent');
+    });
+
+    it('creates root env.d.ts with vue shim when no src/ dir', () => {
+      addFrameworkShim(tmpDir, 'vue');
+      const content = fs.readFileSync(path.join(tmpDir, 'env.d.ts'), 'utf-8');
+      expect(content).toContain("declare module '*.vue'");
+    });
+
+    it('appends vue shim to existing src/env.d.ts', () => {
+      const srcDir = path.join(tmpDir, 'src');
+      fs.mkdirSync(srcDir);
+      const existing = '/// <reference types="vite-plus/client" />\n';
+      fs.writeFileSync(path.join(srcDir, 'env.d.ts'), existing);
+      addFrameworkShim(tmpDir, 'vue');
+      const content = fs.readFileSync(path.join(srcDir, 'env.d.ts'), 'utf-8');
+      expect(content).toContain('/// <reference types="vite-plus/client" />');
+      expect(content).toContain("declare module '*.vue'");
+    });
+
+    it('sets frameworkShimAdded on report', () => {
+      fs.mkdirSync(path.join(tmpDir, 'src'));
+      const report = createMigrationReport();
+      addFrameworkShim(tmpDir, 'vue', report);
+      expect(report.frameworkShimAdded).toBe(true);
+    });
+  });
+});

packages/cli/src/migration/bin.ts

@@ -41,11 +41,14 @@ import { accent, log, muted } from '../utils/terminal.ts';
 import type { PackageDependencies } from '../utils/types.ts';
 import { detectWorkspace } from '../utils/workspace.ts';
 import {
+  addFrameworkShim,
   checkVitestVersion,
   checkViteVersion,
   detectEslintProject,
+  detectFramework,
   detectNodeVersionManagerFile,
   detectPrettierProject,
+  hasFrameworkShim,
   installGitHooks,
   mergeViteConfigFiles,
   migrateEslintToOxlint,
@@ -54,6 +57,7 @@ import {
   preflightGitHooksSetup,
   rewriteMonorepo,
   rewriteStandaloneProject,
+  type Framework,
   type NodeVersionManagerDetection,
 } from './migrator.ts';
 import { createMigrationReport, type MigrationReport } from './report.ts';
@@ -204,6 +208,30 @@ async function confirmNodeVersionFileMigration(
   return true;
 }
 
+async function confirmFrameworkShim(
+  framework: Framework,
+  interactive: boolean,
+): Promise<boolean> {
+  const frameworkNames: Record<Framework, string> = { vue: 'Vue', astro: 'Astro' };
+  const name = frameworkNames[framework];
+  if (interactive) {
+    const confirmed = await prompts.confirm({
+      message:
+        `Add TypeScript shim for ${name} component files (*.${framework})?\n  ` +
+        styleText(
+          'gray',
+          `Lets TypeScript recognize .${framework} files until vp check fully supports them.`,
+        ),
+      initialValue: true,
+    });
+    if (prompts.isCancel(confirmed)) {
+      cancelAndExit();
+    }
+    return confirmed;
+  }
+  return true;
+}
+
 const helpMessage = renderCliDoc({
   usage: 'vp migrate [PATH] [OPTIONS]',
   summary:
@@ -356,6 +384,7 @@ interface MigrationPlan {
   prettierConfigFile?: string;
   migrateNodeVersionFile: boolean;
   nodeVersionDetection?: NodeVersionManagerDetection;
+  frameworkShimFramework?: Framework;
 }
 
 async function collectMigrationPlan(
@@ -493,6 +522,16 @@ async function collectMigrationPlan(
     );
   }
 
+  // 11. Framework shim detection + prompt
+  const detectedFramework = detectFramework(rootDir);
+  let frameworkShimFramework: Framework | undefined;
+  if (detectedFramework && !hasFrameworkShim(rootDir, detectedFramework)) {
+    const addShim = await confirmFrameworkShim(detectedFramework, options.interactive);
+    if (addShim) {
+      frameworkShimFramework = detectedFramework;
+    }
+  }
+
   const plan: MigrationPlan = {
     packageManager,
     shouldSetupHooks,
@@ -506,6 +545,7 @@ async function collectMigrationPlan(
     prettierConfigFile: prettierProject.configFile,
     migrateNodeVersionFile,
     nodeVersionDetection,
+    frameworkShimFramework,
   };
 
   return plan;
@@ -588,6 +628,9 @@ function showMigrationSummary(options: {
   if (report.gitHooksConfigured) {
     log(`${styleText('gray', '•')} Git hooks configured`);
   }
+  if (report.frameworkShimAdded) {
+    log(`${styleText('gray', '•')} TypeScript shim added for framework component files`);
+  }
   if (report.warnings.length > 0) {
     log(`${styleText('yellow', '!')} Warnings:`);
     for (const warning of report.warnings) {
@@ -807,7 +850,13 @@ async function executeMigrationPlan(
     silent: true,
   });
 
-  // 11. Reinstall after migration
+  // 11. Add framework shim if requested
+  if (plan.frameworkShimFramework) {
+    updateMigrationProgress('Adding TypeScript shim');
+    addFrameworkShim(workspaceInfo.rootDir, plan.frameworkShimFramework, report);
+  }
+
+  // 12. Reinstall after migration
   // npm needs --force to re-resolve packages with newly added overrides,
   // otherwise the stale lockfile prevents override resolution.
   const installArgs =

packages/cli/src/migration/migrator.ts

@@ -683,6 +683,88 @@ function cleanupDeprecatedTsconfigOptions(
   }
 }
 
+// Svelte is intentionally excluded: @sveltejs/vite-plugin-svelte and svelte-check handle
+// .svelte file types automatically. No env.d.ts shim is needed or documented officially.
+// https://svelte.dev/docs/svelte/typescript
+export type Framework = 'vue' | 'astro';
+
+const FRAMEWORK_SHIMS: Record<Framework, string> = {
+  // https://vuejs.org/guide/typescript/overview#volar-takeover-mode
+  vue: [
+    "declare module '*.vue' {",
+    "  import type { DefineComponent } from 'vue';",
+    '  const component: DefineComponent<{}, {}, unknown>;',
+    '  export default component;',
+    '}',
+  ].join('\n'),
+  // astro/client is the pre-v4.14 form; v4.14+ prefers `/// <reference path="../.astro/types.d.ts" />`
+  // but .astro/types.d.ts is generated at build time and may not exist yet after migration.
+  // astro/client remains valid and is still used in official Astro integrations.
+  // https://docs.astro.build/en/guides/typescript/#extending-global-types
+  astro: '/// <reference types="astro/client" />',
+};
+
+export function detectFramework(projectPath: string): Framework | null {
+  const packageJsonPath = path.join(projectPath, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return null;
+  }
+  const pkg = readJsonFile(packageJsonPath) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+  const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+  for (const framework of ['vue', 'astro'] as const) {
+    if (allDeps[framework]) {
+      return framework;
+    }
+  }
+  return null;
+}
+
+function getEnvDtsPath(projectPath: string): string {
+  const srcEnvDts = path.join(projectPath, 'src', 'env.d.ts');
+  const rootEnvDts = path.join(projectPath, 'env.d.ts');
+  for (const candidate of [srcEnvDts, rootEnvDts]) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return fs.existsSync(path.join(projectPath, 'src')) ? srcEnvDts : rootEnvDts;
+}
+
+export function hasFrameworkShim(projectPath: string, framework: Framework): boolean {
+  const envDtsPath = getEnvDtsPath(projectPath);
+  if (!fs.existsSync(envDtsPath)) {
+    return false;
+  }
+
+  const content = fs.readFileSync(envDtsPath, 'utf-8');
+  if (framework === 'astro') {
+    return content.includes('astro/client');
+  }
+  return content.includes(`'*.${framework}'`) || content.includes(`"*.${framework}"`);
+}
+
+export function addFrameworkShim(
+  projectPath: string,
+  framework: Framework,
+  report?: MigrationReport,
+): void {
+  const envDtsPath = getEnvDtsPath(projectPath);
+  const shim = FRAMEWORK_SHIMS[framework];
+  if (fs.existsSync(envDtsPath)) {
+    const existing = fs.readFileSync(envDtsPath, 'utf-8');
+    fs.writeFileSync(envDtsPath, `${existing.trimEnd()}\n\n${shim}\n`, 'utf-8');
+  } else {
+    fs.mkdirSync(path.dirname(envDtsPath), { recursive: true });
+    fs.writeFileSync(envDtsPath, `${shim}\n`, 'utf-8');
+  }
+  if (report) {
+    report.frameworkShimAdded = true;
+  }
+}
+
 /**
  * Rewrite standalone project to add vite-plus dependencies
  * @param projectPath - The path to the project