How Open-SEO Handles Module Resolution with Its tsconfig.json: A Complete Guide

Open-SEO uses a bundler-style module resolution strategy defined in its root tsconfig.json, combining "moduleResolution": "Bundler" with a @/* path alias that stays synchronized with Vite via the vite-tsconfig-paths plugin.

The every-app/open-seo repository demonstrates modern TypeScript module resolution by leveraging the Bundler strategy alongside intelligent path mapping. Understanding how open-seo handles module resolution with its tsconfig.json reveals a seamless integration between TypeScript's compiler options and Vite's build pipeline, ensuring consistent import behavior across development and production.

Configuring the Bundler Module Resolution Strategy

In tsconfig.json at line 9, Open-SEO explicitly sets the resolution mode:

{
  "compilerOptions": {
    "moduleResolution": "Bundler"
  }
}

This configuration tells TypeScript to resolve imports exactly as modern bundlers like Vite and Webpack do. Unlike the traditional Node resolution strategy, the Bundler mode properly handles bare imports from node_modules, relative file-system paths, and modern package.json fields including exports and imports.

Setting Up Path Aliases in tsconfig.json

Lines 19-20 of tsconfig.json define a project-wide alias that eliminates brittle relative paths:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

This mapping allows developers to import modules using @/ as a root-relative reference to the src/ directory. Instead of writing ../../../components/Button, you can write @/components/Button, making refactors safer and imports more readable.

Bridging TypeScript Paths to Vite

While TypeScript understands the paths configuration during type-checking, Vite requires explicit knowledge of these aliases to resolve them at build time. In vite.config.ts at line 56, Open-SEO registers the vite-tsconfig-paths plugin:

// vite.config.ts
import { defineConfig } from 'vite';
import tsConfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    tsConfigPaths(), // Line 56: Reads and applies tsconfig.json paths
    // ... other plugins
  ],
});

This plugin reads the tsconfig.json configuration and automatically injects the corresponding Vite alias definitions. Consequently, the @/ prefix resolves identically during both the TypeScript compilation phase and Vite's bundling process.

Practical Code Examples

Using the @/ Alias for Internal Imports

// src/components/Button.tsx
export const Button = () => <button>Click me</button>;

// src/pages/Home.tsx
import { Button } from '@/components/Button'; // ✅ Resolved via tsconfig paths

export const Home = () => (
  <main>
    <h1>Welcome to Open-SEO</h1>
    <Button />
  </main>
);

Resolving Third-Party ESM Packages

The Bundler resolution strategy also handles external dependencies correctly by honoring package.json#exports:

import dayjs from 'dayjs';

export const now = () => dayjs().format();

This import works without additional configuration because the Bundler mode understands modern package export maps, allowing Open-SEO to consume ESM and CommonJS packages seamlessly.

Summary

• Open-SEO configures "moduleResolution": "Bundler" in tsconfig.json (line 9) to align TypeScript with Vite's native ESM resolution.
• The @/* path alias defined in tsconfig.json lines 19-20 enables clean, absolute imports from the src/ directory.
• The vite-tsconfig-paths plugin registered in vite.config.ts (line 56) bridges TypeScript's type-checking with Vite's runtime resolution.
• This setup supports both internal project aliases and external package imports following the package.json exports standard.

Frequently Asked Questions

What is the advantage of using "Bundler" module resolution in TypeScript?

The Bundler module resolution strategy allows TypeScript to resolve imports exactly as modern build tools do, supporting package.json exports and imports fields while maintaining compatibility with both ESM and CommonJS packages. This eliminates resolution mismatches between the TypeScript compiler and your Vite bundler.

How does the @/ alias work in both TypeScript and Vite?

TypeScript recognizes the @/* mapping from the paths configuration in tsconfig.json during compilation and type-checking. Simultaneously, the vite-tsconfig-paths plugin reads this same configuration and creates corresponding Vite aliases, ensuring the paths resolve identically during development server startup and production builds.

Where is the vite-tsconfig-paths plugin configured in Open-SEO?

The plugin is registered in vite.config.ts at line 56 within the plugins array as tsConfigPaths(), which automatically detects and applies all path mappings defined in the project's tsconfig.json file without requiring manual alias configuration in the Vite config.

Can I add additional path aliases beyond @/ in Open-SEO?

Yes, you can extend the paths object in tsconfig.json with additional aliases such as "@components/*": ["./src/components/*"]. The vite-tsconfig-paths plugin will automatically synchronize these new mappings to Vite's resolution configuration, requiring no manual updates to vite.config.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}