How to fix path mapping must start with "*" in TypeScript

First, examine your tsconfig.json file to see the current paths configuration:

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      // Check these mappings for syntax errors
      "@components/*": ["components/*"],
      "@utils/*": ["utils/*"],
      "@/*": ["./*"]
    }
  }
}

Look for any path mappings that don't start with "*". The correct syntax requires the wildcard at the beginning of the pattern on the left side.

Correct the path mapping syntax by ensuring all patterns start with "*":

// WRONG - missing * at beginning
{
  "paths": {
    "components": ["src/components"]  // ✗ Error: doesn't start with *
  }
}

// CORRECT - pattern starts with *
{
  "paths": {
    "@components/*": ["src/components/*"]  // ✓ Correct
  }
}

// WRONG - * in wrong position
{
  "paths": {
    "components/*/utils": ["src/components/*/utils"]  // ✗ * not at beginning
  }
}

// CORRECT - * at beginning
{
  "paths": {
    "@components/*/utils/*": ["src/components/*/utils/*"]  // ✓ Correct
  }
}

Remember: The pattern on the left side (the import alias) must start with "*" if you want to use wildcards.

Ensure you have a baseUrl set in your compiler options, as path mappings are relative to this base:

{
  "compilerOptions": {
    "baseUrl": "./src",  // Required for path mappings
    "paths": {
      "@components/*": ["components/*"]  // Resolves to ./src/components/*
    }
  }
}

Without baseUrl, TypeScript won't know where to resolve the paths from. The baseUrl should point to the directory where your source code lives.

After fixing the path mappings, test them with a simple import:

// With correct configuration:
// tsconfig.json:
// {
//   "compilerOptions": {
//     "baseUrl": "./src",
//     "paths": {
//       "@components/*": ["components/*"]
//     }
//   }
// }

// This should now work:
import { Button } from "@components/Button";
import { Header } from "@components/layout/Header";

Run TypeScript compilation to verify:

npx tsc --noEmit

If there are no errors, your path mappings are correctly configured.

After making changes to tsconfig.json, restart the TypeScript language server in your IDE:

VS Code:
1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
2. Type "TypeScript: Restart TS Server"
3. Select the command

WebStorm/IntelliJ:
1. Go to File → Invalidate Caches...
2. Select "Invalidate and Restart"

Other editors: Consult your editor's documentation for restarting the TypeScript language server.

This ensures your IDE picks up the new path mapping configuration.

If you're having persistent issues with path mappings, consider these alternatives:

1. Use relative imports instead:

// Instead of @components/Button
import { Button } from "../../components/Button";

2. Use npm packages for path resolution:

npm install --save-dev tsconfig-paths

Then run your code with:

node -r tsconfig-paths/register dist/index.js

3. Use a bundler with built-in path resolution:
- Webpack: resolve.alias in webpack.config.js
- Vite: Supports tsconfig paths natively
- esbuild: Use --alias: flag or plugins