npm package: @magzhan-sanzyzbayev/tsconfig
Description: Base TypeScript config for React + Next + Node projects
Author: DSRC TEAM
Latest version: 1.0.14

# @magzhan-sanzyzbayev/tsconfig

Strict and modern TypeScript configs for React (SPA / app) and Next.js 13–16

---

## 🇷🇺 Русский

### 📦 Описание

`@magzhan-sanzyzbayev/tsconfig` — это набор переиспользуемых, строгих и современных
TypeScript-конфигураций для frontend и backend проектов:

- React (SPA / app, Vite)
- Next.js (версии 13–16, App Router и Pages Router)
- Node.js (серверные приложения)

Цель пакета — убрать дублирование `tsconfig.json` между проектами и
обеспечить единые правила типизации.

---

### 📂 Содержимое пакета

| Файл        | Назначение                                       |
| ----------- | ------------------------------------------------ |
| `base.json` | Общая строгая база без привязки к платформе      |
| `app.json`  | React SPA (Vite, DOM + JSX, современный JSX)     |
| `next.json` | Next.js 13–16 (совместим с App Router)           |
| `node.json` | Node.js (bundler resolution, современные модули) |

---

### 🚀 Установка

```bash
npm install -D @magzhan-sanzyzbayev/tsconfig
```

```bash
pnpm add -D @magzhan-sanzyzbayev/tsconfig
```

```bash
yarn add -D @magzhan-sanzyzbayev/tsconfig
```

---

### 🧩 Использование

#### React / SPA / Vite

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/app.json",
  "include": ["src"]
}
```

---

#### Next.js 13–16

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/next.json",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

> `next-env.d.ts` должен находиться в проекте и добавляться в `include`.

---

#### Node.js

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/node.json",
  "include": ["vite.config.ts"],
  "exclude": ["src", "node_modules"]
}
```

---

### 🧠 Архитектура

- `base.json`
  Содержит строгие правила TypeScript и не зависит от среды выполнения.

- `app.json`
  Расширяет `base.json`, добавляет DOM, современный JSX (react-jsx) и типы Vite.

- `next.json`
  Расширяет `app.json`, использует `jsx: preserve` и совместим с Next.js 13–16.

- `node.json`
  Расширяет `base.json` для Node.js проектов с moduleResolution: "bundler" для современных модулей.

---

### ⚠️ Важные нюансы

В shared-конфигах **намеренно отсутствуют**:

- `include` / `exclude`
- `baseUrl`
- `paths`
- `types`
- `references`

Эти параметры зависят от структуры конкретного проекта и должны
задаваться локально.

---

### ❓ Возможные вопросы

**Можно ли использовать в monorepo?**
Да, конфиги совместимы с pnpm, turborepo и другими monorepo-подходами.

**Можно ли переопределять правила?**
Да, любой `compilerOptions` можно переопределить в проекте.

**Почему `moduleResolution: "bundler"`?**
Это актуальный стандарт для Vite, Next.js 13+ и современных bundler'ов, корректно работающий с ESM. Используется даже в Node.js конфиге для совместимости с современными модулями.

## 🇬🇧 English

### 📦 Description

`@magzhan-sanzyzbayev/tsconfig` is a set of reusable, strict and modern
TypeScript configurations for frontend and backend projects:

- React (SPA / app, Vite)
- Next.js (versions 13–16, App Router and Pages Router)
- Node.js (server-side applications)

The goal is to avoid duplicated `tsconfig.json` files and enforce consistent
TypeScript rules across projects.

---

### 📂 Package contents

| File        | Purpose                                      |
| ----------- | -------------------------------------------- |
| `base.json` | Shared strict base config                    |
| `app.json`  | React SPA (Vite, DOM + modern JSX)           |
| `next.json` | Next.js 13–16 configuration                  |
| `node.json` | Node.js (bundler resolution, modern modules) |

---

### 🚀 Installation

```bash
npm install -D @magzhan-sanzyzbayev/tsconfig
```

---

### 🧩 Usage

#### React / SPA / Vite

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/app.json",
  "include": ["src"]
}
```

---

#### Next.js 13–16

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/next.json",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"]
}
```

---

#### Node.js

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/node.json",
  "include": ["vite.config.ts"],
  "exclude": ["src", "node_modules"]
}
```

---

### ⚠️ Important notes

The shared configs intentionally do NOT include:

- `include` / `exclude`
- `baseUrl`
- `paths`
- `types`

These options must be defined per project.

---

### ❓ Possible questions

**Is it monorepo-ready?**
Yes, fully compatible.

**Can rules be overridden?**
Yes, project-level overrides are supported.

**Why `moduleResolution: "bundler"`?**
It is the recommended setup for modern bundlers, Next.js, and even Node.js configs for compatibility with modern modules.

## 🇰🇿 Қазақша

### 📦 Сипаттама

`@magzhan-sanzyzbayev/tsconfig` — frontend және backend жобаларға арналған
қайта қолданылатын, қатаң және заманауи TypeScript конфигурациялары:

- React (SPA / app, Vite)
- Next.js (13–16 нұсқалары)
- Node.js (серверлік қосымшалар)

Мақсаты — жобалар арасында `tsconfig.json` көшірмесін азайту және
бірдей TypeScript ережелерін қолдану.

---

### 📂 Пакет құрамында

| Файл        | Мақсаты                      |
| ----------- | ---------------------------- |
| `base.json` | Жалпы қатаң базалық конфиг   |
| `app.json`  | React SPA (Vite, DOM + JSX)  |
| `next.json` | Next.js 13–16                |
| `node.json` | Node.js (bundler, модульдер) |

---

### 🚀 Орнату

```bash
npm install -D @magzhan-sanzyzbayev/tsconfig
```

---

### 🧩 Қолдану

#### React / SPA

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/app.json",
  "include": ["src"]
}
```

---

#### Next.js 13–16

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/next.json",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"]
}
```

---

#### Node.js

```json
{
  "extends": "@magzhan-sanzyzbayev/tsconfig/node.json",
  "include": ["vite.config.ts"],
  "exclude": ["src", "node_modules"]
}
```

---

### ⚠️ Маңызды ескертулер

Shared конфигурацияларда әдейі жоқ:

- `include` / `exclude`
- `baseUrl`
- `paths`
- `types`

Бұл параметрлер әр жобаға жеке орнатылуы керек.

---

### ❓ Мүмкін сұрақтар

**Monorepo-да қолдануға бола ма?**
Иә, толық үйлесімді.

**Ережелерді өзгертуге бола ма?**
Иә, жоба ішінде қайта анықтауға болады.

**Неге `moduleResolution: "bundler"`?**
Бұл қазіргі bundler-лер, Next.js және тіпті Node.js үшін ұсынылған стандарт, заманауи модульдермен үйлесімді.