MD
# Новый дизайн сайта Умный Сервис 2025 год.
### dev add
## package.json script description
`"check": "eslint . && tsc --noEmit"` - лексическая проверка кода и `.ts` файлов
`"dev": "vite"` - запуск проекта в режиме разработки
`"build": "tsc && vite build"` - сборка проекта (дефолтная)
`"build-unsafe": "tsc --noEmit --noCheck && vite build"` - сборка проекта (без проверок, не безопасно)
`"build:config": "tsc -p tsconfig.node.json"` - компиляция серверных файлов `.ts`
`"tsc": "tsc --outDir dist --rootDir ."` - комплияция всех файлов `.ts`
`"tsc-main": "tsc src/main.ts"` - компиляция `main.ts` файла
`"preview": "vite preview"` - запуск проекта в режиме предварительного просмотра
`"lint": "eslint ."` - лексическая проверка кода
`"lint:fix": "eslint . --fix"` - автофикс лексических ошибок
`"deploy": "node ./sass-build.js"` - сборка и компиляция файлов таблиц стилей проекта: sass => css исходников
## TS description
TypeScript в проектах Vite состоит из **двух окружений**:
1. **Клиентское (Frontend)** → работает в браузере
2. **Серверное (Node.js)** → используется для конфигурации, сборки и утилит
Проблема в том, что настройки для **браузера** и **Node.js** часто конфликтуют. Поэтому в проекте используются два файла: `tsconfig.node.json` с настройками для **Node.js**, а основной `tsconfig.json` остаётся для фронтенда.
### `tsconfig.node.json` description
🔎 Разбор всех ключей compilerOptions
#### 1. Базовые настройки компиляции
| Опция | Описание |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `"target": "ESNext"` | Компилирует код в **современный JavaScript (ESNext)**, поддерживая новые возможности. |
| `"module": "CommonJS"` | Использует **CommonJS-модули** (требуется для Node.js). |
| `"moduleResolution": "Node"` | Позволяет TypeScript правильно находить модули Node.js. |
| `"outDir": "./dist"` | Указывает папку, куда будут сохраняться скомпилированные файлы (`.js` и `.d.ts`). |
| `"rootDir": "./"` | Определяет корневую папку исходников. |
---
#### **2. Строгий режим и безопасность**
| Опция | Описание |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `"strict": true` | Включает **все строгие проверки TypeScript** (лучше для безопасности кода). |
| `"forceConsistentCasingInFileNames": true` | Запрещает различия в регистре имён файлов (`file.ts` ≠ `File.ts`). |
| `"skipLibCheck": true` | Отключает проверку типов в сторонних `.d.ts` библиотеках (ускоряет компиляцию). |
| `"isolatedModules": true` | Требует, чтобы каждый `.ts`-файл компилировался отдельно (важно для **ESM** и **Babel**). |
---
#### **3. Улучшенная работа с модулями**
| Опция | Описание |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `"resolveJsonModule": true` | Позволяет импортировать JSON-файлы как модули. |
| `"esModuleInterop": true` | Улучшает совместимость между CommonJS и ES-модулями (нужно для `import fs from "fs"`). |
| `"allowSyntheticDefaultImports": true` | Разрешает использование `import someLib from "library"`, даже если в CommonJS он экспортируется как `module.exports`. |
---
#### **4. Настройки вывода и сборки**
| Опция | Описание |
| ------------------- | --------------------------------------------------------------------- |
| `"composite": true` | Включает **инкрементальную компиляцию** (ускоряет работу с `tsc -b`). |
| `"noEmit": false` | **Разрешает** компиляцию `.ts` в `.js` (иначе файлы не создадутся). |
---
#### 🎯 \*\*Раздел \*\*\`\`
```json
"include": ["vite.config.ts"]
```
Этот параметр указывает файлы, которые TypeScript должен компилировать.\
В данном случае — \*\*только \*\*\`\`.
Если у вас несколько файлов конфигурации, например:
```json
"include": ["vite.config.ts", "scripts/**/*.ts"]
```
Это значит:
- `vite.config.ts` будет компилироваться.
- Все `.ts` файлы в папке `scripts/` тоже.
*Пример файла конфигурации:*
```json
{
"compilerOptions": {
"composite": true,
"module": "CommonJS",
"moduleResolution": "Node",
"target": "ESNext",
"strict": true,
"resolveJsonModule": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"outDir": "./dist",
"rootDir": "./",
"isolatedModules": true,
"noEmit": false,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["vite.config.ts"]
}
```
### 🎯 Когда tsconfig.node.json нужен?
* Когда `vite.config.ts` написан на TypeScript.
* Когда в проекте есть серверные скрипты на TS (например, для SSR или утилиты).
* Когда основной `tsconfig.json` содержит настройки для браузера, конфликтующие с Node.js.
```json
{
"compilerOptions": {
//? Базовые настройки компиляции
// Компилирует код в современный JavaScript (ESNext), поддерживая новые возможности.
"target": "ESNext",
// Использует модули последней версии (требуется для Node.js).
"module": "ESNext",
// Позволяет TypeScript правильно находить модули Node.js.
"moduleResolution": "bundler",
// Указывает папку, куда будут сохраняться скомпилированные файлы (.js и .d.ts).
"outDir": "./dist",
// Определяет корневую папку исходников.
//"rootDir": "./",
//? Строгий режим и безопасность
// Включает все строгие проверки TypeScript (лучше для безопасности кода).
"strict": true,
// Запрещает различия в регистре имён файлов (file.ts ≠ File.ts).
"forceConsistentCasingInFileNames": true,
// Отключает проверку типов в сторонних .d.ts библиотеках (ускоряет компиляцию).
"skipLibCheck": true,
// Требует, чтобы каждый .ts-файл компилировался отдельно (важно для ESM и Babel).
"isolatedModules": true,
//? Улучшенная работа с модулями
// Позволяет импортировать JSON-файлы как модули.
"resolveJsonModule": true,
// Улучшает совместимость между CommonJS и ES-модулями (нужно для import fs from "fs").
"esModuleInterop": true,
// Разрешает использование import someLib from "library", даже если в CommonJS он экспортируется как module.exports.
"allowSyntheticDefaultImports": true,
//? Настройки вывода и сборки
// Включает инкрементальную компиляцию (ускоряет работу с tsc -b).
"composite": true,
// Разрешает компиляцию .ts в .js (иначе файлы не создадутся).
"noEmit": false,
// разрешает создать файлы декларации
"declaration": true
// каталог для генерации файлов декларации
//"declarationDir": "./dist/types"
},
//? Этот параметр указывает файлы, которые TypeScript должен компилировать
//! серверная часть!.
// vite.config.ts. - файл конфигурации vite
// src/**/*.ts - Все .ts файлы в папке src/ тоже.
"include": ["vite.config.ts"]
}
```
---
### `tsconfig.json` description
Файл `tsconfig.json` – это конфигурационный файл TypeScript, который определяет, как TypeScript должен компилировать ваш код.
#### 📌 **Структура `tsconfig.json`**
Файл состоит из следующих основных частей:
- **`compilerOptions`** – настройки компилятора TypeScript.
- **`include`** – файлы, которые должны быть включены в компиляцию.
- **`exclude`** – файлы, которые должны быть исключены.
- **`files`** – конкретные файлы, которые должны компилироваться.
- **`extends`** – позволяет наследовать настройки от другого `tsconfig.json`.
- **`references`** – используется для поддержки многопроектных (`monorepo`) структур.
---
#### 🔍 **Разбор всех ключей `compilerOptions`**
#### **1. Настройки версии JavaScript**
| Опция | Описание |
|-------|----------|
| `"target": "ESNext"` | Компилирует код в последнюю версию JavaScript. Возможные значения: `"ES5"`, `"ES6"`, `"ES2017"`, `"ESNext"`. |
| `"module": "ESNext"` | Определяет, какой модульный стандарт используется (`CommonJS`, `ESNext`, `AMD` и др.). В браузере лучше `"ESNext"`, в Node.js — `"CommonJS"`. |
| `"moduleResolution": "Node"` | Разрешает модули так, как это делает Node.js. |
---
#### **2. Библиотеки и окружение**
| Опция | Описание |
|-------|----------|
| `"lib": ["ESNext", "DOM"]` | Определяет, какие API доступны (например, `DOM` для работы в браузере). |
---
#### **3. Проверки и строгий режим**
| Опция | Описание |
|-------|----------|
| `"strict": true` | Включает все строгие проверки TypeScript (аналог набора из `noImplicitAny`, `strictNullChecks`, `strictFunctionTypes` и др.). |
| `"noImplicitAny": true` | Запрещает использование `any` без явного указания. |
| `"strictNullChecks": true` | Запрещает использование `null` и `undefined` без явного указания в типах. |
| `"strictFunctionTypes": true` | Улучшает проверку типов для функций. |
| `"noImplicitThis": true` | Запрещает неявное использование `this` без контекста. |
| `"noUnusedLocals": true` | Показывает ошибку, если переменная объявлена, но не используется. |
| `"noUnusedParameters": true` | Показывает ошибку, если параметр функции объявлен, но не используется. |
| `"noFallthroughCasesInSwitch": true` | Запрещает пропуск `break` в `switch`. |
---
#### **4. Работа с файлами**
| Опция | Описание |
|-------|----------|
| `"allowJs": false` | Запрещает компилировать `.js` файлы (если `true`, TypeScript сможет работать и с JavaScript). |
| `"checkJs": false` | Если `true`, TypeScript проверяет типы в `.js` файлах. |
---
#### **5. Настройки вывода**
| Опция | Описание |
|-------|----------|
| `"outDir": "dist"` | Указывает папку для скомпилированных файлов (`.js` и `.d.ts`). |
| `"rootDir": "src"` | Указывает корневую папку исходных файлов. |
---
#### **6. Разрешение модулей**
| Опция | Описание |
|-------|----------|
| `"baseUrl": "./"` | Базовый путь для модулей. |
| `"paths": { "@components/*": ["src/components/*"] }` | Позволяет использовать алиасы для импортов (например, `@components/Button` вместо `../../components/Button`). |
---
#### **7. Генерация файлов**
| Опция | Описание |
|-------|----------|
| `"resolveJsonModule": true` | Позволяет импортировать JSON-файлы. |
| `"allowSyntheticDefaultImports": true` | Разрешает `import x from "module"`, даже если модуль экспортируется как `module.exports`. |
| `"declaration": true` | Генерирует `.d.ts` файлы (используется для создания библиотек). |
| `"sourceMap": true` | Создаёт `.map` файлы, которые помогают отлаживать TypeScript-код в браузере. |
---
#### 🔍 **Раздел `include`, `exclude` и `files`**
| Ключ | Описание |
|------|----------|
| `"include": ["src"]` | Включает все файлы в папке `src` в компиляцию. |
| `"exclude": ["node_modules", "dist"]` | Исключает файлы из компиляции. |
| `"files": ["src/index.ts"]` | Если указан, компилирует **только** перечисленные файлы. |
---
#### 🔗 **Раздел `extends`**
```json
"extends": "./tsconfig.base.json"
```
Позволяет наследовать настройки из другого файла.
---
#### 🏗 **Раздел `references` (для `monorepo` проектов)**
Используется в **больших проектах**, где есть несколько независимых модулей.
```json
"references": [
{ "path": "./packages/core" },
{ "path": "./packages/ui" }
]
```
Так можно разделить код на модули и компилировать их отдельно.
---
#### 🎯 **Когда нужен `tsconfig.json`?**
✅ **Нужен**, если:
- Вы работаете с TypeScript.
- Вам нужно настроить строгую проверку типов.
- Вы хотите оптимизировать компиляцию и структуру проекта.
❌ **Не нужен**, если:
- Проект полностью на JavaScript.
---
#### 🚀 **Как использовать `tsconfig.json`?**
Запуск компиляции TypeScript:
```sh
tsc
```
или компиляция без генерации `.js` файлов (только проверка):
```sh
tsc --noEmit
```
---
#### **Вывод**
Файл `tsconfig.json` – это **гибкий инструмент**, который позволяет:
- Контролировать версию JavaScript (`target`, `module`).
- Включать строгие проверки (`strict`, `noImplicitAny`).
- Управлять импортами (`paths`, `baseUrl`).
- Генерировать `.d.ts` файлы (`declaration`).
- Исключать ненужные файлы (`exclude`).
Теперь вы знаете, как **настроить TypeScript правильно**! 🚀
*Пример:*
```json
{
"compilerOptions": {
"target": "ESNext",
"module": "ESNext",
"moduleResolution": "Node",
"lib": ["ESNext", "DOM"],
"strict": true,
"allowJs": false,
"checkJs": false,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"noImplicitAny": true,
"strictNullChecks": true,
"strictFunctionTypes": true,
"noImplicitThis": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
"outDir": "dist",
"rootDir": "src",
"baseUrl": "./",
"paths": {
"@components/*": ["src/components/*"]
},
"resolveJsonModule": true,
"allowSyntheticDefaultImports": true,
"declaration": true,
"sourceMap": true
},
"include": ["src"],
"exclude": ["node_modules", "dist"],
"references": []
}
```
```json
{
"compilerOptions": {
//? Настройки версии JavaScript
// Компилирует код в последнюю версию JavaScript. Возможные значения: "ES5", "ES6", "ES2017", "ESNext".
"target": "ESNext",
// Определяет, какой модульный стандарт используется (CommonJS, ESNext, AMD и др.).
//! В браузере лучше "ESNext", в Node.js — "CommonJS".
"module": "ESNext",
// Разрешает модули так, как это делает Node.js.
"moduleResolution": "node",
//? Библиотеки и окружение
// Определяет, какие API доступны (например, DOM для работы в браузере).
"lib": ["ESNext", "DOM", "DOM.Iterable"],
//? Проверки и строгий режим
// Включает все строгие проверки TypeScript (аналог набора из noImplicitAny, strictNullChecks, strictFunctionTypes и др.).
"strict": true,
// Запрещает использование any без явного указания.
"noImplicitAny": true,
// Запрещает использование null и undefined без явного указания в типах.
"strictNullChecks": true,
// Улучшает проверку типов для функций.
"strictFunctionTypes": true,
// Запрещает неявное использование this без контекста.
"noImplicitThis": true,
// Показывает ошибку, если переменная объявлена, но не используется.
"noUnusedLocals": true,
// Показывает ошибку, если параметр функции объявлен, но не используется.
"noUnusedParameters": true,
// Запрещает пропуск break в switch.
"noFallthroughCasesInSwitch": true,
//? Работа с файлами
// Запрещает компилировать .js файлы (если true, TypeScript сможет работать и с JavaScript).
"allowJs": true,
// Если true, TypeScript проверяет типы в .js файлах.
"checkJs": false,
//? Настройки вывода
// Указывает папку для скомпилированных файлов (.js и .d.ts). "dist"
"outDir": "./dist",
// Указывает корневую папку исходных файлов. "src"
"rootDir": "./src",
//? Разрешение модулей
// Базовый путь для модулей. "./"
"baseUrl": "./src",
// Позволяет использовать алиасы для импортов (например, @components/Button вместо ../../components/Button).
"paths": {
"@/*": ["./*"],
"@/assets": ["assets/*"],
"@/components": ["components/*"],
"@/models": ["models/*"],
"@/pages": ["pages/*"],
"@/plugins": ["plugins/*"],
"@/scripts": ["scripts/*"],
"@/libs": ["libs/*"],
"@/dto": ["dto/*"]
},
//? Генерация файлов
// Позволяет импортировать JSON-файлы.
"resolveJsonModule": true,
// Разрешает import x from "module", даже если модуль экспортируется как module.exports.
"allowSyntheticDefaultImports": true,
// Генерирует .d.ts файлы (используется для создания библиотек).
"declaration": true,
// Создаёт .map файлы, которые помогают отлаживать TypeScript-код в браузере.
"sourceMap": true,
// Принудительно распознаёт модули в файлах даже без import/export.
"moduleDetection": "force",
// Меняет способ трансляции полей классов в JavaScript. Использует Object.defineProperty() для определения полей классов.
"useDefineForClassFields": true,
// Используется для сборки многомодульных проектов (TypeScript Project References).
// Позволяет использовать этот проект как зависимость в других TypeScript-проектах.
//! Требует "declaration": true (генерацию .d.ts файлов).
"composite": true,
//Указывает папку для файлов деклараций (.d.ts).
// Вместо того, чтобы генерировать .d.ts рядом с .js, они будут в ./dist/types.
//! Работает только если declaration: true.
//"declarationDir": "./dist/types",
// Позволяет импортировать .ts файлы с расширением (ESM-стиль).
// Разрешает import "./module.ts" в коде, даже если TypeScript обычно не требует .ts.
// import { something } from "./utils.ts"; // Без этой опции TypeScript выдаст ошибку
"allowImportingTsExtensions": false,
// Запрещает пропуск return в функциях, если они должны что-то возвращать.
// Показывает ошибку, если в функции не все ветки кода возвращают значение.
"noImplicitReturns": true,
// Запрещает TypeScript создавать .js файлы при компиляции. true- не создает
// TypeScript только проверяет код на ошибки, но НЕ генерирует .js.
// Полезно, если код компилирует Vite/ESBuild/Webpack.
"noEmit": false,
// Гарантирует, что TypeScript-компилятор работает по-файлово, как ESBuild или Babel.
// Запрещает использовать TypeScript-фичи, которые требуют полного анализа проекта (например, const enum).
//! Требуется Vite (из-за ESBuild).
"isolatedModules": true,
// Пропускает проверку типов в node_modules. (Ускоряет компиляцию, Позволяет избежать ошибок в зависимостях.)
// import express from "express"; // ❌ Ошибка, если в Express есть несовместимые типы
"skipLibCheck": true,
// Гарантирует, что файлы импортируются с правильным регистром.
// Предотвращает ошибки при сборке в Linux/Mac (где file.ts ≠ File.ts).
// import { something } from "./Utils.ts"; // ❌ Ошибка, если файл `utils.ts`
"forceConsistentCasingInFileNames": true
},
//? References
// Используется в больших проектах, где есть несколько независимых модулей.
// "references": [ { "path": "./packages/core" }, { "path": "./packages/ui" }]
// Так можно разделить код на модули и компилировать их отдельно.
"references": [{ "path": "./tsconfig.node.json" }],
//? Include
// Включает все файлы в папке src в компиляцию. "src"
//"include": ["src/**/*.ts"],
"include": ["src"],
//? Exclude
// Исключает файлы из компиляции. "exclude": ["node_modules", "dist"]
//! исключаем js файлы ❌Cannot write file 'e:/umserv/html2025/eslint.config.js' because it would overwrite input file.ts
"exclude": ["node_modules", "dist", "sass-build.js", "eslint.config.js"],
//? Files
// Если указан, компилирует только перечисленные файлы. "files": ["src/index.ts"]
//"files": [],
//? Types
// Определяет, какие файлы деклараций (.d.ts) TypeScript должен загружать.
// "vite/client" Это включает глобальные типы Vite, такие как: console.log(import.meta.env.VITE_API_URL);
// Можно подключить собственные .d.ts файлы: {"compilerOptions": {"types": ["vite/client", "./src/types/global"] } }
//! Загружает ТОЛЬКО указанные .d.ts файлы (например, vite/client).
"types": ["vite/client"]
// Определяет папки, где искать .d.ts файлы (например, node_modules/@types).
//! Если "types" задан, то "typeRoots" игнорируется.
//"typeRoots": []
//? Extends
// Позволяет наследовать настройки из другого файла.
//"extends": ""
}
```
No Comments