2. Установка и структура проекта

Начать работу с Astro очень просто — фреймворк поставляется с интерактивным мастером установки, который проведёт вас через все шаги. В этом модуле мы разберём, как создать проект, изучим его структуру и настроим окружение для разработки.

Создание проекта

Для создания нового Astro-проекта используйте команду create astro:

# С помощью npm
npm create astro@latest

# С помощью pnpm (рекомендуется)
pnpm create astro@latest

# С помощью yarn
yarn create astro

Мастер установки задаст несколько вопросов:

 astro   Launch sequence initiated.

   dir   Where should we create your new project?
         → ./my-astro-site

  tmpl   How would you like to start your new project?
         ● A few best practices (recommended)

    ts   Do you plan to write TypeScript?
         ● Yes

   use   How strict should TypeScript be?
         ● Strict (recommended)

  deps   Install dependencies?
         ● Yes

   git   Initialize a new git repository?
         ● Yes

      ✔  Project initialized!
         ■ Template copied
         ■ TypeScript customized
         ■ Dependencies installed
         ■ Git initialized

После этого перейдите в папку проекта и запустите сервер разработки:

cd my-astro-site
npm run dev

Сервер запустится на http://localhost:4321 — Astro использует порт 4321 (отсылка к Звёздным войнам — “4, 3, 2, 1… Пуск!”).

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

Стандартный Astro-проект имеет следующую структуру:

my-astro-site/
├── public/                 # Статические файлы (без обработки)
│   ├── favicon.svg
│   └── robots.txt
├── src/                    # Весь исходный код
│   ├── components/         # Переиспользуемые компоненты
│   │   └── Card.astro
│   ├── layouts/            # Макеты страниц
│   │   └── Layout.astro
│   ├── pages/              # Страницы = URL-маршруты
│   │   └── index.astro
│   └── content/            # Content Collections (Markdown, MDX)
│       └── blog/
├── astro.config.mjs        # Конфигурация Astro
├── tsconfig.json           # Конфигурация TypeScript
└── package.json            # Зависимости и скрипты

Папка src/

Это сердце вашего проекта. Astro обрабатывает всё что находится внутри src/:

• pages/ — каждый файл здесь становится URL-маршрутом
• components/ — переиспользуемые .astro компоненты
• layouts/ — макеты для страниц
• content/ — Content Collections с типизацией

Папка public/

Файлы в public/ копируются в корень сборки без какой-либо обработки. Используйте её для:

• favicon.ico, robots.txt, sitemap.xml
• Изображений, которые не нужно оптимизировать
• Шрифтов и других статических ресурсов

Файл astro.config.mjs

Главный конфигурационный файл Astro:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  // Базовый URL сайта
  site: 'https://my-site.com',

  // Интеграции с другими фреймворками и инструментами
  integrations: [
    react(),
    tailwind(),
  ],

  // Режим рендеринга: 'static' (по умолчанию) или 'server'
  output: 'static',

  // Настройки сборки
  build: {
    assets: 'assets',
  },
});

Файл tsconfig.json

Astro настраивает TypeScript “из коробки”. Рекомендуемый конфиг:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@layouts/*": ["src/layouts/*"],
      "@assets/*": ["src/assets/*"]
    }
  }
}

Астро поддерживает три уровня строгости TypeScript: base, strict и strictest.

Добавление интеграций

Astro имеет богатую экосистему интеграций. Добавить их можно командой:

# Добавить React
npx astro add react

# Добавить Tailwind CSS
npx astro add tailwind

# Добавить Vue
npx astro add vue

# Добавить несколько сразу
npx astro add react tailwind sitemap

Команда astro add автоматически:

1. Устанавливает необходимые npm-пакеты
2. Обновляет astro.config.mjs
3. Создаёт необходимые конфигурационные файлы

Скрипты в package.json

{
  "scripts": {
    "dev": "astro dev",        // Запуск dev-сервера
    "build": "astro build",    // Сборка для production
    "preview": "astro preview", // Предпросмотр production-сборки
    "astro": "astro"           // CLI команды
  }
}

Переменные окружения

Astro имеет встроенную поддержку .env файлов:

.env

PUBLIC_API_URL=https://api.example.com  # Доступна на клиенте
SECRET_TOKEN=abc123                     # Только сервер

В коде:

---
// Серверная переменная (только в frontmatter)
const token = import.meta.env.SECRET_TOKEN;

// Публичная переменная (доступна везде)
const apiUrl = import.meta.env.PUBLIC_API_URL;
---

Интерактивный обозреватель структуры проекта

Кликайте по файлам и папкам, чтобы узнать их назначение: