TypeScript-konfiguration: En omfattende guide til tsconfig.json

TypeScript, et supersæt af JavaScript, bringer statisk typning til den dynamiske verden af webudvikling. En velkonfigureret tsconfig.json-fil er afgørende for at udnytte den fulde kraft af TypeScript. Denne guide giver en omfattende oversigt over tsconfig.json, der dækker essentielle compiler-indstillinger, projektopætning og avancerede konfigurationer.

Hvad er tsconfig.json?

tsconfig.json-filen er en konfigurationsfil, der specificerer compiler-indstillingerne for et TypeScript-projekt. Den fortæller TypeScript-compileren, hvordan den skal transpilerere TypeScript-kode til JavaScript. Denne fil er essentiel for at definere projektets struktur, fastsætte kompileringsregler og sikre konsistens på tværs af udviklingsteamet, uanset om teamet er placeret på et enkelt kontor eller fordelt over flere kontinenter.

Oprettelse af en tsconfig.json-fil

For at oprette en tsconfig.json-fil skal du navigere til dit projekts rodmappe i terminalen og køre følgende kommando:

tsc --init

Denne kommando genererer en grundlæggende tsconfig.json-fil med almindeligt anvendte compiler-indstillinger. Du kan derefter tilpasse filen, så den passer til dit projekts specifikke krav. En typisk tsconfig.json vil indeholde indstillinger som compilerOptions, include og exclude.

Essentielle Compiler-indstillinger

compilerOptions-sektionen er hjertet i tsconfig.json-filen. Den indeholder en bred vifte af indstillinger, der styrer TypeScript-compilerens adfærd. Her er nogle af de vigtigste compiler-indstillinger:

target

target-indstillingen specificerer ECMAScript-målversionen for den genererede JavaScript-kode. Almindelige værdier inkluderer ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. At vælge det rigtige mål er afgørende for at sikre kompatibilitet med det tilsigtede kørselsmiljø, såsom browsere eller Node.js-versioner.

Eksempel:

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

module

module-indstillingen specificerer stilen for generering af modul-kode. Almindelige værdier inkluderer CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 og ESNext. Valget af modulsystem afhænger af målmiljøet og den anvendte module bundler (f.eks. Webpack, Rollup, Parcel). For Node.js bruges CommonJS ofte, mens for moderne webapplikationer foretrækkes ES6 eller ESNext med en module bundler. Brug af ESNext giver udviklere mulighed for at udnytte de nyeste funktioner og optimeringer, mens de stoler på, at bundleren håndterer det endelige modulformat.

Eksempel:

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

lib

lib-indstillingen specificerer en liste over biblioteksfiler, der skal inkluderes i kompileringen. Disse biblioteksfiler leverer typedefinitioner for indbyggede JavaScript-API'er og browser-API'er. Almindelige værdier inkluderer 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, og mange flere. At vælge de passende biblioteker sikrer, at TypeScript-compileren har den nødvendige typeinformation for målmiljøet. Brug af DOM-biblioteket gør det muligt for projektet at kompilere kode, der bruger browserspecifikke API'er uden typefejl.

Eksempel:

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

allowJs

allowJs-indstillingen giver TypeScript-compileren mulighed for at kompilere JavaScript-filer sammen med TypeScript-filer. Dette er nyttigt for gradvist at migrere eksisterende JavaScript-projekter til TypeScript. At sætte denne til true gør det muligt for compileren at behandle .js-filer, hvilket muliggør en gradvis indførelse af TypeScript i et projekt.

Eksempel:

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

jsx

jsx-indstillingen specificerer, hvordan JSX-syntaks skal håndteres. Almindelige værdier inkluderer preserve, react, react-native og react-jsx. preserve bevarer JSX-syntaksen i outputtet, mens react transformerer JSX til React.createElement-kald. react-jsx bruger den nye JSX-transformation, der blev introduceret i React 17, som ikke kræver import af React. Valg af den korrekte JSX-indstilling er afgørende for projekter, der bruger React eller andre JSX-baserede biblioteker.

Eksempel:

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

declaration

declaration-indstillingen genererer tilsvarende .d.ts-deklarationsfiler for hver TypeScript-fil. Deklarationsfiler indeholder typeinformation og bruges af andre TypeScript-projekter til at forbruge den kompilerede kode. Generering af deklarationsfiler er essentielt for at skabe genanvendelige biblioteker og moduler. Disse filer giver andre TypeScript-projekter mulighed for at forstå de typer og interfaces, som biblioteket eksponerer, uden at skulle kompilere den oprindelige kildekode.

Eksempel:

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

sourceMap

sourceMap-indstillingen genererer source map-filer, som mapper den genererede JavaScript-kode tilbage til den oprindelige TypeScript-kode. Source maps er essentielle for debugging af TypeScript-kode i browsere og andre miljøer. Når der opstår en fejl i JavaScript-koden, giver source map'en udvikleren mulighed for at se den tilsvarende TypeScript-kode i debuggeren, hvilket gør det lettere at identificere og rette fejlen.

Eksempel:

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

outDir

outDir-indstillingen specificerer output-mappen for de genererede JavaScript-filer. Denne indstilling hjælper med at organisere projektets build-output ved at adskille kildekoden fra den kompilerede kode. Brug af en outDir gør det lettere at administrere build-processen og implementere applikationen.

Eksempel:

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

rootDir

rootDir-indstillingen specificerer rodmappen for TypeScript-projektet. Compileren bruger denne mappe som base for at opløse modulnavne. Denne indstilling er især vigtig for projekter med en kompleks mappestruktur. Korrekt indstilling af rootDir sikrer, at compileren kan finde alle nødvendige moduler og afhængigheder.

Eksempel:

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

strict

strict-indstillingen aktiverer alle strenge typekontrol-indstillinger. Dette anbefales stærkt til nye TypeScript-projekter, da det hjælper med at fange potentielle fejl tidligt i udviklingsprocessen. Aktivering af strict mode håndhæver strengere regler for typekontrol, hvilket fører til mere robust og vedligeholdelsesvenlig kode. Det er en bedste praksis at aktivere strict mode i alle nye TypeScript-projekter.

Eksempel:

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

esModuleInterop

esModuleInterop-indstillingen muliggør interoperabilitet mellem CommonJS og ES-moduler. Dette er vigtigt for projekter, der bruger begge typer moduler. Når esModuleInterop er aktiveret, håndterer TypeScript automatisk forskellene mellem CommonJS og ES-moduler, hvilket gør det lettere at importere og eksportere moduler mellem de to systemer. Denne indstilling er især nyttig, når man arbejder med tredjepartsbiblioteker, der kan bruge forskellige modulsystemer.

Eksempel:

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

moduleResolution

moduleResolution-indstillingen specificerer, hvordan TypeScript opløser modulimport. Almindelige værdier inkluderer Node og Classic. Node-modulopløsningsstrategien er standard og er baseret på Node.js-modulopløsningsalgoritmen. Classic-modulopløsningsstrategien er ældre og mindre brugt. Brug af Node-modulopløsningsstrategien sikrer, at TypeScript korrekt kan opløse modulimport i et Node.js-miljø.

Eksempel:

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

baseUrl og paths

baseUrl- og paths-indstillingerne bruges til at konfigurere modulopløsning for ikke-relative modulimporter. baseUrl-indstillingen specificerer basismappen for opløsning af ikke-relative modulnavne. paths-indstillingen giver dig mulighed for at mappe modulnavne til specifikke placeringer på filsystemet. Disse indstillinger er især nyttige for projekter med en kompleks mappestruktur og for at forenkle modulimport. Brug af baseUrl og paths kan gøre koden mere læsbar og vedligeholdelsesvenlig.

Eksempel:

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

Include- og Exclude-indstillinger

include- og exclude-indstillingerne specificerer, hvilke filer der skal inkluderes i kompileringen, og hvilke filer der skal udelukkes. Disse indstillinger bruger glob-mønstre til at matche filnavne. Brug af include og exclude giver dig mulighed for at kontrollere, hvilke filer der behandles af TypeScript-compileren, hvilket forbedrer build-ydeevnen og reducerer fejl. Det er en bedste praksis eksplicit at specificere, hvilke filer der skal inkluderes i kompileringen.

Eksempel:

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

Extends-indstilling

extends-indstillingen giver dig mulighed for at arve compiler-indstillinger fra en anden tsconfig.json-fil. Dette er nyttigt for at dele fælles konfigurationsindstillinger mellem flere projekter eller for at oprette grundlæggende konfigurationer. Brug af extends-indstillingen fremmer genbrug af kode og reducerer duplikering. Det er en bedste praksis at oprette grundlæggende konfigurationer og udvide dem i individuelle projekter.

Eksempel:

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

Avancerede konfigurationer

Ud over de essentielle compiler-indstillinger understøtter tsconfig.json avancerede konfigurationer for specialiserede scenarier.

Inkrementel kompilering

For store projekter kan inkrementel kompilering markant forbedre build-tider. TypeScript kan cache resultaterne af tidligere kompileringer og kun genkompilere filer, der er blevet ændret. Aktivering af inkrementel kompilering kan dramatisk reducere build-tider for store projekter. Dette er især vigtigt for projekter med et stort antal filer og afhængigheder.

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

Project References

Project references giver dig mulighed for at strukturere store TypeScript-projekter i mindre, uafhængige moduler. Dette kan forbedre build-tider og kodeorganisering. Brug af project references kan gøre store projekter mere håndterbare og lettere at vedligeholde. Det er en bedste praksis at bruge project references til store, komplekse projekter.

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

Brugerdefinerede typedefinitioner

Nogle gange kan du have brug for at levere typedefinitioner til JavaScript-biblioteker, der ikke har dem. Du kan oprette brugerdefinerede .d.ts-filer for at definere typerne for disse biblioteker. Oprettelse af brugerdefinerede typedefinitioner giver dig mulighed for at bruge JavaScript-biblioteker i din TypeScript-kode uden at ofre typesikkerhed. Dette er især nyttigt, når man arbejder med ældre JavaScript-kode eller biblioteker, der ikke leverer deres egne typedefinitioner.

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

Bedste praksis

• Brug Strict Mode: Aktivér strict-indstillingen for forbedret typekontrol.
• Specificer Target: Vælg den passende target-version til dit kørselsmiljø.
• Organiser Output: Brug outDir til at adskille kildekode fra kompileret kode.
• Administrer afhængigheder: Brug include og exclude til at kontrollere, hvilke filer der kompileres.
• Udnyt Extends: Del fælles konfigurationsindstillinger med extends-indstillingen.
• Check konfigurationen ind i versionskontrol: Commit `tsconfig.json` til git for at opretholde konsistens på tværs af udviklermiljøer og CI/CD pipelines.

Fejlfinding af almindelige problemer

Konfiguration af tsconfig.json kan nogle gange være udfordrende. Her er nogle almindelige problemer og deres løsninger:

Problemer med modulopløsning

Hvis du støder på fejl med modulopløsning, skal du sikre, at moduleResolution-indstillingen er korrekt konfigureret, og at baseUrl- og paths-indstillingerne er sat korrekt op. Dobbelttjek stierne specificeret i paths-indstillingen for at sikre, at de er korrekte. Verificer, at alle nødvendige moduler er installeret i node_modules-mappen.

Typefejl

Typefejl kan opstå, hvis typedefinitionerne er forkerte eller mangler. Sørg for, at du har de korrekte typedefinitioner installeret for alle de biblioteker, du bruger. Hvis du bruger et JavaScript-bibliotek, der ikke har typedefinitioner, kan du overveje at oprette brugerdefinerede typedefinitioner.

Kompileringsfejl

Kompileringsfejl kan opstå, hvis der er syntaksfejl eller typefejl i din TypeScript-kode. Gennemgå fejlmeddelelserne omhyggeligt og ret eventuelle syntaksfejl eller typefejl. Sørg for, at din kode følger TypeScript-kodningskonventionerne.

Konklusion

En velkonfigureret tsconfig.json-fil er essentiel for et vellykket TypeScript-projekt. Ved at forstå de essentielle compiler-indstillinger og avancerede konfigurationer kan du optimere din udviklingsworkflow, forbedre kodekvaliteten og sikre kompatibilitet med målmiljøet. At investere tid i korrekt konfiguration af tsconfig.json vil betale sig i det lange løb ved at reducere fejl, forbedre vedligeholdelsesvenligheden og strømline byggeprocessen. Dette resulterer i mere effektiv og pålidelig softwareudvikling. Informationen her er designet til at være universelt anvendelig og bør give et solidt fundament for at starte et nyt projekt med TypeScript.

Husk at konsultere den officielle TypeScript-dokumentation for den mest opdaterede information og detaljerede forklaringer af alle tilgængelige compiler-indstillinger. TypeScript-dokumentationen er en værdifuld ressource til at forstå finesserne i TypeScript-konfiguration.