Konfigurace TypeScriptu: Komplexní průvodce souborem tsconfig.json

TypeScript, nadmnožina JavaScriptu, přináší statické typování do dynamického světa webového vývoje. Správně nakonfigurovaný soubor tsconfig.json je klíčový pro využití plného potenciálu TypeScriptu. Tento průvodce poskytuje komplexní přehled souboru tsconfig.json, zahrnující základní možnosti kompilátoru, nastavení projektu a pokročilé konfigurace.

Co je to tsconfig.json?

Soubor tsconfig.json je konfigurační soubor, který specifikuje možnosti kompilátoru pro projekt v TypeScriptu. Říká kompilátoru TypeScriptu, jak má transpikovat kód TypeScriptu do JavaScriptu. Tento soubor je nezbytný pro definování struktury projektu, nastavení pravidel kompilace a zajištění konzistence napříč vývojovým týmem, ať už se tento tým nachází v jedné kanceláři nebo je rozdělen na několika kontinentech.

Vytvoření souboru tsconfig.json

Pro vytvoření souboru tsconfig.json přejděte v terminálu do kořenového adresáře vašeho projektu a spusťte následující příkaz:

            tsc --init
            

              
                Copy
              
            
          

Tento příkaz vygeneruje základní soubor tsconfig.json s běžně používanými možnostmi kompilátoru. Soubor si pak můžete přizpůsobit specifickým požadavkům vašeho projektu. Typický tsconfig.json bude obsahovat možnosti jako compilerOptions, include a exclude.

Základní možnosti kompilátoru

Sekce compilerOptions je srdcem souboru tsconfig.json. Obsahuje širokou škálu možností, které řídí chování kompilátoru TypeScriptu. Zde jsou některé z nejdůležitějších možností kompilátoru:

target

Možnost target specifikuje cílovou verzi ECMAScriptu pro generovaný JavaScriptový kód. Mezi běžné hodnoty patří ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Výběr správného cíle je zásadní pro zajištění kompatibility s cílovým běhovým prostředím, jako jsou prohlížeče nebo verze Node.js.

Příklad:

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

              
                Copy
              
            
          

module

Možnost module specifikuje styl generování kódu modulů. Mezi běžné hodnoty patří CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 a ESNext. Volba modulového systému závisí na cílovém prostředí a použitém nástroji pro sdružování modulů (např. Webpack, Rollup, Parcel). Pro Node.js se často používá CommonJS, zatímco pro moderní webové aplikace je preferován ES6 nebo ESNext s nástrojem pro sdružování modulů. Použití ESNext umožňuje vývojářům využívat nejnovější funkce a optimalizace, přičemž se spoléhají na to, že konečný formát modulů zpracuje bundler.

Příklad:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

Možnost lib specifikuje seznam souborů knihoven, které mají být zahrnuty do kompilace. Tyto soubory knihoven poskytují definice typů pro vestavěná JavaScript API a API prohlížečů. Mezi běžné hodnoty patří ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String a mnoho dalších. Výběr vhodných knihoven zajišťuje, že kompilátor TypeScriptu má potřebné informace o typech pro cílové prostředí. Použití knihovny DOM umožňuje projektu kompilovat kód, který využívá API specifická pro prohlížeče, bez typových chyb.

Příklad:

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

              
                Copy
              
            
          

allowJs

Možnost allowJs umožňuje kompilátoru TypeScriptu kompilovat JavaScriptové soubory spolu se soubory TypeScriptu. To je užitečné pro postupnou migraci existujících JavaScriptových projektů na TypeScript. Nastavení této hodnoty na true umožňuje kompilátoru zpracovávat soubory .js, což umožňuje postupnou adopci TypeScriptu v rámci projektu.

Příklad:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

Možnost jsx specifikuje, jak se má zpracovávat syntaxe JSX. Běžné hodnoty zahrnují preserve, react, react-native a react-jsx. preserve zachovává syntaxi JSX ve výstupu, zatímco react transformuje JSX na volání React.createElement. react-jsx používá novou JSX transformaci zavedenou v React 17, která nevyžaduje import Reactu. Výběr správné možnosti JSX je klíčový pro projekty používající React nebo jiné knihovny založené na JSX.

Příklad:

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

              
                Copy
              
            
          

declaration

Možnost declaration generuje odpovídající deklarační soubory .d.ts pro každý soubor TypeScriptu. Deklarační soubory obsahují informace o typech a jsou používány jinými projekty v TypeScriptu k využívání zkompilovaného kódu. Generování deklaračních souborů je nezbytné pro vytváření znovupoužitelných knihoven a modulů. Tyto soubory umožňují jiným projektům v TypeScriptu porozumět typům a rozhraním, které knihovna odhaluje, aniž by bylo nutné kompilovat původní zdrojový kód.

Příklad:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

Možnost sourceMap generuje soubory zdrojových map, které mapují generovaný JavaScriptový kód zpět na původní kód TypeScriptu. Zdrojové mapy jsou nezbytné pro ladění kódu TypeScriptu v prohlížečích a jiných prostředích. Když dojde k chybě v JavaScriptovém kódu, zdrojová mapa umožňuje vývojáři vidět odpovídající kód TypeScriptu v debuggeru, což usnadňuje identifikaci a opravu problému.

Příklad:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

Možnost outDir specifikuje výstupní adresář pro generované JavaScriptové soubory. Tato možnost pomáhá organizovat výstup sestavení projektu oddělením zdrojového kódu od zkompilovaného kódu. Použití outDir usnadňuje správu procesu sestavení a nasazení aplikace.

Příklad:

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

              
                Copy
              
            
          

rootDir

Možnost rootDir specifikuje kořenový adresář projektu TypeScript. Kompilátor používá tento adresář jako základ pro rozlišování názvů modulů. Tato možnost je obzvláště důležitá pro projekty se složitou adresářovou strukturou. Správné nastavení rootDir zajišťuje, že kompilátor dokáže najít všechny potřebné moduly a závislosti.

Příklad:

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

              
                Copy
              
            
          

strict

Možnost strict povoluje všechny možnosti striktní kontroly typů. Je vysoce doporučena pro nové projekty v TypeScriptu, protože pomáhá odhalit potenciální chyby v rané fázi vývojového procesu. Povolení striktního režimu vynucuje přísnější pravidla kontroly typů, což vede k robustnějšímu a udržitelnějšímu kódu. Je osvědčeným postupem povolit striktní režim ve všech nových projektech v TypeScriptu.

Příklad:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

Možnost esModuleInterop umožňuje interoperabilitu mezi moduly CommonJS a ES. To je důležité pro projekty, které používají oba typy modulů. Když je esModuleInterop povoleno, TypeScript automaticky zpracuje rozdíly mezi moduly CommonJS a ES, což usnadňuje import a export modulů mezi těmito dvěma systémy. Tato možnost je obzvláště užitečná při práci s knihovnami třetích stran, které mohou používat různé modulové systémy.

Příklad:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

Možnost moduleResolution specifikuje, jak TypeScript rozlišuje importy modulů. Běžné hodnoty zahrnují Node a Classic. Strategie rozlišování modulů Node je výchozí a je založena na algoritmu rozlišování modulů v Node.js. Strategie rozlišování modulů Classic je starší a méně používaná. Použití strategie rozlišování modulů Node zajišťuje, že TypeScript dokáže správně rozlišit importy modulů v prostředí Node.js.

Příklad:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl and paths

Možnosti baseUrl a paths se používají ke konfiguraci rozlišování modulů pro ne-relativní importy modulů. Možnost baseUrl specifikuje základní adresář pro rozlišování ne-relativních názvů modulů. Možnost paths vám umožňuje mapovat názvy modulů na konkrétní umístění v souborovém systému. Tyto možnosti jsou obzvláště užitečné pro projekty se složitou adresářovou strukturou a pro zjednodušení importů modulů. Použití baseUrl a paths může učinit kód čitelnějším a udržitelnějším.

Příklad:

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

              
                Copy
              
            
          

Možnosti Include a Exclude

Možnosti include a exclude specifikují, které soubory mají být zahrnuty do kompilace a které soubory mají být vyloučeny. Tyto možnosti používají glob vzory pro shodu názvů souborů. Použití include a exclude vám umožňuje kontrolovat, které soubory jsou zpracovávány kompilátorem TypeScriptu, což zlepšuje výkon sestavení a snižuje počet chyb. Je osvědčeným postupem explicitně specifikovat soubory, které mají být zahrnuty do kompilace.

Příklad:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Možnost Extends

Možnost extends vám umožňuje dědit možnosti kompilátoru z jiného souboru tsconfig.json. To je užitečné pro sdílení společných nastavení konfigurace mezi více projekty nebo pro vytváření základních konfigurací. Použití možnosti extends podporuje znovupoužití kódu a snižuje duplicitu. Je osvědčeným postupem vytvářet základní konfigurace a rozšiřovat je v jednotlivých projektech.

Příklad:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Pokročilé konfigurace

Kromě základních možností kompilátoru podporuje tsconfig.json pokročilé konfigurace pro specializované scénáře.

Inkrementální kompilace

U velkých projektů může inkrementální kompilace výrazně zkrátit dobu sestavení. TypeScript může ukládat výsledky předchozích kompilací do mezipaměti a znovu kompilovat pouze soubory, které se změnily. Povolení inkrementální kompilace může dramaticky snížit dobu sestavení u velkých projektů. To je zvláště důležité pro projekty s velkým počtem souborů a závislostí.

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

              
                Copy
              
            
          

Odkazy na projekty

Odkazy na projekty vám umožňují strukturovat velké projekty v TypeScriptu do menších, nezávislých modulů. To může zlepšit dobu sestavení a organizaci kódu. Použití odkazů na projekty může učinit velké projekty lépe spravovatelnými a snáze udržovatelnými. Je osvědčeným postupem používat odkazy na projekty pro velké a složité projekty.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Vlastní definice typů

Někdy budete muset poskytnout definice typů pro JavaScriptové knihovny, které je nemají. Můžete vytvořit vlastní soubory .d.ts k definování typů pro tyto knihovny. Vytváření vlastních definic typů vám umožňuje používat JavaScriptové knihovny ve vašem kódu TypeScript bez obětování typové bezpečnosti. To je zvláště užitečné při práci se starším JavaScriptovým kódem nebo knihovnami, které neposkytují vlastní definice typů.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

Osvědčené postupy

• Používejte striktní režim: Povolte možnost strict pro vylepšenou kontrolu typů.
• Specifikujte cíl: Zvolte vhodnou verzi target pro vaše běhové prostředí.
• Organizujte výstup: Použijte outDir k oddělení zdrojového kódu od zkompilovaného kódu.
• Spravujte závislosti: Použijte include a exclude pro kontrolu, které soubory se kompilují.
• Využívejte Extends: Sdílejte společná nastavení konfigurace pomocí možnosti extends.
• Ukládejte konfiguraci do správy verzí: Commitujte `tsconfig.json` do gitu pro zachování konzistence napříč vývojářskými prostředími a CI/CD pipeline.

Řešení běžných problémů

Konfigurace souboru tsconfig.json může být někdy náročná. Zde jsou některé běžné problémy a jejich řešení:

Problémy s rozlišováním modulů

Pokud narazíte na chyby při rozlišování modulů, ujistěte se, že je možnost moduleResolution správně nakonfigurována a že jsou možnosti baseUrl a paths správně nastaveny. Dvakrát zkontrolujte cesty zadané v možnosti paths, abyste se ujistili, že jsou správné. Ověřte, že jsou všechny potřebné moduly nainstalovány v adresáři node_modules.

Typové chyby

Typové chyby se mohou objevit, pokud jsou definice typů nesprávné nebo chybí. Ujistěte se, že máte nainstalované správné definice typů pro všechny knihovny, které používáte. Pokud používáte JavaScriptovou knihovnu, která nemá definice typů, zvažte vytvoření vlastních definic typů.

Chyby kompilace

Chyby kompilace se mohou objevit, pokud jsou ve vašem kódu TypeScriptu syntaktické nebo typové chyby. Pečlivě si projděte chybové zprávy a opravte všechny syntaktické nebo typové chyby. Ujistěte se, že váš kód dodržuje kódovací konvence TypeScriptu.

Závěr

Správně nakonfigurovaný soubor tsconfig.json je nezbytný pro úspěšný projekt v TypeScriptu. Porozuměním základním možnostem kompilátoru a pokročilým konfiguracím můžete optimalizovat svůj vývojový pracovní postup, zlepšit kvalitu kódu a zajistit kompatibilitu s cílovým prostředím. Investice času do správné konfigurace tsconfig.json se v dlouhodobém horizontu vyplatí snížením chyb, zlepšením udržovatelnosti a zefektivněním procesu sestavení. To vede k efektivnějšímu a spolehlivějšímu vývoji softwaru. Zde poskytnuté informace jsou navrženy tak, aby byly univerzálně použitelné a měly by poskytnout pevný základ pro zahájení nového projektu s TypeScriptem.

Nezapomeňte nahlédnout do oficiální dokumentace TypeScriptu pro nejaktuálnější informace a podrobná vysvětlení všech dostupných možností kompilátoru. Dokumentace TypeScriptu je cenným zdrojem pro pochopení složitostí konfigurace TypeScriptu.