@lokalise/tsconfig

Shared TypeScript configuration for Lokalise projects.

Getting Started

Requirements:

TypeScript >=5.9.0
ESM codebase

Installation:

npm install --save-dev @lokalise/tsconfig

TypeScript configuration depends on whether you're using a bundler (Vite, esbuild, SWC, etc.) or tsc to build your code:

Bundlers are commonly used for frontend applications, where they also bundle and optimize code for faster loading.
tsc is typically used for backend applications and libraries, where you directly compile TypeScript into JavaScript.

Using a Bundler

Create a tsconfig.json that whitelists the files for type-checking:

{
  "extends": "@lokalise/tsconfig/bundler",
  "include": ["src/**/*", "test/**/*", "vitest.config.ts"]
}

For frontend applications running in the DOM:

{
  "extends": "@lokalise/tsconfig/bundler-dom",
  "include": ["src/**/*", "test/**/*", "vitest.config.ts"]
}

Using `tsc` (TypeScript Compiler)

Create a tsconfig.json that whitelists the files for type-checking:

{
  "extends": "@lokalise/tsconfig/tsc",
  "include": ["src/**/*", "test/**/*", "vitest.config.ts"]
}

For frontend applications running in the DOM:

{
  "extends": "@lokalise/tsconfig/tsc-dom",
  "include": ["src/**/*", "test/**/*", "vitest.config.ts"]
}

Create a tsconfig.build.json for building the code, ensuring that only the necessary files are included, and unnecessary ones are excluded.

For building an application or a service:

{
  "extends": ["./tsconfig.json", "@lokalise/tsconfig/build-app"],
  "include": ["src/**/*"],
  "exclude": ["src/**/*.test.ts"]
}

For building a publishable library:

{
  "extends": ["./tsconfig.json", "@lokalise/tsconfig/build-public-lib"],
  "include": ["src/**/*"],
  "exclude": ["src/**/*.test.ts"]
}

For building a private monorepo library:

{
  "extends": ["./tsconfig.json", "@lokalise/tsconfig/build-private-lib"],
  "include": ["src/**/*"],
  "exclude": ["src/**/*.test.ts"]
}

Additional Configuration Options

JSX Support

If your app uses JSX, add jsx option in tsconfig.json:

{
  "extends": "@lokalise/tsconfig/bundler-dom",
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

Adding Global Types

To include additional type definitions, add types option in tsconfig.json:

{
  "extends": "@lokalise/tsconfig/tsc",
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Options That Can Be Disabled To Ease Adoption

erasableSyntaxOnly

It marks the following syntax as errors:

enum declarations
namespace and module with runtime code
Parameter properties in classes
Non-ECMAScript import = and export = assignments

To disable:

{
  "extends": "@lokalise/tsconfig/tsc",
  "compilerOptions": {
    "erasableSyntaxOnly": false
  }
}

noUncheckedIndexedAccess

It ensures that accessing arrays or objects without checking if a value exists results in a TypeScript error, preventing potential runtime crashes.

Example for accessing the array:

const arr: string[] = [];

console.log(arr[0].trim());

With "noUncheckedIndexedAccess": true → TypeScript error: "Object is possibly undefined"
With "noUncheckedIndexedAccess": false → No error, but at runtime, this will throw: "TypeError: Cannot read properties of undefined (reading 'trim')"

Example for accessing the object:

const obj: Record<string, string> = {};

console.log(obj.some.trim());

With "noUncheckedIndexedAccess": true → TypeScript error: "obj.some is possibly undefined"
With "noUncheckedIndexedAccess": false → No error, but at runtime, this will throw: "TypeError: Cannot read properties of undefined (reading 'trim')"

To disable:

{
  "extends": "@lokalise/tsconfig/tsc",
  "compilerOptions": {
    "noUncheckedIndexedAccess": false
  }
}

Package detail