Import Paths - Convenzione @/

📝 Convenzione

Il progetto utilizza path alias con @/ per importare moduli dalla cartella app/ invece di path relativi.

✅ Configurazione

TypeScript (tsconfig.json)

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./app/*"]
    }
  }
}

Vite (vite.config.ts)

import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [
    tsconfigPaths() // Legge automaticamente i paths da tsconfig.json
  ]
});

Vitest (vitest.config.ts)

import tsconfigPaths from "vite-tsconfig-paths";
import path from "path";

export default defineConfig({
  plugins: [tsconfigPaths()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./app"),
    },
  },
});

🎯 Esempi

❌ Prima (path relativi)

// Da app/routes/auth/login.tsx
import { authService } from "../../lib/auth/auth";
import { createGuestLoader } from "../../lib/auth/loaders";
import { useAuthStore } from "../../store/auth/auth.store";

// Da app/components/auth/AuthenticatedLayout.tsx
import { useCartStore } from "../../store/cart/cart.store";
import { useMessagesStore } from "../../store/messages/messages.store";
import { Cart } from "../cart/Cart";

// Da tests/auth/api.test.ts
import { login } from "../../app/api/auth/auth.api";
import { useAuthStore } from "../../app/store/auth/auth.store";

✅ Dopo (path alias @/)

// Da app/routes/auth/login.tsx
import { authService } from "@/lib/auth/auth";
import { createGuestLoader } from "@/lib/auth/loaders";
import { useAuthStore } from "@/store/auth/auth.store";

// Da app/components/auth/AuthenticatedLayout.tsx
import { useCartStore } from "@/store/cart/cart.store";
import { useMessagesStore } from "@/store/messages/messages.store";
import { Cart } from "@/components/cart/Cart";

// Da tests/auth/api.test.ts
import { login } from "@/api/auth/auth.api";
import { useAuthStore } from "@/store/auth/auth.store";

📦 Struttura Import

@/                          → app/
├── api/                   → app/api/
│   ├── auth/             → app/api/auth/
│   └── warehouse/        → app/api/warehouse/
├── components/            → app/components/
│   ├── auth/             → app/components/auth/
│   └── cart/             → app/components/cart/
├── hooks/                 → app/hooks/
│   ├── api/              → app/hooks/api/
│   ├── iframe/           → app/hooks/iframe/
│   ├── sync/             → app/hooks/sync/
│   ├── ui/               → app/hooks/ui/
│   └── utils/            → app/hooks/utils/
├── lib/                   → app/lib/
│   └── auth/             → app/lib/auth/
├── routes/                → app/routes/
│   └── auth/             → app/routes/auth/
├── schemas/               → app/schemas/
│   ├── auth/             → app/schemas/auth/
│   └── warehouse/        → app/schemas/warehouse/
└── store/                 → app/store/
    ├── auth/             → app/store/auth/
    ├── cart/             → app/store/cart/
    └── messages/         → app/store/messages/

🎨 Casi Speciali

Import da stessa cartella

Usa path relativi per file nella stessa directory:

// ✅ OK - stessa cartella
import { AuthService } from "./auth";
import type { Route } from "./+types/login";

Import di tipi generati da React Router

Usa sempre path relativi per i tipi generati:

// ✅ OK - file generato da React Router
import type { Route } from "./+types/login";

Import in test

Usa @/ anche nei test:

// tests/auth/api.test.ts
import { login } from "@/api/auth/auth.api";
import { useAuthStore } from "@/store/auth/auth.store";

✨ Vantaggi

1. Leggibilità: @/lib/auth/auth è più chiaro di ../../../lib/auth/auth
2. Manutenibilità: Non devi aggiornare i path quando sposti i file
3. Refactoring: Più facile spostare file senza rompere gli import
4. Autocomplete: Migliore supporto IDE con path assoluti
5. Consistenza: Stesso pattern in tutto il progetto

🚫 Errori Comuni

❌ Non usare path relativi lunghi

import { authService } from "../../../lib/auth/auth";

✅ Usa sempre @/

import { authService } from "@/lib/auth/auth";

❌ Non mescolare convenzioni

// ❌ Cattivo - mix di stili
import { authService } from "@/lib/auth/auth";
import { useAuthStore } from "../../store/auth/auth.store";

✅ Sii consistente

// ✅ Buono - un solo stile
import { authService } from "@/lib/auth/auth";
import { useAuthStore } from "@/store/auth/auth.store";

🔧 Migrazione

Se hai file con path relativi, puoi convertirli facilmente:

# Cerca file con import relativi
grep -r "from \"\.\./\.\./app/" .

# O usa l'IDE per refactoring automatico

📚 Riferimenti

• TypeScript Path Mapping
• Vite Path Aliases
• vite-tsconfig-paths