Структура проекта и организация файлов

Использование Carbon Components Svelte требует соблюдения определённой структуры проекта для поддержания чистоты кода, удобства масштабирования и совместимости с экосистемой Svelte. Важно понимать, как организовать файлы, компоненты и стили, чтобы проект оставался поддерживаемым.

Основные директории проекта

Стандартная структура проекта на Svelte с интеграцией Carbon Components может выглядеть следующим образом:

my-svelte-app/
├─ public/
│  ├─ global.css
│  └─ favicon.png
├─ src/
│  ├─ components/
│  │  ├─ Button.svelte
│  │  ├─ Modal.svelte
│  │  └─ FormInput.svelte
│  ├─ routes/
│  │  ├─ Home.svelte
│  │  ├─ About.svelte
│  │  └─ Contact.svelte
│  ├─ stores/
│  │  └─ userStore.js
│  ├─ App.svelte
│  └─ main.js
├─ package.json
├─ svelte.config.js
└─ tailwind.config.js (при использовании Tailwind)

Описание ключевых папок:

  • public/ — содержит статические ресурсы, доступные напрямую через URL. Обычно сюда помещают глобальные стили, изображения и фавиконы.
  • src/components/ — директория для переиспользуемых компонентов. Каждый компонент Svelte, особенно на базе Carbon, хранится в отдельном файле. Название файлов обычно совпадает с названием компонента.
  • src/routes/ — содержит страницы приложения. В случае использования SvelteKit каждая страница соответствует маршруту.
  • src/stores/ — хранит глобальные состояния приложения через writable или readable из Svelte.

Организация компонентов

Каждый компонент Carbon Components Svelte имеет структурное разделение:

  1. Импорт необходимых элементов Carbon:
<script>
  import { Button, Modal } from 'carbon-components-svelte';
  let modalOpen = false;
</script>
  1. HTML-разметка с компонентами Carbon:
<Button kind="primary" on:click={() => modalOpen = true}>
  Открыть модальное окно
</Button>

<Modal bind:open={modalOpen} modalLabel="Пример">
  <p>Содержимое модального окна</p>
</Modal>
  1. Стилизация и переопределение переменных:

Carbon использует CSS-переменные и SCSS-подход. Для локальной стилизации компонентов можно использовать <style> внутри .svelte файла:

<style>
  :global(.bx--btn--primary) {
    background-color: #0f62fe;
  }
</style>

Разделение логики и UI

Рекомендуется держать логику приложения отдельно от компонентов Carbon, чтобы обеспечить чистоту компонентов:

  • Компоненты отвечают за отображение и поведение UI.
  • Stores и вспомогательные функции (utils) отвечают за состояние и обработку данных.

Пример структуры:

src/
├─ components/
│  └─ UserForm.svelte
├─ stores/
│  └─ userStore.js
└─ utils/
   └─ validation.js

UserForm.svelte использует store для управления состоянием формы:

<script>
  import { userStore } from '../stores/userStore.js';
  import { TextInput, Button } from 'carbon-components-svelte';
  let username = '';
  
  function submitForm() {
    userStore.addUser({ username });
    username = '';
  }
</script>

<TextInput bind:value={username} labelText="Имя пользователя" />
<Button on:click={submitForm}>Добавить пользователя</Button>

Стандарты именования и вложенности

  • Компоненты — PascalCase (Button.svelte, ModalWindow.svelte).
  • Stores и утилиты — camelCase (userStore.js, validation.js).
  • Папки разделяются по типу или домену (components, routes, stores, utils).
  • Для крупных проектов рекомендуется создавать поддиректории внутри components для модульного деления, например:
components/
├─ Buttons/
│  ├─ PrimaryButton.svelte
│  └─ SecondaryButton.svelte
├─ Forms/
│  ├─ UserForm.svelte
│  └─ LoginForm.svelte

Интеграция глобальных стилей

Carbon Components Svelte требует импорта базовых стилей Carbon. Обычно это делается в main.js или App.svelte:

import 'carbon-components-svelte/css/all.css';

Если проект использует SCSS или Tailwind, можно подключать их в глобальном файле global.css или app.scss, сохраняя совместимость с Carbon.

Практические рекомендации

  • Каждый компонент Carbon лучше хранить в отдельном .svelte файле.
  • Логику состояния и обработку данных держать в stores и utils.
  • Глобальные стили и переменные импортировать в начале проекта.
  • Для масштабируемости использовать вложенные директории в components по функциональным блокам.
  • Использовать строгие соглашения именования, чтобы облегчить поиск и поддержку кода.

Эта структура позволяет масштабировать проект, обеспечивать повторное использование компонентов, чистоту кода и быстро адаптироваться к изменениям требований при работе с Carbon Components Svelte.

Оглавление