TypeScript Konfigūravimas: Išsamus tsconfig.json Vadovas

TypeScript, JavaScript viršaibis, įneša statinį tipizavimą į dinamišką interneto svetainių kūrimo pasaulį. Gerai sukonfigūruotas tsconfig.json failas yra būtinas norint išnaudoti visą TypeScript galią. Šis vadovas pateikia išsamią tsconfig.json apžvalgą, apimančią esmines kompiliatoriaus parinktis, projekto sąranką ir pažangias konfigūracijas.

Kas yra tsconfig.json?

tsconfig.json failas yra konfigūracijos failas, nurodantis TypeScript projekto kompiliatoriaus parinktis. Jis nurodo TypeScript kompiliatoriui, kaip transpiliuoti TypeScript kodą į JavaScript. Šis failas yra būtinas apibrėžiant projekto struktūrą, nustatant kompiliavimo taisykles ir užtikrinant nuoseklumą visoje kūrėjų komandoje, nesvarbu, ar komanda dirba viename biure, ar yra išsidėsčiusi keliuose žemynuose.

tsconfig.json Failo Kūrimas

Norėdami sukurti tsconfig.json failą, savo projekto šakniniame kataloge terminale paleiskite šią komandą:

tsc --init

Ši komanda sugeneruoja bazinį tsconfig.json failą su dažniausiai naudojamomis kompiliatoriaus parinktimis. Tada galite pritaikyti failą pagal savo projekto specifinius reikalavimus. Tipiškas tsconfig.json failas apims tokias parinktis kaip compilerOptions, include ir exclude.

Esminės Kompiliatoriaus Parinktys

compilerOptions skyrius yra tsconfig.json failo širdis. Jame yra platus parinkčių spektras, kontroliuojantis TypeScript kompiliatoriaus elgseną. Štai keletas svarbiausių kompiliatoriaus parinkčių:

target

target parinktis nurodo generuojamo JavaScript kodo ECMAScript tikslinę versiją. Dažniausios reikšmės yra ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Tinkamos tikslinės versijos pasirinkimas yra labai svarbus siekiant užtikrinti suderinamumą su numatyta vykdymo aplinka, pavyzdžiui, naršyklėmis ar Node.js versijomis.

Pavyzdys:

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

module

module parinktis nurodo modulio kodo generavimo stilių. Dažniausios reikšmės yra CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ir ESNext. Modulių sistemos pasirinkimas priklauso nuo tikslinės aplinkos ir naudojamo modulių pakuoklio (pvz., Webpack, Rollup, Parcel). Node.js aplinkai dažnai naudojamas CommonJS, o šiuolaikinėms interneto programoms pirmenybė teikiama ES6 arba ESNext su modulių pakuokliu. Naudojant ESNext, kūrėjai gali pasinaudoti naujausiomis funkcijomis ir optimizacijomis, pasikliaudami pakuokliu, kad jis sutvarkytų galutinį modulio formatą.

Pavyzdys:

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

lib

lib parinktis nurodo bibliotekos failų, kurie bus įtraukti į kompiliavimą, sąrašą. Šie bibliotekos failai pateikia tipų apibrėžimus integruotoms JavaScript API ir naršyklės API. Dažniausios reikšmės yra 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 ir daugelis kitų. Tinkamų bibliotekų pasirinkimas užtikrina, kad TypeScript kompiliatorius turės reikiamą tipo informaciją tikslinei aplinkai. Naudojant DOM biblioteką, projektas gali kompiliuoti kodą, kuris naudoja naršyklei būdingas API be tipo klaidų.

Pavyzdys:

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

allowJs

allowJs parinktis leidžia TypeScript kompiliatoriui kompiliuoti JavaScript failus kartu su TypeScript failais. Tai naudinga laipsniškai migruojant esamus JavaScript projektus į TypeScript. Nustačius šią parinktį į true, kompiliatorius gali apdoroti .js failus, leidžiant palaipsniui pritaikyti TypeScript projekte.

Pavyzdys:

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

jsx

jsx parinktis nurodo, kaip turi būti tvarkoma JSX sintaksė. Dažniausios reikšmės yra preserve, react, react-native ir react-jsx. preserve išlaiko JSX sintaksę išvestyje, o react transformuoja JSX į React.createElement iškvietimus. react-jsx naudoja naują JSX transformaciją, pristatytą React 17, kuriai nereikia importuoti React. Tinkamos JSX parinkties pasirinkimas yra labai svarbus projektuose, kuriuose naudojamas React ar kitos JSX pagrindu veikiančios bibliotekos.

Pavyzdys:

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

declaration

declaration parinktis sugeneruoja atitinkamus .d.ts deklaracijų failus kiekvienam TypeScript failui. Deklaracijų failuose yra tipo informacija ir juos naudoja kiti TypeScript projektai, norėdami naudoti kompiliuotą kodą. Deklaracijų failų generavimas yra būtinas kuriant daugkartinio naudojimo bibliotekas ir modulius. Šie failai leidžia kitiems TypeScript projektams suprasti bibliotekos atskleistus tipus ir sąsajas, nereikalaujant kompiliuoti originalaus šaltinio kodo.

Pavyzdys:

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

sourceMap

sourceMap parinktis sugeneruoja šaltinio žemėlapio failus, kurie susieja sugeneruotą JavaScript kodą su originaliu TypeScript kodu. Šaltinio žemėlapiai yra būtini derinant TypeScript kodą naršyklėse ir kitose aplinkose. Kai JavaScript kode įvyksta klaida, šaltinio žemėlapis leidžia programuotojui matyti atitinkamą TypeScript kodą derintuve, todėl lengviau nustatyti ir ištaisyti problemą.

Pavyzdys:

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

outDir

outDir parinktis nurodo išvesties katalogą sugeneruotiems JavaScript failams. Ši parinktis padeda organizuoti projekto kūrimo išvestį, atskiriant šaltinio kodą nuo kompiliuoto kodo. Naudojant outDir, lengviau valdyti kūrimo procesą ir įdiegti programą.

Pavyzdys:

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

rootDir

rootDir parinktis nurodo TypeScript projekto šakninį katalogą. Kompiliatorius naudoja šį katalogą kaip pagrindą sprendžiant modulių pavadinimus. Ši parinktis yra ypač svarbi projektuose su sudėtinga katalogų struktūra. Teisingai nustačius rootDir, užtikrinama, kad kompiliatorius ras visus reikiamus modulius ir priklausomybes.

Pavyzdys:

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

strict

strict parinktis įjungia visas griežto tipo tikrinimo parinktis. Tai labai rekomenduojama naujiems TypeScript projektams, nes padeda anksti aptikti galimas klaidas kūrimo procese. Griežtojo režimo įjungimas įveda griežtesnes tipų tikrinimo taisykles, todėl kodas tampa tvirtesnis ir lengviau prižiūrimas. Geriausia praktika yra įjungti griežtąjį režimą visuose naujuose TypeScript projektuose.

Pavyzdys:

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

esModuleInterop

esModuleInterop parinktis įjungia sąveiką tarp CommonJS ir ES modulių. Tai svarbu projektuose, kuriuose naudojami abiejų tipų moduliai. Kai įjungta esModuleInterop, TypeScript automatiškai tvarko skirtumus tarp CommonJS ir ES modulių, todėl lengviau importuoti ir eksportuoti modulius tarp dviejų sistemų. Ši parinktis ypač naudinga dirbant su trečiųjų šalių bibliotekomis, kurios gali naudoti skirtingas modulių sistemas.

Pavyzdys:

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

moduleResolution

moduleResolution parinktis nurodo, kaip TypeScript sprendžia modulių importavimą. Dažniausios reikšmės yra Node ir Classic. Node modulių sprendimo strategija yra numatytoji ir pagrįsta Node.js modulių sprendimo algoritmu. Classic modulių sprendimo strategija yra senesnė ir rečiau naudojama. Naudojant Node modulių sprendimo strategiją, užtikrinama, kad TypeScript teisingai išspręs modulių importavimą Node.js aplinkoje.

Pavyzdys:

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

baseUrl ir paths

baseUrl ir paths parinktys naudojamos konfigūruoti modulių sprendimą ne santykiniams modulių importams. baseUrl parinktis nurodo pagrindinį katalogą sprendžiant ne santykinius modulių pavadinimus. paths parinktis leidžia susieti modulių pavadinimus su konkrečiomis vietomis failų sistemoje. Šios parinktys yra ypač naudingos projektuose su sudėtinga katalogų struktūra ir supaprastinant modulių importavimą. Naudojant baseUrl ir paths, kodas gali tapti skaitomesnis ir lengviau prižiūrimas.

Pavyzdys:

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

Include ir Exclude Parinktys

include ir exclude parinktys nurodo, kurie failai turėtų būti įtraukti į kompiliavimą ir kurie failai turėtų būti neįtraukti. Šios parinktys naudoja „glob“ šablonus, kad atitiktų failų pavadinimus. Naudojant include ir exclude, galima kontroliuoti, kurie failai yra apdorojami TypeScript kompiliatoriaus, taip pagerinant kūrimo našumą ir sumažinant klaidų skaičių. Geriausia praktika yra aiškiai nurodyti failus, kurie turi būti įtraukti į kompiliavimą.

Pavyzdys:

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

Extends Parinktis

extends parinktis leidžia paveldėti kompiliatoriaus parinktis iš kito tsconfig.json failo. Tai naudinga dalijantis bendrais konfigūracijos nustatymais tarp kelių projektų arba kuriant bazines konfigūracijas. Naudojant extends parinktį skatinamas kodo pakartotinis naudojimas ir mažinamas dubliavimas. Geriausia praktika yra sukurti bazines konfigūracijas ir jas išplėsti atskiruose projektuose.

Pavyzdys:

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

Pažangios Konfigūracijos

Be esminių kompiliatoriaus parinkčių, tsconfig.json palaiko pažangias konfigūracijas specializuotiems scenarijams.

Inkrementinis Kompiliavimas

Dideliuose projektuose inkrementinis kompiliavimas gali žymiai pagerinti kūrimo laiką. TypeScript gali išsaugoti ankstesnių kompiliavimų rezultatus ir perkompiliuoti tik pakeistus failus. Inkrementinio kompiliavimo įjungimas gali dramatiškai sumažinti kūrimo laiką dideliuose projektuose. Tai ypač svarbu projektuose su dideliu failų ir priklausomybių skaičiumi.

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

Projektų Nuorodos

Projektų nuorodos leidžia struktūrizuoti didelius TypeScript projektus į mažesnius, nepriklausomus modulius. Tai gali pagerinti kūrimo laiką ir kodo organizavimą. Naudojant projektų nuorodas, dideli projektai tampa lengviau valdomi ir prižiūrimi. Geriausia praktika yra naudoti projektų nuorodas dideliems, sudėtingiems projektams.

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

Pasirinktiniai Tipų Apibrėžimai

Kartais gali prireikti pateikti tipų apibrėžimus JavaScript bibliotekoms, kurios jų neturi. Galite sukurti pasirinktinius .d.ts failus, kad apibrėžtumėte šių bibliotekų tipus. Pasirinktinių tipų apibrėžimų kūrimas leidžia naudoti JavaScript bibliotekas savo TypeScript kode neprarandant tipų saugumo. Tai ypač naudinga dirbant su senu JavaScript kodu ar bibliotekomis, kurios nepateikia savo tipų apibrėžimų.

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

Geriausios Praktikos

• Naudokite griežtąjį režimą (Strict Mode): Įjunkite strict parinktį patobulintam tipų tikrinimui.
• Nurodykite tikslinę versiją (Target): Pasirinkite tinkamą target versiją savo vykdymo aplinkai.
• Organizuokite išvestį: Naudokite outDir, kad atskirtumėte pradinį kodą nuo kompiliuoto kodo.
• Valdykite priklausomybes: Naudokite include ir exclude, kad kontroliuotumėte, kurie failai yra kompiluojami.
• Išnaudokite paveldėjimą (Extends): Dalinkitės bendrais konfigūracijos nustatymais su extends parinktimi.
• Įkelkite konfigūraciją į versijų kontrolės sistemą: Įkelkite tsconfig.json į „git“, kad išlaikytumėte nuoseklumą kūrėjų aplinkose ir CI/CD procesuose.

Dažniausiai Pasitaikančių Problemų Sprendimas

Konfigūruoti tsconfig.json kartais gali būti sudėtinga. Štai keletas dažniausiai pasitaikančių problemų ir jų sprendimai:

Modulių Sprendimo Problemos

Jei susiduriate su modulių sprendimo klaidomis, įsitikinkite, kad moduleResolution parinktis yra teisingai sukonfigūruota ir kad baseUrl bei paths parinktys yra tinkamai nustatytos. Dukart patikrinkite paths parinktyje nurodytus kelius, kad įsitikintumėte, jog jie yra teisingi. Patikrinkite, ar visi reikalingi moduliai yra įdiegti node_modules kataloge.

Tipų Klaidos

Tipų klaidos gali atsirasti, jei tipų apibrėžimai yra neteisingi arba jų trūksta. Įsitikinkite, kad turite įdiegtus teisingus tipų apibrėžimus visoms naudojamoms bibliotekoms. Jei naudojate JavaScript biblioteką, kuri neturi tipų apibrėžimų, apsvarstykite galimybę sukurti pasirinktinius tipų apibrėžimus.

Kompiliavimo Klaidos

Kompiliavimo klaidos gali atsirasti, jei jūsų TypeScript kode yra sintaksės ar tipų klaidų. Atidžiai peržiūrėkite klaidų pranešimus ir ištaisykite visas sintaksės ar tipų klaidas. Įsitikinkite, kad jūsų kodas atitinka TypeScript kodavimo konvencijas.

Išvada

Gerai sukonfigūruotas tsconfig.json failas yra būtinas sėkmingam TypeScript projektui. Suprasdami esmines kompiliatoriaus parinktis ir pažangias konfigūracijas, galite optimizuoti savo kūrimo darbo eigą, pagerinti kodo kokybę ir užtikrinti suderinamumą su tiksline aplinka. Laikas, investuotas į tinkamą tsconfig.json konfigūravimą, atsipirks ilgalaikėje perspektyvoje, sumažinant klaidų skaičių, pagerinant kodo priežiūrą ir supaprastinant kūrimo procesą. Tai lemia efektyvesnį ir patikimesnį programinės įrangos kūrimą. Čia pateikta informacija yra sukurta taip, kad būtų universaliai pritaikoma ir turėtų suteikti tvirtą pagrindą pradedant naują projektą su TypeScript.

Nepamirškite pasikonsultuoti su oficialia TypeScript dokumentacija, kad gautumėte naujausią informaciją ir išsamius visų galimų kompiliatoriaus parinkčių paaiškinimus. TypeScript dokumentacija yra vertingas šaltinis, padedantis suprasti TypeScript konfigūravimo subtilybes.