TypeScripti Konfigureerimine: Põhjalik tsconfig.json Juhend

TypeScript, JavaScripti superhulk, toob staatilise tüüpimise veebiarenduse dünaamilisse maailma. Hästi konfigureeritud tsconfig.json fail on TypeScripti täieliku potentsiaali rakendamiseks ülioluline. See juhend annab põhjaliku ülevaate tsconfig.json failist, hõlmates olulisi kompilaatori valikuid, projekti seadistamist ja täiustatud konfiguratsioone.

Mis on tsconfig.json?

tsconfig.json fail on konfiguratsioonifail, mis määrab TypeScripti projekti kompilaatori valikud. See ütleb TypeScripti kompilaatorile, kuidas transpileerida TypeScripti kood JavaScriptiks. See fail on hädavajalik projekti struktuuri määratlemiseks, kompileerimisreeglite seadmiseks ja arendusmeeskonna ühtsuse tagamiseks, olenemata sellest, kas meeskond asub ühes kontoris või on jaotatud mitme mandri vahel.

tsconfig.json faili loomine

tsconfig.json faili loomiseks navigeerige oma projekti juurkataloogi terminalis ja käivitage järgmine käsk:

tsc --init

See käsk genereerib põhilise tsconfig.json faili levinud kompilaatori valikutega. Seejärel saate faili kohandada vastavalt oma projekti spetsiifilistele nõuetele. Tüüpiline tsconfig.json sisaldab valikuid nagu compilerOptions, include ja exclude.

Olulised kompilaatori valikud

Sektsioon compilerOptions on tsconfig.json faili süda. See sisaldab laia valikut suvandeid, mis kontrollivad TypeScripti kompilaatori käitumist. Siin on mõned kõige olulisemad kompilaatori valikud:

target

Valik target määrab genereeritava JavaScripti koodi ECMAScripti sihtversiooni. Levinud väärtused on ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Õige sihtmärgi valimine on ülioluline, et tagada ühilduvus sihtkeskkonnaga, näiteks brauserite või Node.js-i versioonidega.

Näide:

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

module

Valik module määrab mooduli koodi genereerimise stiili. Levinud väärtused on CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ja ESNext. Moodulisüsteemi valik sõltub sihtkeskkonnast ja kasutatavast moodulite komplekteerijast (nt Webpack, Rollup, Parcel). Node.js-i jaoks kasutatakse sageli CommonJS-i, samas kui kaasaegsete veebirakenduste jaoks eelistatakse ES6 või ESNext koos moodulite komplekteerijaga. ESNext kasutamine võimaldab arendajatel kasutada kõige uuemaid funktsioone ja optimeerimisi, tuginedes samal ajal komplekteerijale lõpliku moodulivormingu käsitlemisel.

Näide:

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

lib

Valik lib määrab kompileerimisse kaasatavate teegifailide loendi. Need teegifailid pakuvad tüübimääratlusi sisseehitatud JavaScripti API-de ja brauseri API-de jaoks. Levinud väärtused on 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 ja palju muud. Sobivate teekide valimine tagab, et TypeScripti kompilaatoril on sihtkeskkonna jaoks vajalik tüübiinfo olemas. DOM-teegi kasutamine võimaldab projektil kompileerida koodi, mis kasutab brauserispetsiifilisi API-sid ilma tüübivigadeta.

Näide:

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

allowJs

Valik allowJs lubab TypeScripti kompilaatoril kompileerida JavaScripti faile koos TypeScripti failidega. See on kasulik olemasolevate JavaScripti projektide järkjärguliseks TypeScriptile üleviimiseks. Selle väärtuseks true seadmine võimaldab kompilaatoril töödelda .js faile, võimaldades TypeScripti järkjärgulist kasutuselevõttu projektis.

Näide:

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

jsx

Valik jsx määrab, kuidas JSX-süntaksit tuleks käsitleda. Levinud väärtused on preserve, react, react-native ja react-jsx. preserve säilitab JSX-süntaksi väljundis, samas kui react teisendab JSX-i React.createElementi kutseteks. react-jsx kasutab uut JSX-teisendust, mis võeti kasutusele React 17-s ja mis ei nõua Reacti importimist. Õige JSX-valiku tegemine on ülioluline projektidele, mis kasutavad Reacti või muid JSX-põhiseid teeke.

Näide:

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

declaration

Valik declaration genereerib iga TypeScripti faili jaoks vastavad .d.ts deklaratsioonifailid. Deklaratsioonifailid sisaldavad tüübiinfot ja neid kasutavad teised TypeScripti projektid kompileeritud koodi tarbimiseks. Deklaratsioonifailide genereerimine on oluline korduvkasutatavate teekide ja moodulite loomiseks. Need failid võimaldavad teistel TypeScripti projektidel mõista teegi poolt paljastatud tüüpe ja liideseid, ilma et oleks vaja algset lähtekoodi kompileerida.

Näide:

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

sourceMap

Valik sourceMap genereerib lähtekoodi kaardistamise faile, mis seovad genereeritud JavaScripti koodi tagasi algse TypeScripti koodiga. Lähtekoodi kaardid on hädavajalikud TypeScripti koodi silumiseks brauserites ja teistes keskkondades. Kui JavaScripti koodis tekib viga, võimaldab lähtekoodi kaart arendajal näha siluris vastavat TypeScripti koodi, mis teeb probleemi tuvastamise ja parandamise lihtsamaks.

Näide:

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

outDir

Valik outDir määrab genereeritud JavaScripti failide väljundkataloogi. See valik aitab korraldada projekti ehituse väljundit, eraldades lähtekoodi kompileeritud koodist. outDir kasutamine muudab ehitusprotsessi haldamise ja rakenduse juurutamise lihtsamaks.

Näide:

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

rootDir

Valik rootDir määrab TypeScripti projekti juurkataloogi. Kompilaator kasutab seda kataloogi moodulite nimede lahendamise alusena. See valik on eriti oluline keerulise kataloogistruktuuriga projektide puhul. rootDir korrektne seadistamine tagab, et kompilaator leiab kõik vajalikud moodulid ja sõltuvused.

Näide:

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

strict

Valik strict lubab kõik ranged tüübikontrolli valikud. See on uute TypeScripti projektide jaoks tungivalt soovitatav, kuna see aitab tabada potentsiaalseid vigu arendusprotsessi varases staadiumis. Range režiimi lubamine rakendab rangemaid tüübikontrolli reegleid, mis viib robustsema ja hooldatavama koodini. Hea tava on lubada range režiim kõigis uutes TypeScripti projektides.

Näide:

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

esModuleInterop

Valik esModuleInterop võimaldab koostalitlusvõimet CommonJS ja ES moodulite vahel. See on oluline projektide jaoks, mis kasutavad mõlemat tüüpi mooduleid. Kui esModuleInterop on lubatud, tegeleb TypeScript automaatselt CommonJS ja ES moodulite erinevustega, muutes moodulite importimise ja eksportimise kahe süsteemi vahel lihtsamaks. See valik on eriti kasulik, kui töötate kolmandate osapoolte teekidega, mis võivad kasutada erinevaid moodulisüsteeme.

Näide:

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

moduleResolution

Valik moduleResolution määrab, kuidas TypeScript lahendab moodulite importimisi. Levinud väärtused on Node ja Classic. Node moodulite lahendamise strateegia on vaikimisi ja põhineb Node.js moodulite lahendamise algoritmil. Classic moodulite lahendamise strateegia on vanem ja vähem levinud. Node moodulite lahendamise strateegia kasutamine tagab, et TypeScript suudab Node.js keskkonnas moodulite importimisi korrektselt lahendada.

Näide:

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

baseUrl ja paths

Valikuid baseUrl ja paths kasutatakse mitterelatiivsete moodulite importide lahendamise konfigureerimiseks. Valik baseUrl määrab baaskataloogi mitterelatiivsete moodulite nimede lahendamiseks. Valik paths võimaldab teil vastendada moodulite nimesid konkreetsete asukohtadega failisüsteemis. Need valikud on eriti kasulikud keerulise kataloogistruktuuriga projektide jaoks ja moodulite importide lihtsustamiseks. baseUrl ja paths kasutamine võib muuta koodi loetavamaks ja hooldatavamaks.

Näide:

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

Include ja Exclude valikud

Valikud include ja exclude määravad, millised failid tuleks kompileerimisse kaasata ja millised failid välistada. Need valikud kasutavad failinimede sobitamiseks glob-mustreid. include ja exclude kasutamine võimaldab teil kontrollida, milliseid faile TypeScripti kompilaator töötleb, parandades ehituse jõudlust ja vähendades vigu. Hea tava on kompileerimisse kaasatavad failid selgesõnaliselt määrata.

Näide:

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

Extends valik

Valik extends võimaldab teil pärida kompilaatori valikuid teisest tsconfig.json failist. See on kasulik ühiste konfiguratsiooniseadete jagamiseks mitme projekti vahel või baaskonfiguratsioonide loomiseks. extends valiku kasutamine soodustab koodi taaskasutust ja vähendab dubleerimist. Hea tava on luua baaskonfiguratsioonid ja laiendada neid üksikutes projektides.

Näide:

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

Täiustatud konfiguratsioonid

Lisaks olulistele kompilaatori valikutele toetab tsconfig.json spetsialiseeritud stsenaariumide jaoks täiustatud konfiguratsioone.

Inkrementaalne kompileerimine

Suurte projektide puhul võib inkrementaalne kompileerimine ehitusaegu märkimisväärselt parandada. TypeScript suudab vahemällu salvestada eelmiste kompileerimiste tulemused ja kompileerida uuesti ainult neid faile, mis on muutunud. Inkrementaalse kompileerimise lubamine võib suurte projektide ehitusaegu drastiliselt vähendada. See on eriti oluline projektide puhul, millel on suur hulk faile ja sõltuvusi.

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

Projekti viited

Projekti viited võimaldavad teil struktureerida suuri TypeScripti projekte väiksemateks, iseseisvateks mooduliteks. See võib parandada ehitusaegu ja koodi organiseerimist. Projekti viidete kasutamine võib muuta suured projektid paremini hallatavaks ja lihtsamini hooldatavaks. Hea tava on kasutada projekti viiteid suurte, keeruliste projektide puhul.

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

Kohandatud tüübimääratlused

Mõnikord peate esitama tüübimääratlusi JavaScripti teekidele, millel neid pole. Nende teekide tüüpide määratlemiseks saate luua kohandatud .d.ts faile. Kohandatud tüübimääratluste loomine võimaldab teil kasutada JavaScripti teeke oma TypeScripti koodis ilma tüübiohutust ohverdamata. See on eriti kasulik, kui töötate pärand-JavaScripti koodi või teekidega, mis ei paku oma tüübimääratlusi.

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

Parimad praktikad

• Kasutage ranget režiimi: Lubage strict valik täiustatud tüübikontrolliks.
• Määrake sihtversioon: Valige oma käituskeskkonnale sobiv target versioon.
• Organiseerige väljund: Kasutage outDir-i, et eraldada lähtekood kompileeritud koodist.
• Hallake sõltuvusi: Kasutage include ja exclude, et kontrollida, milliseid faile kompileeritakse.
• Kasutage Extends-i: Jagage ühiseid konfiguratsiooniseadeid extends valikuga.
• Lisage konfiguratsioon versioonihaldusesse: Kinnitage `tsconfig.json` git-i, et säilitada järjepidevus arenduskeskkondade ja CI/CD torujuhtmete vahel.

Levinud probleemide tõrkeotsing

tsconfig.json-i konfigureerimine võib mõnikord olla keeruline. Siin on mõned levinud probleemid ja nende lahendused:

Moodulite lahendamise probleemid

Kui teil tekib moodulite lahendamise vigu, veenduge, et moduleResolution valik on õigesti konfigureeritud ning baseUrl ja paths valikud on korrektselt seadistatud. Kontrollige paths valikus määratud teid, et veenduda nende korrektsuses. Veenduge, et kõik vajalikud moodulid on installitud node_modules kataloogi.

Tüübivead

Tüübivead võivad tekkida, kui tüübimääratlused on valed või puuduvad. Veenduge, et teil on kõigi kasutatavate teekide jaoks installitud õiged tüübimääratlused. Kui kasutate JavaScripti teeki, millel pole tüübimääratlusi, kaaluge kohandatud tüübimääratluste loomist.

Kompileerimisvead

Kompileerimisvead võivad tekkida, kui teie TypeScripti koodis on süntaksi- või tüübivigu. Vaadake veateated hoolikalt üle ja parandage kõik süntaksi- või tüübivead. Veenduge, et teie kood järgib TypeScripti kodeerimistavasid.

Kokkuvõte

Hästi konfigureeritud tsconfig.json fail on eduka TypeScripti projekti jaoks hädavajalik. Mõistes olulisi kompilaatori valikuid ja täiustatud konfiguratsioone, saate optimeerida oma arendustöövoogu, parandada koodi kvaliteeti ja tagada ühilduvuse sihtkeskkonnaga. Aja investeerimine tsconfig.json-i korrektsele konfigureerimisele tasub end pikemas perspektiivis ära, vähendades vigu, parandades hooldatavust ja sujuvamaks muutes ehitusprotsessi. See tulemuseks on tõhusam ja usaldusväärsem tarkvaraarendus. Siin esitatud teave on loodud olema universaalselt rakendatav ja peaks pakkuma tugeva aluse uue projekti alustamiseks TypeScriptiga.

Ärge unustage tutvuda ametliku TypeScripti dokumentatsiooniga kõige ajakohasema teabe ja kõigi saadaolevate kompilaatori valikute üksikasjalike selgituste saamiseks. TypeScripti dokumentatsioon on väärtuslik ressurss TypeScripti konfigureerimise keerukuste mõistmiseks.