Что такое параметры маршрутов (route parameters) и группы маршрутов (route groups) в SvelteKit?

Параметры маршрутов и группы маршрутов в SvelteKit

Параметры маршрутов (Route Parameters)

Динамические сегменты URL задаются квадратными скобками в имени папки или файла. SvelteKit автоматически извлекает значения и передаёт их в params внутри load функций.

Базовые параметры

src/routes/
  users/
    [id]/
      +page.svelte         # /users/123
      +page.server.ts      # params.id = '123'
  blog/
    [slug]/
      +page.svelte         # /blog/my-article

// src/routes/users/[id]/+page.server.ts
import type { PageServerLoad } from './$types';
import { error } from '@sveltejs/kit';

export const load: PageServerLoad = async ({ params }) => {
  const user = await db.users.findById(params.id);
  if (!user) throw error(404);
  return { user };
};

Несколько параметров

src/routes/
  shops/[shopId]/products/[productId]/
    +page.server.ts    # params = { shopId: '5', productId: 'abc' }

REST параметры (rest parameters)

Двойные квадратные скобки [...path] захватывают оставшийся путь как строку:

src/routes/
  files/
    [...path]/
      +page.svelte    # /files/a/b/c → params.path = 'a/b/c'

Матчеры (Parameter Matchers)

Ограничивают формат параметра — например, только числа. Создаются в src/params/:

// src/params/integer.ts
import type { ParamMatcher } from '@sveltejs/kit';

export const match: ParamMatcher = (param) => {
  return /^\d+$/.test(param);
};

# Использование: [id=integer] — совпадает только если id — число
src/routes/posts/[id=integer]/+page.svelte

Опциональные параметры

src/routes/
  [[lang]]/
    about/
      +page.svelte    # /about И /en/about

Группы маршрутов (Route Groups)

Папки в круглых скобках (group) создают логическую группировку маршрутов без добавления сегмента в URL. Главное применение — разные layouts для разных секций без влияния на адрес.

src/routes/
  (app)/
    +layout.svelte           # Layout с sidebar для аутентифицированных
    +layout.server.ts        # Проверка авторизации для всей группы
    dashboard/
      +page.svelte           # URL: /dashboard (не /(app)/dashboard)
    settings/
      +page.svelte           # URL: /settings
  (marketing)/
    +layout.svelte           # Простой layout без sidebar
    +page.svelte             # URL: / — главная страница
    about/
      +page.svelte           # URL: /about

Практический пример: защищённая зона

// src/routes/(app)/+layout.server.ts
import { redirect } from '@sveltejs/kit';
import type { LayoutServerLoad } from './$types';

export const load: LayoutServerLoad = ({ locals }) => {
  if (!locals.user) {
    throw redirect(303, '/login');
  }
  return { user: locals.user };
};

Группы без shared layout

Если в группе нет +layout.svelte, она используется только для организации файлов — URL не меняется, но маршруты изолированы от layout родительской папки:

src/routes/
  (auth)/                 # Нет +layout.svelte
    login/
      +page.svelte        # URL: /login, inherits от корневого layout
    register/
      +page.svelte        # URL: /register

Подводные камни

• Матчеры в src/params/ должны экспортировать именно функцию match, иначе SvelteKit молча игнорирует файл.
• REST параметр [...path] захватывает весь остаток URL включая слэши — это может конфликтовать с более специфичными маршрутами; порядок разрешения идёт от наиболее специфичного к наименее.
• Несколько групп с одинаковым URL-адресом вызовут конфликт маршрутов и ошибку сборки — имена групп в скобках не влияют на URL, поэтому (a)/about и (b)/about — один маршрут.
• Опциональные параметры [[param]] нельзя размещать рядом с обычными параметрами в одном сегменте — [[lang]]-posts не поддерживается.
• Группы маршрутов не влияют на $page.route.id — он включает скобки в пути, что нужно учитывать при сопоставлении в тестах.
• Layout внутри группы не наследуется дочерними маршрутами из других групп того же уровня — изоляция полная.
• При использовании матчера с REST параметром ([...path=type]) матчер должен принимать строку с слэшами — учтите это в регулярном выражении.

• Путать route parameters and groups с похожим API из соседнего фреймворка.
• Не объяснять, где код выполняется: сервер, клиент, build step или runtime.
• Игнорировать влияние на hydration, cache, bundle size или безопасность.

• Точно объясняет назначение механизма «route parameters and groups».
• Показывает корректный минимальный пример без выдуманных API.
• Называет ограничения, failure modes и production-компромиссы.