TypeScript-konfiguraatio: TSConfig-kääntäjäasetusten hallitseminen

tsconfig.json-tiedosto on jokaisen TypeScript-projektin sydän. Se määrää, miten TypeScript-kääntäjä (tsc) muuntaa .ts-tiedostosi JavaScriptiksi. Hyvin konfiguroitu tsconfig.json on ratkaisevan tärkeä koodin laadun ylläpitämiseksi, yhteensopivuuden varmistamiseksi eri ympäristöissä ja rakennusprosessin optimoimiseksi. Tämä kattava opas sukeltaa syvälle edistyneisiin tsconfig.json-asetuksiin, antaen sinulle mahdollisuuden hienosäätää TypeScript-projektejasi huippusuorituskyvyn ja ylläpidettävyyden saavuttamiseksi.

Perusasioiden ymmärtäminen: Miksi TSConfig on tärkeä

Ennen kuin syvennymme edistyneisiin asetuksiin, kerrataanpa miksi tsconfig.json on niin tärkeä:

• Käännöksen hallinta: Se määrittää, mitkä tiedostot tulisi sisällyttää projektiisi ja miten ne tulisi kääntää.
• Tyypintarkistus: Se määrittelee tyypintarkistuksen säännöt ja tiukkuuden, auttaen sinua löytämään virheet kehityssyklin alkuvaiheessa.
• Tulostuksen hallinta: Se määrittää kohde-JavaScript-version, moduulijärjestelmän ja tulostushakemiston.
• IDE-integraatio: Se tarjoaa arvokasta tietoa IDE:ille (kuten VS Code, WebStorm jne.) ominaisuuksia varten, kuten koodin täydennys, virheiden korostus ja refaktorointi.

Ilman tsconfig.json-tiedostoa TypeScript-kääntäjä käyttää oletusasetuksia, jotka eivät välttämättä sovi kaikkiin projekteihin. Tämä voi johtaa odottamattomaan käyttäytymiseen, yhteensopivuusongelmiin ja vähemmän ihanteelliseen kehityskokemukseen.

TSConfig-tiedoston luominen: Nopea aloitus

Voit luoda tsconfig.json-tiedoston yksinkertaisesti ajamalla seuraavan komennon projektisi juurihakemistossa:

            tsc --init
            

              
                Copy
              
            
          

Tämä luo perusmuotoisen tsconfig.json-tiedoston, jossa on joitakin yleisiä asetuksia. Voit sitten muokata tätä tiedostoa vastaamaan projektisi erityisvaatimuksia.

Keskeiset kääntäjäasetukset: Yksityiskohtainen katsaus

tsconfig.json-tiedosto sisältää compilerOptions-objektin, jossa määrität TypeScript-kääntäjän asetukset. Tarkastellaan joitakin tärkeimmistä ja yleisimmin käytetyistä vaihtoehdoista:

target

Tämä asetus määrittää käännetyn JavaScript-koodin ECMAScript-kohdeversion. Se määrää, mitä JavaScript-ominaisuuksia kääntäjä käyttää, varmistaen yhteensopivuuden kohdeympäristön kanssa (esim. selaimet, Node.js). Yleisiä arvoja ovat ES5, ES6 (ES2015), ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. ESNext-asetuksen käyttö kohdistaa uusimmat tuetut ECMAScript-ominaisuudet.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio ohjeistaa kääntäjää luomaan JavaScript-koodia, joka on yhteensopiva ECMAScript 2020:n kanssa.

module

Tämä asetus määrittää moduulijärjestelmän, jota käytetään käännetyssä JavaScript-koodissa. Yleisiä arvoja ovat CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ja ESNext. Moduulijärjestelmän valinta riippuu kohdeympäristöstä ja käytetystä moduulilataajasta (esim. Node.js, Webpack, Browserify).

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio sopii Node.js-projekteihin, jotka tyypillisesti käyttävät CommonJS-moduulijärjestelmää.

lib

Tämä asetus määrittää kokoelman kirjastotiedostoja, jotka sisällytetään käännösprosessiin. Nämä kirjastotiedostot tarjoavat tyyppimääritykset sisäänrakennetuille JavaScript-rajapinnoille ja selainrajapinnoille. Yleisiä arvoja ovat ES5, ES6, ES7, DOM, WebWorker, ScriptHost ja muita.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio sisältää tyyppimääritykset ECMAScript 2020:lle ja DOM-rajapinnalle, mikä on välttämätöntä selainpohjaisille projekteille.

allowJs

Tämä asetus sallii TypeScript-kääntäjän kääntää JavaScript-tiedostoja TypeScript-tiedostojen rinnalla. Tämä voi olla hyödyllistä siirrettäessä JavaScript-projektia TypeScriptiin tai työskenneltäessä olemassa olevien JavaScript-koodikantojen kanssa.

Esimerkki:

            "compilerOptions": {
  "allowJs": true
}
            

              
                Copy
              
            
          

Kun tämä asetus on käytössä, kääntäjä käsittelee sekä .ts- että .js-tiedostot.

checkJs

Tämä asetus mahdollistaa tyypintarkistuksen JavaScript-tiedostoille. Yhdessä allowJs-asetuksen kanssa se antaa TypeScriptille mahdollisuuden tunnistaa mahdolliset tyyppivirheet JavaScript-koodissasi.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio tarjoaa tyypintarkistuksen sekä TypeScript- että JavaScript-tiedostoille.

jsx

Tämä asetus määrittää, miten JSX-syntaksi (käytetään Reactissa ja muissa kehyksissä) tulisi muuntaa. Yleisiä arvoja ovat preserve, react, react-native ja react-jsx. preserve jättää JSX-syntaksin sellaisenaan, react muuntaa sen React.createElement-kutsuiksi, react-native on React Native -kehitystä varten, ja react-jsx muuntaa sen JSX-tehdasfunktioiksi. react-jsxdev on kehityskäyttöön.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio sopii React-projekteihin, muuntaen JSX:n React.createElement-kutsuiksi.

declaration

Tämä asetus luo määritystiedostoja (.d.ts) TypeScript-koodillesi. Määritystiedostot tarjoavat tyyppitietoa koodillesi, jolloin muut TypeScript-projektit tai JavaScript-projektit voivat käyttää koodiasi asianmukaisen tyypintarkistuksen avulla.

Esimerkki:

            "compilerOptions": {
  "declaration": true
}
            

              
                Copy
              
            
          

Tämä konfiguraatio luo .d.ts-tiedostot käännettyjen JavaScript-tiedostojen rinnalle.

declarationMap

Tämä asetus luo lähdekarttatiedostoja (.d.ts.map) luoduille määritystiedostoille. Lähdekartat mahdollistavat virheenkorjaajien ja muiden työkalujen palata alkuperäiseen TypeScript-lähdekoodiin, kun työskennellään määritystiedostojen kanssa.

Esimerkki:

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

              
                Copy
              
            
          

sourceMap

Tämä asetus luo lähdekarttatiedostoja (.js.map) käännetylle JavaScript-koodille. Lähdekartat mahdollistavat virheenkorjaajien ja muiden työkalujen palata alkuperäiseen TypeScript-lähdekoodiin, kun virheenkorjausta tehdään selaimessa tai muissa ympäristöissä.

Esimerkki:

            "compilerOptions": {
  "sourceMap": true
}
            

              
                Copy
              
            
          

outFile

Tämä asetus yhdistää ja tuottaa kaikki tulostustiedostot yhdeksi tiedostoksi. Tätä käytetään tyypillisesti koodin niputtamiseen selainpohjaisia sovelluksia varten.

Esimerkki:

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

              
                Copy
              
            
          

outDir

Tämä asetus määrittää käännettyjen JavaScript-tiedostojen tulostushakemiston. Jos sitä ei ole määritetty, kääntäjä sijoittaa tulostustiedostot samaan hakemistoon kuin lähdetiedostot.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio sijoittaa käännetyn JavaScript-tiedostot dist-hakemistoon.

rootDir

Tämä asetus määrittää TypeScript-projektin juurihakemiston. Kääntäjä käyttää tätä hakemistoa moduulinimien ratkaisemiseen ja tulostustiedostopolkujen luomiseen. Tämä on erityisen hyödyllistä monimutkaisille projektirakenteille.

Esimerkki:

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

              
                Copy
              
            
          

removeComments

Tämä asetus poistaa kommentit käännetystä JavaScript-koodista. Tämä voi auttaa pienentämään tulostustiedostojen kokoa.

Esimerkki:

            "compilerOptions": {
  "removeComments": true
}
            

              
                Copy
              
            
          

noEmitOnError

Tämä asetus estää kääntäjää luomasta JavaScript-tiedostoja, jos tyyppivirheitä havaitaan. Tämä varmistaa, että vain kelvollista koodia luodaan.

Esimerkki:

            "compilerOptions": {
  "noEmitOnError": true
}
            

              
                Copy
              
            
          

strict

Tämä asetus ottaa käyttöön kaikki tiukat tyypintarkistusasetukset. Tätä suositellaan erittäin uusille projekteille, sillä se auttaa löytämään mahdolliset virheet ja varmistamaan parhaiden käytäntöjen noudattamisen.

Esimerkki:

            "compilerOptions": {
  "strict": true
}
            

              
                Copy
              
            
          

Tiukan tilan käyttöönotto vastaa seuraavien asetusten käyttöönottoa:

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

esModuleInterop

Tämä asetus mahdollistaa CommonJS- ja ES-moduulien välisen yhteentoimivuuden. Se sallii CommonJS-moduulien tuonnin ES-moduuleihin ja päinvastoin.

Esimerkki:

            "compilerOptions": {
  "esModuleInterop": true
}
            

              
                Copy
              
            
          

forceConsistentCasingInFileNames

Tämä asetus pakottaa tiedostonimissä yhtenäisen kirjainkoon. Tämä on tärkeää alustojen välisen yhteensopivuuden kannalta, sillä jotkin käyttöjärjestelmät ovat kirjainkokoriippuvaisia ja toiset eivät.

Esimerkki:

            "compilerOptions": {
  "forceConsistentCasingInFileNames": true
}
            

              
                Copy
              
            
          

baseUrl ja paths

Nämä asetukset mahdollistavat moduulin resoluution määrittämisen. baseUrl määrittää perustiedostohakemiston suhteettomien moduulinimien ratkaisemiseen, ja paths sallii mukautettujen moduulialiasien määrittämisen.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio sallii moduulien tuonnin aliasien avulla, kuten @components/MyComponent ja @utils/myFunction.

Edistynyt konfiguraatio: Perusasioiden ulkopuolella

Nyt tarkastellaan joitakin edistyneitä tsconfig.json-asetuksia, jotka voivat edelleen parantaa TypeScript-kehityskokemustasi.

Inkrementaalinen käännös

TypeScript tukee inkrementaalista käännöstä, mikä voi merkittävästi nopeuttaa rakennusprosessia suurissa projekteissa. Ottaaksesi käyttöön inkrementaalisen käännöksen, aseta incremental-asetus arvoon true ja määritä tsBuildInfoFile-asetus.

Esimerkki:

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

              
                Copy
              
            
          

tsBuildInfoFile-asetus määrittää tiedoston, johon kääntäjä tallentaa rakennustiedot. Näitä tietoja käytetään määrittämään, mitkä tiedostot on käännettävä uudelleen myöhemmissä rakennuksissa.

Projektiviittaukset

Projektiviittaukset mahdollistavat koodisi rakentamisen pienempiin, helpommin hallittaviin projekteihin. Tämä voi parantaa rakennusaikoja ja koodin organisoitumista suurissa koodikannoissa. Hyvä analogia tähän konseptiin on mikropalveluarkkitehtuuri – jokainen palvelu on itsenäinen, mutta tukeutuu muihin ekosysteemissä.

Käyttääksesi projektiviittauksia, sinun on luotava erillinen tsconfig.json-tiedosto jokaiselle projektille. Sitten pääasiassa tsconfig.json-tiedostossa voit määrittää viitattavat projektit käyttämällä references-asetusta.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio määrittää, että nykyinen projekti riippuu projekteista, jotka sijaitsevat hakemistoissa ./project1 ja ./project2.

Mukautetut muuntajat

Mukautetut muuntajat sallivat TypeScript-kääntäjän tulosteen muokkaamisen. Tätä voidaan käyttää moniin eri tarkoituksiin, kuten mukautettujen koodimuunnosten lisäämiseen, käyttämättömän koodin poistamiseen tai tulosteen optimointiin tietyille ympäristöille. Niitä käytetään yleisesti i18n-kansainvälistys- ja lokalisointitehtävissä.

Käyttääksesi mukautettuja muuntajia sinun on luotava erillinen JavaScript-tiedosto, joka vie ulos funktion, jota kääntäjä kutsuu. Sitten voit määrittää muuntajatiedoston käyttämällä plugins-asetusta tsconfig.json-tiedostossa.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio määrittää, että ./transformer.js-tiedostoa tulisi käyttää mukautettuna muuntajana.

Tiedostot, sisällyttäminen ja poissulkeminen

compilerOptions-asetusten lisäksi tsconfig.json-tiedoston muut juuritason asetukset ohjaavat, mitkä tiedostot sisällytetään käännösprosessiin:

• files: Taulukko tiedostopoluista, jotka sisällytetään käännökseen.
• include: Taulukko glob-kuvioista, jotka määrittelevät sisällytettävät tiedostot.
• exclude: Taulukko glob-kuvioista, jotka määrittelevät poissuljettavat tiedostot.

Nämä asetukset tarjoavat tarkan hallinnan siitä, mitkä tiedostot TypeScript-kääntäjä käsittelee. Voit esimerkiksi sulkea pois testitiedostot tai generoidun koodin käännösprosessista.

Esimerkki:

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

              
                Copy
              
            
          

Tämä konfiguraatio sisältää kaikki tiedostot src-hakemistosta ja sen alihakemistoista, samalla kun se jättää pois tiedostot node_modules- ja dist-hakemistoista, sekä kaikki tiedostot, joiden tiedostopääte on .spec.ts (tyypillisesti käytetään yksikkötesteihin).

Kääntäjäasetukset tietyille skenaarioille

Eri projektit saattavat vaatia erilaisia kääntäjäasetuksia optimaalisten tulosten saavuttamiseksi. Tarkastellaan muutamia erityisiä skenaarioita ja niille suositeltuja kääntäjäasetuksia.

Verkkosovellusten kehitys

Verkkosovellusten kehityksessä haluat yleensä käyttää seuraavia kääntäjäasetuksia:

            {
  "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
              
            
          

Nämä asetukset sopivat moderneihin verkkosovelluksiin, jotka käyttävät Reactia tai muita vastaavia kehyksiä. Ne kohdistavat uusimmat ECMAScript-ominaisuudet, käyttävät ES-moduuleja ja mahdollistavat tiukan tyypintarkistuksen.

Node.js-taustakehitys

Node.js-taustakehityksessä haluat yleensä käyttää seuraavia kääntäjäasetuksia:

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

              
                Copy
              
            
          

Nämä asetukset sopivat Node.js-sovelluksiin, jotka käyttävät CommonJS-moduulijärjestelmää. Ne kohdistavat uusimmat ECMAScript-ominaisuudet, mahdollistavat tiukan tyypintarkistuksen ja sallivat JSON-tiedostojen tuonnin moduuleina.

Kirjastokehitys

Kirjastokehityksessä haluat yleensä käyttää seuraavia kääntäjäasetuksia:

            {
  "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
              
            
          

Nämä asetukset sopivat kirjastojen luomiseen, joita voidaan käyttää sekä selain- että Node.js-ympäristöissä. Ne luovat määritystiedostoja ja lähdekarttoja parantaen kehittäjäkokemusta.

Parhaat käytännöt TSConfig-hallintaan

Tässä muutamia parhaita käytäntöjä, jotka kannattaa pitää mielessä hallitessasi tsconfig.json-tiedostojasi:

• Aloita peruskonfiguraatiolla: Luo perusmuotoinen tsconfig.json-tiedosto yleisillä asetuksilla ja laajenna sitä sitten muissa projekteissa käyttämällä extends-asetusta.
• Käytä tiukkaa tilaa: Ota käyttöön tiukka tila mahdollisten virheiden havaitsemiseksi ja parhaiden käytäntöjen noudattamisen varmistamiseksi.
• Määritä moduulin resoluutio: Määritä moduulin resoluutio oikein välttääksesi tuontivirheet.
• Käytä projektiviittauksia: Jäsennä koodisi pienemmiksi, helpommin hallittaviksi projekteiksi käyttämällä projektiviittauksia.
• Pidä tsconfig.json-tiedostosi ajan tasalla: Tarkista tsconfig.json-tiedostosi säännöllisesti ja päivitä sitä projektisi kehittyessä.
• Versiohallitse tsconfig.json-tiedostosi: Sitouta tsconfig.json-tiedostosi versionhallintaan muun lähdekoodisi kanssa.
• Dokumentoi konfiguraatiosi: Lisää kommentteja tsconfig.json-tiedostoosi selittääksesi jokaisen asetuksen tarkoituksen.

Yhteenveto: TypeScript-konfiguraation hallinta

tsconfig.json-tiedosto on tehokas työkalu TypeScript-kääntäjän määrittämiseen ja rakennusprosessin hallintaan. Ymmärtämällä käytettävissä olevat asetukset ja noudattamalla parhaita käytäntöjä voit hienosäätää TypeScript-projektejasi optimaalisen suorituskyvyn, ylläpidettävyyden ja yhteensopivuuden saavuttamiseksi. Tämä opas on tarjonnut kattavan yleiskatsauksen tsconfig.json-tiedoston edistyneistä vaihtoehdoista, antaen sinulle täyden hallinnan TypeScript-kehitystyönkulkuun. Muista aina tutustua viralliseen TypeScript-dokumentaatioon uusimman tiedon ja ohjeistuksen saamiseksi. Projektiesi kehittyessä myös ymmärryksesi ja näiden tehokkaiden konfigurointityökalujen hyödyntäminen tulisi kehittyä. Hyvää koodausta!