[июль 2025] Настройка проекта AstroJS: VS Code, Prettier, ESlint, Stylelint, PostCSS, минификация файлов / Хабр

Changelog находится в конце статьи. Последнее обновление - 13 июля 2025.

Собрала все файлы в репозиторий: https://github.com/teinett/astro-dot-files/

Настраиваем Visual Studio Code для работы с AstroJS

Устанавливаем плагины VS Code:

официальный Astro для распознавания файлов .astro;

Создаем проект

AstroJS 5.x работает на Node 18.20.8 и старше. Я уже везде использую Node 22.

1. Устанавливаем AstroJS

npm create astro@latest

После установки проверяем - запускаем локально:

npm run dev

Если проект запустился, то можем его посмотреть в браузере: http://localhost:4321.

Останавливаем проект: CTRL + C.

2. Отключаем телеметрию

npm run astro telemetry disable

официальная инструкция

Настраиваем проект

1. Настраиваем Typescript - добавляем пути для файлов

Начиная с AstroJS 4.x поддерживает Typescript 5.х.

Редактируем файл tsconfig.json:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

2. Настраиваем EditorConfig

Создаем в корне проекта файл .editorconfig:

root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
charset = utf-8

[{*.json,*.yml}]
indent_size = 2

[*.yaml]
indent_style = space

[*.md]
trim_trailing_whitespace = false

Настраиваем автоматическую проверку на соблюдение правил редактора.

Внимание! Может не работать при каких-то особых настройках окружения: начинает проверять файлы в папке node_modules. Если вы с таким сталкиваетесь, пропускайте этот шаг.

Устанавливаем линтер:

npm install --save-dev editorconfig-checker

Добавляем в файл package.json команду для проверки EditorConfig:

…
"scripts": {
…
    "lint:editorconfig": "editorconfig-checker --exclude node_modules",
…
  },
…

Проверяем, работает ли:

npm run lint:editorconfig

3. Настраиваем версию node

Вариант 1. Создаем в корне проекта файл .nvmrc:

Вариант 2. В файл package.json добавляем код:

…
"engines": {
    "node": "22"
  },
…

4. Настраиваем Browserlist

Создаем в корне проекта файл .browserlistrc:

defaults
last 2 version
not dead

5. Добавляем проверку типов от AstroJS

Добавляем в файл package.json команду для линтера:

…
"scripts": {
…
    "check": "astro check",
…
  },
…

Проверяем работу линтера:

npm run check

6. Добавляем Prettier для AstroJS и Tailwind CSS

npm install --save-dev prettier prettier-plugin-astro

Создаем в корне проекта файл .prettierignore - исключаем форматирование указанных файлов и папок:

# Ignore artifacts:
dist
.astro

# Standard
**/.git
**/.svn
**/.hg
**/node_modules

# lockfiles
pnpm-lock.yaml
yarn.lock
package-lock.json

Создаем в корне проекта файл .prettierrc.mjs с настройками для Prettier:

/** @type {import("prettier").Config} */
export default {
    plugins: ["prettier-plugin-astro"],
    overrides: [
        {
            files: "*.astro",
            options: {
                parser: "astro",
            },
        },
    ],
};

7. Добавляем ESLint - линтер для JavaScript и JSX

npm install --save-dev eslint eslint-plugin-astro eslint-plugin-prettier eslint-plugin-jsx-a11y @eslint/js globals typescript-eslint

Создаем в корне проект файл eslint.config.mjs:

import { defineConfig } from "eslint/config";
import globals from "globals";
import js from "@eslint/js";
import tseslint from "typescript-eslint";
import astro from "eslint-plugin-astro";
import prettier from "eslint-plugin-prettier";

// parsers
const tsParser = tseslint.parser;
const astroParser = astro.parser;

export default defineConfig([
  // Global configuration
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
      },
    },
  },

  // Base configs
  js.configs.recommended,
  tseslint.configs.recommended,

  // Prettier config
  {
    plugins: {
      prettier: prettier,
    },
    rules: {
      // disable warnings, since prettier should format on save
      "prettier/prettier": "off",
    },
  },

  // astro setup with a11y
  astro.configs.recommended,
  astro.configs["jsx-a11y-recommended"],
  {
    files: ["**/*.astro"],
    languageOptions: {
      parser: astroParser,
      parserOptions: {
        parser: tsParser,
        extraFileExtensions: [".astro"],
        sourceType: "module",
        ecmaVersion: "latest",
        project: "./tsconfig.json",
      },
    },
    rules: {
      "no-undef": "off", // Disable "not defined" errors for specific Astro types that are globally available (ImageMetadata)
      "@typescript-eslint/no-explicit-any": "off", // you may want this as it can get annoying
    },
  },

  // Ignore patterns
  {
    ignores: ["dist/**", "**/*.d.ts", ".github/"],
  },
]);

Добавляем в файл package.json команду для линтера:

…
"scripts": {
…
"lint:js": "eslint \"src/**/*.{js,ts,astro}\" --fix || true",
…
  },
…

У меня сейчас в проекте нет файлов *.js, поэтому линтер выпадает с ошибкой. Чтобы работа линтер завершилась корректно даже в этом случае, добавлено || true в конец команды проверки.

Проверяем работу линтера:

npm run lint:js

8. Добавляем Stylelint - линтер для CSS

Устанавливаем Stylelint и его конфиги:

npm install --save-dev stylelint stylelint-config-html stylelint-config-standard postcss-html

Официальная инструкция

Дополнительно можно установить плагин stylelint-order для упорядочивания селекторов:

npm install --save-dev stylelint-order

Пример, зачем это нужно из статьи Яндекса 2014 года с описанием их инструмента. Сейчас задача решается плагином.

Используем конфиг stylelint-config-html - он позволяет парсить файлы HTML, XML, Vue, Svelte, Astro.

Создаем в корне проекта файл .stylelintrc.yml:

extends:
  - stylelint-config-standard
  - stylelint-config-html
plugins:
  - stylelint-order
rules:
  order/properties-order:
    …

Пример правил для упорядочивания селекторов: Pepelsbey.dev

Добавляем в файл package.json команду для линтера c автоисправлением ошибок, где это возможно:

…
"scripts": {
…
    "lint:css": "stylelint \"src/**/*.{css,astro}\" --fix",
…
  },
…

Проверяем работу линтера:

npm run lint:css

9. Настройка VSCode для ESlint, Stylelint и Prettier

В корне проекта создаем папку .vscode и файлы:

.vscode/extensions.json - возможно, уже создан автоматически:

{
  "recommendations": ["astro-build.astro-vscode"],
  "unwantedRecommendations": []
}

.vscode/launch.json - возможно, уже создан автоматически:

{
  "version": "0.2.0",
  "configurations": [
    {
      "command": "./node_modules/.bin/astro dev",
      "name": "Development server",
      "request": "launch",
      "type": "node-terminal"
    }
  ]
}

.vscode/settings.json:

{
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "astro", // Enable .astro
    "typescript", // Enable .ts
    "typescriptreact" // Enable .tsx
  ],
  "stylelint.validate": [
    "css",
    // ↓ Add "html" language.
    "html",
    // ↓ Add "vue" language.
    "vue",
    // ↓ Add "svelte" language.
    "svelte",
    // ↓ Add "astro" language.
    "astro"
  ],
  "prettier.documentSelectors": ["**/*.astro"],
  "[astro]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

10. Настройка общей команды тестов для ESlint и Stylelint

Добавляем в файл package.json команду для проверки всеми линтерами:

…
"scripts": {
…
    "test": "npm run lint:css && npm run lint:js && npm run check",
…
  },
…

Если запускается editorconfig-checker, то общая команда для тестов:

…
"scripts": {
…
    "test": "npm run lint:editorconfig && npm run lint:css && npm run lint:js && npm run check",
…
  },
…

Проверяем команду:

npm run test

11. Настройка PostCSS

Официальная инструкция.

AstroJS основан на Vite, и PostCSS уже включен по умолчанию.

Мы уже создали конфиг Browserlist - этот конфиг будет использовать PostCSS для понимания поддерживаемых браузеров.

Установим плагины:

Autoprefixer
PostCSS Preset Env
CSSnano

npm install --save-dev autoprefixer postcss-preset-env cssnano

Создадим конфиг для PostCSS - файл postcss.config.js в корне сайта:

import autoprefixer from 'autoprefixer';
import postcssPresetEnv from 'postcss-preset-env';
import cssnano from 'cssnano';

const settings = {
    plugins: [
        autoprefixer(),
        postcssPresetEnv({ stage: 1 }),
        cssnano({ preset: 'default' }),
    ],
};

export default settings;

12. Удаляем неиспользованные стили

Пакет: astro-purgecss

Он сработает на этапе build процесса.

Устанавливаем пакет:

npx astro add astro-purgecss

Настройки в astro.config.mjs:

import { defineConfig } from "astro/config";
import purgecss from "astro-purgecss";


export default defineConfig({
// ...
integrations: [
        purgecss({
            variables: true,

            // for Astro view transitions
            keyframes: false,

            // for Astro view transitions
            safelist: {
                greedy: [
                    /*astro*/
                ],
            },

            // for SSR
            content: [
                process.cwd() + "/src/**/*.{astro,vue,jsx,tsx,css}", // Watching astro and vue sources
            ],
        }),
        ...
    ],
});

13. Минификация файлов

Минифицируем сгенерированные во время build процесса файлы.

Установим пакет astro-compress:

npm install --save-dev @playform/compress.

Добавим конфигурацию в файл astro.config.mjs:

import { defineConfig } from "astro/config";
import Compress from "@playform/compress";

export default defineConfig({
    integrations: [
         ...
        Compress({
            // CSS: false,
            // HTML: false,
            Image: false,
            // JavaScript: false,
            SVG: false,
        }), // should be last in the list
    ],
});

NOTE! Compress() должен идти последним в списке всех интеграций.

В настройках Compress() можно указать, какие типы файлов не минифицировать (выключить работу плагинов по минификации полностью). В коде выше я буду минифицировать CSS, HTML и JS, а картинки трогать не буду.

Заключение

Мы подготовили проект AstroJS к активной разработке.

Если планируется работа с git-репозиторием, то рекомендую добавить husky и инструкции для тестирования перед заливкой кода в git.

Структура проекта:

/
├── .vscode/
│   ├── extensions.json
│   ├── launch.json
│   └── settings.json
├── node_modules/
│   └── папки и файлы
├── public/
│   └── папки и файлы
├── src/
│   └── папки и файлы
├── .browserlistrc
├── .editorconfig
├── .gitignore
├── .nvmrc
├── .prettierignore
├── .prettierrc.mjs
├── .stylelintrc.yml
├── astro.config.mjs
├── eslint.config.mjs
├── package-lock.json
├── package.json
├── postcss.config.js
├── README.md
└── tsconfig.json

Changelog статьи

UPDATE 13 июля 2025. Обновление команд с актуальными пакетами.

UPDATE 26 октября 2024. Обновила инфу про eslint в связи с выходом новой мажорной версии. Удалила всё про TailwindCSS, т.к. инструкция уже нерабочая.

UPDATE 21 апреля 2024. Добавила пакет astro-purgecss для удаления неиспользованных стилей.

UPDATE 18 апреля 2024. Пакет astro-compress стал @playform/compress

UPDATE 27 декабря 2023. Исправила settings.json для vscode: теперь он работает с Prettier для .astro файлов корректно.

UPDATE 17 декабря 2023. Добавила инфу про минификацию файлов html, js, css.

UPDATE 14 ноября 2023. Добавлен конфиг Stylelint для TailwindCSS.

UPDATE 1 сентября 2023. Обновлено для AstroJS 3.x.

UPDATE 21 августа 2023. Исправлен конфиг для Prettier, команда для запуска Stylelint (ранее проверяла все папки, а не только src), добавлена инфа про PostCSS