Konfiguracja TypeScript: Mistrzostwo Opcji Kompilatora TSConfig

Plik tsconfig.json jest sercem każdego projektu TypeScript. Określa on, w jaki sposób kompilator TypeScript (tsc) przekształca pliki .ts na JavaScript. Dobrze skonfigurowany tsconfig.json jest kluczowy dla utrzymania jakości kodu, zapewnienia kompatybilności w różnych środowiskach i optymalizacji procesu budowania. Ten kompleksowy przewodnik zagłębia się w zaawansowane opcje tsconfig.json, umożliwiając precyzyjne dostrojenie projektów TypeScript w celu uzyskania najwyższej wydajności i możliwości konserwacji.

Podstawy: Dlaczego TSConfig ma znaczenie

Zanim zagłębimy się w zaawansowane opcje, przypomnijmy sobie, dlaczego tsconfig.json jest tak ważny:

• Kontrola kompilacji: Określa, które pliki powinny być dołączone do projektu i jak powinny być kompilowane.
• Sprawdzanie typów: Definiuje zasady i rygor sprawdzania typów, pomagając wcześnie wykrywać błędy w cyklu rozwoju.
• Kontrola wyjścia: Określa docelową wersję JavaScript, system modułów i katalog wyjściowy.
• Integracja IDE: Dostarcza cennych informacji do IDE (takich jak VS Code, WebStorm itp.) dla funkcji takich jak uzupełnianie kodu, podświetlanie błędów i refaktoryzacja.

Bez pliku tsconfig.json kompilator TypeScript użyje ustawień domyślnych, które mogą nie być odpowiednie dla wszystkich projektów. Może to prowadzić do nieoczekiwanego zachowania, problemów ze zgodnością i mniej niż idealnego doświadczenia deweloperskiego.

Tworzenie TSConfig: Szybki start

Aby utworzyć plik tsconfig.json, wystarczy uruchomić następujące polecenie w katalogu głównym projektu:

            tsc --init
            

              
                Copy
              
            
          

Spowoduje to wygenerowanie podstawowego pliku tsconfig.json z kilkoma typowymi opcjami. Następnie można dostosować ten plik do konkretnych wymagań projektu.

Kluczowe opcje kompilatora: Szczegółowy przegląd

Plik tsconfig.json zawiera obiekt compilerOptions, w którym konfiguruje się kompilator TypeScript. Przeanalizujmy niektóre z najważniejszych i najczęściej używanych opcji:

target

Ta opcja określa docelową wersję ECMAScript dla skompilowanego kodu JavaScript. Określa, których funkcji JavaScript użyje kompilator, zapewniając kompatybilność ze środowiskiem docelowym (np. przeglądarkami, Node.js). Typowe wartości to ES5, ES6 (ES2015), ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Użycie ESNext będzie miało na celu najnowsze obsługiwane funkcje ECMAScript.

Przykład:

            "compilerOptions": {
  "target": "ES2020"
}
            

              
                Copy
              
            
          

Ta konfiguracja poinstruuje kompilator, aby wygenerował kod JavaScript zgodny z ECMAScript 2020.

module

Ta opcja określa system modułów, który ma być używany w skompilowanym kodzie JavaScript. Typowe wartości to CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 i ESNext. Wybór systemu modułów zależy od środowiska docelowego i używanego loadera modułów (np. Node.js, Webpack, Browserify).

Przykład:

            "compilerOptions": {
  "module": "CommonJS"
}
            

              
                Copy
              
            
          

Ta konfiguracja jest odpowiednia dla projektów Node.js, które zazwyczaj używają systemu modułów CommonJS.

lib

Ta opcja określa zestaw plików bibliotecznych, które mają zostać uwzględnione w procesie kompilacji. Te pliki biblioteczne udostępniają definicje typów dla wbudowanych interfejsów API JavaScript i interfejsów API przeglądarki. Typowe wartości to ES5, ES6, ES7, DOM, WebWorker, ScriptHost i inne.

Przykład:

            "compilerOptions": {
  "lib": ["ES2020", "DOM"]
}
            

              
                Copy
              
            
          

Ta konfiguracja zawiera definicje typów dla ECMAScript 2020 i interfejsu API DOM, co jest niezbędne dla projektów opartych na przeglądarce.

allowJs

Ta opcja pozwala kompilatorowi TypeScript kompilować pliki JavaScript obok plików TypeScript. Może to być przydatne podczas migracji projektu JavaScript do TypeScript lub podczas pracy z istniejącymi bazami kodu JavaScript.

Przykład:

            "compilerOptions": {
  "allowJs": true
}
            

              
                Copy
              
            
          

Po włączeniu tej opcji kompilator przetworzy zarówno pliki .ts, jak i .js.

checkJs

Ta opcja włącza sprawdzanie typów dla plików JavaScript. W połączeniu z allowJs, pozwala TypeScript zidentyfikować potencjalne błędy typów w kodzie JavaScript.

Przykład:

            "compilerOptions": {
  "allowJs": true,
  "checkJs": true
}
            

              
                Copy
              
            
          

Ta konfiguracja zapewnia sprawdzanie typów zarówno dla plików TypeScript, jak i JavaScript.

jsx

Ta opcja określa, w jaki sposób składnia JSX (używana w React i innych frameworkach) powinna być przekształcana. Typowe wartości to preserve, react, react-native i react-jsx. preserve pozostawia składnię JSX taką, jaka jest, react przekształca ją w wywołania React.createElement, react-native jest przeznaczone dla programowania React Native, a react-jsx przekształca ją w funkcje fabryczne JSX. react-jsxdev jest przeznaczone do celów programistycznych.

Przykład:

            "compilerOptions": {
  "jsx": "react"
}
            

              
                Copy
              
            
          

Ta konfiguracja jest odpowiednia dla projektów React, przekształcając JSX w wywołania React.createElement.

declaration

Ta opcja generuje pliki deklaracji (.d.ts) dla kodu TypeScript. Pliki deklaracji dostarczają informacji o typach dla kodu, umożliwiając innym projektom TypeScript lub JavaScript korzystanie z kodu z poprawnym sprawdzaniem typów.

Przykład:

            "compilerOptions": {
  "declaration": true
}
            

              
                Copy
              
            
          

Ta konfiguracja wygeneruje pliki .d.ts obok skompilowanych plików JavaScript.

declarationMap

Ta opcja generuje pliki mapy źródeł (.d.ts.map) dla wygenerowanych plików deklaracji. Mapy źródeł pozwalają debugerom i innym narzędziom mapować z powrotem do oryginalnego kodu źródłowego TypeScript podczas pracy z plikami deklaracji.

Przykład:

            "compilerOptions": {
  "declaration": true,
  "declarationMap": true
}
            

              
                Copy
              
            
          

sourceMap

Ta opcja generuje pliki mapy źródeł (.js.map) dla skompilowanego kodu JavaScript. Mapy źródeł pozwalają debugerom i innym narzędziom mapować z powrotem do oryginalnego kodu źródłowego TypeScript podczas debugowania w przeglądarce lub innych środowiskach.

Przykład:

            "compilerOptions": {
  "sourceMap": true
}
            

              
                Copy
              
            
          

outFile

Ta opcja łączy i emituje wszystkie pliki wyjściowe do jednego pliku. Jest to zwykle używane do tworzenia pakietów kodu dla aplikacji opartych na przeglądarkach.

Przykład:

            "compilerOptions": {
  "outFile": "dist/bundle.js"
}
            

              
                Copy
              
            
          

outDir

Ta opcja określa katalog wyjściowy dla skompilowanych plików JavaScript. Jeśli nie zostanie określony, kompilator umieści pliki wyjściowe w tym samym katalogu co pliki źródłowe.

Przykład:

            "compilerOptions": {
  "outDir": "dist"
}
            

              
                Copy
              
            
          

Ta konfiguracja umieści skompilowane pliki JavaScript w katalogu dist.

rootDir

Ta opcja określa katalog główny projektu TypeScript. Kompilator używa tego katalogu do rozpoznawania nazw modułów i generowania ścieżek do plików wyjściowych. Jest to szczególnie przydatne w przypadku złożonych struktur projektów.

Przykład:

            "compilerOptions": {
  "rootDir": "src"
}
            

              
                Copy
              
            
          

removeComments

Ta opcja usuwa komentarze ze skompilowanego kodu JavaScript. Może to pomóc w zmniejszeniu rozmiaru plików wyjściowych.

Przykład:

            "compilerOptions": {
  "removeComments": true
}
            

              
                Copy
              
            
          

noEmitOnError

Ta opcja uniemożliwia kompilatorowi emitowanie plików JavaScript, jeśli zostaną wykryte jakiekolwiek błędy typów. Zapewnia to, że generowany jest tylko prawidłowy kod.

Przykład:

            "compilerOptions": {
  "noEmitOnError": true
}
            

              
                Copy
              
            
          

strict

Ta opcja włącza wszystkie opcje ścisłego sprawdzania typów. Jest to wysoce zalecane dla nowych projektów, ponieważ pomaga wychwytywać potencjalne błędy i wymuszać najlepsze praktyki.

Przykład:

            "compilerOptions": {
  "strict": true
}
            

              
                Copy
              
            
          

Włączenie trybu ścisłego jest równoważne z włączeniem następujących opcji:

• noImplicitAny
• noImplicitThis
• alwaysStrict
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• noImplicitReturns
• noFallthroughCasesInSwitch

esModuleInterop

Ta opcja włącza interoperacyjność między modułami CommonJS i ES. Pozwala importować moduły CommonJS w modułach ES i odwrotnie.

Przykład:

            "compilerOptions": {
  "esModuleInterop": true
}
            

              
                Copy
              
            
          

forceConsistentCasingInFileNames

Ta opcja wymusza spójną wielkość liter w nazwach plików. Jest to ważne dla kompatybilności między platformami, ponieważ niektóre systemy operacyjne rozróżniają wielkość liter, a inne nie.

Przykład:

            "compilerOptions": {
  "forceConsistentCasingInFileNames": true
}
            

              
                Copy
              
            
          

baseUrl i paths

Te opcje pozwalają na skonfigurowanie rozpoznawania modułów. baseUrl określa katalog bazowy do rozpoznawania nazw modułów nierelatywnych, a paths pozwala na definiowanie niestandardowych aliasów modułów.

Przykład:

            "compilerOptions": {
  "baseUrl": ".",
  "paths": {
    "@components/*": ["src/components/*"],
    "@utils/*": ["src/utils/*"]
  }
}
            

              
                Copy
              
            
          

Ta konfiguracja pozwala na importowanie modułów za pomocą aliasów takich jak @components/MyComponent i @utils/myFunction.

Zaawansowana konfiguracja: Poza podstawami

Teraz przeanalizujmy niektóre zaawansowane opcje tsconfig.json, które mogą dodatkowo poprawić komfort tworzenia w TypeScript.

Kompilacja przyrostowa

TypeScript obsługuje kompilację przyrostową, która może znacznie przyspieszyć proces budowania dla dużych projektów. Aby włączyć kompilację przyrostową, ustaw opcję incremental na true i określ opcję tsBuildInfoFile.

Przykład:

            "compilerOptions": {
  "incremental": true,
  "tsBuildInfoFile": ".tsbuildinfo"
}
            

              
                Copy
              
            
          

Opcja tsBuildInfoFile określa plik, w którym kompilator będzie przechowywał informacje o kompilacji. Informacje te służą do określania, które pliki wymagają ponownej kompilacji podczas kolejnych budowań.

Odwołania do projektów

Odwołania do projektów pozwalają na strukturę kodu w mniejsze, łatwiejsze w zarządzaniu projekty. Może to poprawić czas budowania i organizację kodu dla dużych baz kodu. Dobrym analogiem do tej koncepcji jest architektura mikrousług - każda usługa jest niezależna, ale opiera się na innych w ekosystemie.

Aby użyć odwołań do projektów, musisz utworzyć oddzielny plik tsconfig.json dla każdego projektu. Następnie w głównym pliku tsconfig.json możesz określić projekty, do których należy się odwołać, używając opcji references.

Przykład:

            {
  "compilerOptions": {
    ...
  },
  "references": [
    { "path": "./project1" },
    { "path": "./project2" }
  ]
}
            

              
                Copy
              
            
          

Ta konfiguracja określa, że bieżący projekt zależy od projektów znajdujących się w katalogach ./project1 i ./project2.

Niestandardowe transformatory

Niestandardowe transformatory pozwalają modyfikować dane wyjściowe kompilatora TypeScript. Może to być używane do różnych celów, takich jak dodawanie niestandardowych transformacji kodu, usuwanie nieużywanego kodu lub optymalizacja danych wyjściowych dla określonych środowisk. Są one powszechnie używane do zadań internacjonalizacji i lokalizacji i18n.

Aby użyć niestandardowych transformatorów, musisz utworzyć oddzielny plik JavaScript, który eksportuje funkcję, która zostanie wywołana przez kompilator. Następnie możesz określić plik transformatora, używając opcji plugins w pliku tsconfig.json.

Przykład:

            {
  "compilerOptions": {
    ...
    "plugins": [
      { "transform": "./transformer.js" }
    ]
  }
}
            

              
                Copy
              
            
          

Ta konfiguracja określa, że plik ./transformer.js powinien być używany jako niestandardowy transformator.

Pliki, Include i Exclude

Poza compilerOptions, inne opcje na poziomie głównym w tsconfig.json kontrolują, które pliki są zawarte w procesie kompilacji:

• files: Tablica ścieżek do plików, które mają być uwzględnione w kompilacji.
• include: Tablica wzorców glob określających pliki do uwzględnienia.
• exclude: Tablica wzorców glob określających pliki do wykluczenia.

Opcje te zapewniają precyzyjną kontrolę nad tym, które pliki są przetwarzane przez kompilator TypeScript. Na przykład możesz wykluczyć pliki testowe lub wygenerowany kod z procesu kompilacji.

Przykład:

            {
  "compilerOptions": { ... },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

Ta konfiguracja zawiera wszystkie pliki w katalogu src i jego podkatalogach, wykluczając jednocześnie pliki w katalogach node_modules i dist, a także wszystkie pliki z rozszerzeniem .spec.ts (zwykle używane do testów jednostkowych).

Opcje kompilatora dla konkretnych scenariuszy

Różne projekty mogą wymagać różnych ustawień kompilatora, aby osiągnąć optymalne wyniki. Przyjrzyjmy się kilku konkretnym scenariuszom i zalecanym ustawieniom kompilatora dla każdego z nich.

Tworzenie aplikacji internetowych

Do tworzenia aplikacji internetowych zazwyczaj będziesz chciał użyć następujących ustawień kompilatora:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "sourceMap": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

Te ustawienia są odpowiednie dla nowoczesnych aplikacji internetowych używających React lub innych podobnych frameworków. Są one ukierunkowane na najnowsze funkcje ECMAScript, używają modułów ES i włączają ścisłe sprawdzanie typów.

Tworzenie zaplecza Node.js

Do tworzenia zaplecza Node.js zazwyczaj będziesz chciał użyć następujących ustawień kompilatora:

            {
  "compilerOptions": {
    "target": "ESNext",
    "module": "CommonJS",
    "esModuleInterop": true,
    "strict": true,
    "sourceMap": true,
    "outDir": "dist",
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
            

              
                Copy
              
            
          

Te ustawienia są odpowiednie dla aplikacji Node.js używających systemu modułów CommonJS. Są one ukierunkowane na najnowsze funkcje ECMAScript, włączają ścisłe sprawdzanie typów i pozwalają na importowanie plików JSON jako modułów.

Tworzenie bibliotek

Do tworzenia bibliotek zazwyczaj będziesz chciał użyć następujących ustawień kompilatora:

            {
  "compilerOptions": {
    "target": "ES5",
    "module": "UMD",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.spec.ts"]
}
            

              
                Copy
              
            
          

Te ustawienia są odpowiednie do tworzenia bibliotek, które mogą być używane zarówno w przeglądarkach, jak i w środowiskach Node.js. Generują pliki deklaracji i mapy źródeł, aby poprawić komfort programisty.

Najlepsze praktyki zarządzania TSConfig

Oto kilka najlepszych praktyk, o których należy pamiętać podczas zarządzania plikami tsconfig.json:

• Zacznij od podstawowej konfiguracji: Utwórz podstawowy plik tsconfig.json ze wspólnymi ustawieniami, a następnie rozszerz go w innych projektach, używając opcji extends.
• Używaj trybu ścisłego: Włącz tryb ścisły, aby wychwytywać potencjalne błędy i wymuszać najlepsze praktyki.
• Skonfiguruj rozpoznawanie modułów: Prawidłowo skonfiguruj rozpoznawanie modułów, aby uniknąć błędów importu.
• Używaj odwołań do projektów: Ustrukturyzuj swój kod w mniejsze, łatwiejsze w zarządzaniu projekty, używając odwołań do projektów.
• Aktualizuj plik tsconfig.json: Regularnie przeglądaj plik tsconfig.json i aktualizuj go w miarę rozwoju projektu.
• Kontrola wersji pliku tsconfig.json: Zatwierdź plik tsconfig.json do kontroli wersji wraz z innym kodem źródłowym.
• Udokumentuj konfigurację: Dodaj komentarze do pliku tsconfig.json, aby wyjaśnić cel każdej opcji.

Podsumowanie: Mistrzostwo Konfiguracji TypeScript

Plik tsconfig.json to potężne narzędzie do konfigurowania kompilatora TypeScript i kontrolowania procesu budowania. Rozumiejąc dostępne opcje i przestrzegając najlepszych praktyk, możesz precyzyjnie dostroić swoje projekty TypeScript w celu uzyskania optymalnej wydajności, możliwości konserwacji i kompatybilności. Ten przewodnik zawierał kompleksowy przegląd zaawansowanych opcji dostępnych w pliku tsconfig.json, umożliwiając pełną kontrolę nad przepływem pracy w zakresie rozwoju TypeScript. Pamiętaj, aby zawsze zapoznać się z oficjalną dokumentacją TypeScript, aby uzyskać najbardziej aktualne informacje i wskazówki. Wraz z ewolucją Twoich projektów, powinna również ewoluować Twoja wiedza i wykorzystanie tych potężnych narzędzi konfiguracyjnych. Miłego kodowania!