Установка и настройка окружения

Fresh — фреймворк для создания веб-приложений на JavaScript и TypeScript, ориентированный на Deno и использующий архитектуру islands. Установка и настройка окружения для Fresh принципиально отличаются от привычных процессов в экосистеме Node.js, поэтому требуют отдельного и подробного разбора.

Fresh работает исключительно на Deno, поэтому наличие Node.js, npm, yarn или pnpm не требуется и не используется.

Минимальные требования:

  • операционная система: Windows, macOS или Linux
  • установленный Deno версии 1.31+
  • доступ к интернету (для загрузки модулей по URL)

Fresh использует стандартные возможности Deno:

  • встроенный TypeScript
  • URL-импорты
  • встроенный сервер
  • систему разрешений

Установка Deno

Windows

Рекомендуемый способ — PowerShell:

irm https://deno.land/install.ps1 | iex

После установки необходимо убедиться, что путь к Deno добавлен в PATH.

Проверка:

deno --version

macOS и Linux

Через shell-скрипт:

curl -fsSL https://deno.land/install.sh | sh

Или через Homebrew (macOS):

brew install deno

Проверка:

deno --version

Особенности среды Deno

Отсутствие package.json

Fresh не использует:

  • package.json
  • node_modules
  • lock-файлы npm

Все зависимости подключаются напрямую по URL и кэшируются Deno автоматически.

Система разрешений

Deno по умолчанию запускается в изолированной среде. Для работы Fresh требуются разрешения:

  • --allow-net — для HTTP-сервера
  • --allow-read — для чтения файлов проекта
  • --allow-env — для работы с переменными окружения (опционально)

Fresh-шаблоны уже учитывают это при запуске.

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

Использование официального инициализатора

Fresh устанавливается без глобальной установки.

Команда создания проекта:

deno run -A -r https://fresh.deno.dev my-project

Параметры:

  • -A — все разрешения (упрощает начальную настройку)
  • -r — автоматическая перезагрузка при изменении файлов
  • my-project — имя каталога проекта

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

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

my-project/
├── components/
├── islands/
├── routes/
├── static/
├── main.ts
├── fresh.gen.ts
├── deno.json

Ключевые элементы

main.ts

Точка входа приложения. Здесь запускается сервер Fresh и подключаются middleware.

routes/

Файловая маршрутизация:

  • каждый файл — отдельный HTTP-маршрут
  • поддержка параметров ([id].tsx)
  • поддержка API-эндпоинтов

islands/

Компоненты с клиентской логикой:

  • гидратируются только при необходимости
  • используют Preact
  • минимальный JavaScript на клиенте

components/

Обычные серверные компоненты без клиентского JS.

static/

Статические файлы:

  • изображения
  • шрифты
  • CSS
  • favicon

Конфигурация проекта

deno.json

Файл конфигурации Deno и Fresh.

Пример:

{
  "tasks": {
    "start": "deno run -A --watch=static/,routes/ main.ts"
  },
  "imports": {
    "$fresh/": "https://deno.land/x/fresh@1.6.5/"
  }
}

Назначение:

  • описание задач (deno task)
  • алиасы импортов
  • настройки форматирования и линтинга

Запуск сервера разработки

Из каталога проекта:

deno task start

По умолчанию сервер доступен по адресу:

http://localhost:8000

Возможности dev-режима:

  • hot reload
  • автоматическая пересборка маршрутов
  • обновление fresh.gen.ts

Генерация fresh.gen.ts

Файл fresh.gen.ts создаётся автоматически и содержит:

  • список маршрутов
  • регистрацию islands
  • оптимизированную схему загрузки

Редактировать файл вручную не требуется. Он обновляется при изменении структуры routes/ и islands/.

Работа с переменными окружения

Fresh использует стандартный API Deno:

Deno.env.get("API_KEY");

Запуск с переменными окружения:

API_KEY=123 deno task start

Для Windows (PowerShell):

$env:API_KEY="123"
deno task start

Проверка корректности установки

Признаки корректно настроенного окружения:

  • сервер запускается без ошибок
  • страницы открываются в браузере
  • изменения в файлах сразу отражаются
  • отсутствует каталог node_modules

Отличия от Node.js-фреймворков

Ключевые особенности окружения Fresh:

  • единый runtime без внешних менеджеров пакетов
  • нативный TypeScript без сборки
  • минимальный JavaScript на клиенте
  • отсутствие шага npm install
  • контроль безопасности через разрешения

Эти отличия напрямую влияют на процесс разработки и делают настройку окружения более прозрачной и предсказуемой.

Оглавление