Widget Sliced Design

От автора

Привет, дорогой читатель, меня зовут Давид Шекунц и я Tech Lead с 12-летним опытом.

WSD – это одно из лучших открытий в моей карьере программиста. Оно настолько логично повторяет то, как устроен фронтенд, что идеально ложится под любые задачи.

Я использую этот подход уже лет 7 и ни разу не было кейса, когда он создавал бы мне проблемы или подводил.

Звучит как магия / серебряная пуля? Буду глупцом, но черт возьми, скажу “да”, удивительно, но пока я не нашел кейса, где эта структура бы не работала.

И теперь, жорогой читатель, я вызываю тебя на дуэль: найди такой кейс, покажи мне его и сделай самое важное в истории человечества – уничтожь первую и последнюю серебряную пулю.

Примеры приложений

Словарь

• Entity (Сущность) – описание каких-то данных, бывает 3-х видов:
• UI (Интерфейсная) – конкретного UI компонента: виден ли, что написано в input, etc. (часто 80% всего кода)
• Util (Утилитарная) – геометрия (Точка в пространстве, Треугольник), внешний API (Stripe, ), то есть все то, что предопределено внешним для нас миром.
• Business (Бизнес) – состояние бизнес-сущностей, с которыми мы работает. Очень часто оно приходит к нам и попадает обратно в БД на backend.

// Enitity описываются через какую-то типизацию, будь то type, interface или class

// Пример, Интерфейсной Сущности

type LoginPopup = {
	closed: boolean
	collapsed: boolean
	loading: boolean
	error: string
}

// Пример, Утилитарной Сущности Треугольник

type Point = {
	x: number;
	y: number;
}

type Triangle = {
	one: Point;
	two: Point;
	three: Point;
}

// Пример, Утилитарной Сущности Stripe API

type StripeCreateInvoceRequest = {
	id: string
	total: number
}

type StripeCreateInvoceResponse = {
	success: boolean
	message: string
}

// Пример, Бизнес-сущности
type Product = {
	name: string
	price: number
	comments: Comment[]
}

type Cart = {
	products: Product[]
	totalSum: number
}

• State (Состояние) – та или иная комбинация Сущностей в том или ином Компоненте на конкретный момент времени.

// loginPopup – это уже Состояние на базе UI сущности LoginPopup
const loginPopup = useState<LoginPopup>({ ... })

// Состояние утилитарного кода треугольника
const pointOne = useState<Point>({ x: 10, y: 10 })
// ...
const triangle = useState<Triangle>({ one: pointOne, ... })

// Состояние бизнес-сущности Корзина
const cart = useState<Cart>({ ... })

• Логика – набор функций, которые что-то делают с Cостоянием, обычно выделяют 3 категории:
• UI (Интерфейсная) – состояние конкретного UI компонента: виден ли, что написано в input, etc. (часто 80% всего кода)
• Util (Утилитарная) – например, функции расчета см в м, или гипотенузы через косинус, или доллара в рубли, то есть все то, что предопределено внешним для нас миром (физикой, законами, математикой, etc.)
• Business (Бизнес) – это функции, которые работают с Бизнес-сущностями вашего конкретного приложения (Положить Товар в Корзину, Удалить Комментарий), часто подразумевает работу с backend

// UI-логика — работает с состоянием интерфейса

const openLoginPopup = (popup: LoginPopup): LoginPopup => ({
  ...popup,
  closed: false,
})

const closeLoginPopup = (popup: LoginPopup): LoginPopup => ({
  ...popup,
  closed: true,
  error: "",
})

const setLoginError = (
  popup: LoginPopup,
  error: string,
): LoginPopup => ({
  ...popup,
  error,
  loading: false,
})

// Util-логика — не знает ничего про ваше приложение

const getDistance = (a: Point, b: Point): number => {
  return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2)
}

const getTrianglePerimeter = (triangle: Triangle): number => {
  return (
    getDistance(triangle.one, triangle.two) +
    getDistance(triangle.two, triangle.three) +
    getDistance(triangle.three, triangle.one)
  )
}

// Business-логика — работает с бизнес-сущностями приложения

const getCartTotalSum = (cart: Cart): number => {
  return cart.products.reduce((sum, product) => {
    return sum + product.price
  }, 0)
}

const addProductToCart = (
  cart: Cart,
  product: Product,
): Cart => {
  const products = [...cart.products, product]

  return {
    ...cart,
    products,
    totalSum: getCartTotalSum({ ...cart, products }),
  }
}

const removeProductFromCart = (
  cart: Cart,
  productName: string,
): Cart => {
  const products = cart.products.filter(product => {
    return product.name !== productName
  })

  return {
    ...cart,
    products,
    totalSum: getCartTotalSum({ ...cart, products }),
  }
}

• Component (Компонента) – UI компонент с любыми из вариантов и комбинаций логик:

type CartWidgetProps = {
  user: User | null
  cart: Cart
  openAuthPopup: () => void
}

const CartWidget = ({
  user,
  cart,
  openAuthPopup,
}: CartWidgetProps) => {
  const [loading, setLoading] = useState(false)
  const [error, setError] = useState("")

  const pay = async () => {
    if (!user) {
      openAuthPopup()
      return
    }

    setLoading(true)
    setError("")

    const response = await createStripeInvoice({
      id: user.id,
      total: cart.totalSum,
    })

    setLoading(false)

    if (!response.success) {
      setError(response.message)
      return
    }

    window.location.href = response.paymentUrl
  }

  return (
    <div>
      <div>Products: {cart.products.length}</div>
      <div>Total: {cart.totalSum}</div>

      {error && <div>{error}</div>}

      <button disabled={loading} onClick={pay}>
        {loading ? "Loading..." : "Pay"}
      </button>
    </div>
  )
}

Делим приложение на 5 частей

1. pages – Компонента с Состоянием и Бизнес-логикой, которые открываются по какому-то URL (можно также сказать: “widget для URL”)

2. widgets – Компонента с Состоянием и Бизнес-логикой, которые переиспользуются на разных pages

3. apps – благодаря которым мы можем из разных наборов pages собирать разные приложения, например, под разные url, разные роли, разные env (например, веб и electron.js)

4. libs – код, как библиотеки, которые могли точно также лежать в npm, но у вас есть причины хранить их локально

Правила структурирования

src/
├── apps/                  # точки сборки приложений
│   └── shop/
│       └── index.tsx
│
├── pages/                 # страницы, привязанные к URL
│   ├── home/
│   │   └── index.tsx
│   └── cart/
│       └── index.tsx
│
├── widgets/               # глобальные переиспользуемые виджеты
│   ├── auth-widget/
│   │   └── index.tsx
│   └── cart-widget/
│       └── index.tsx
│
└── libs/                  # локальные библиотеки
    ├── ui-kit/
    │   └── index.ts
    ├── auth-sdk/
    │   └── index.ts
    └── math-fns/
        └── index.ts

# Может казаться сложным, но это быстро понимается интуитивно, буквально смотрите
# на вложенность папок друг в друга (вот прмя на табы и все становится понятно)

src/
├── apps/                         # не рассматриваем, потому что их переиспользовать нельзя, он – самая высокая точка всей иерархии
│
├── libs-1/                       # 0 уровень (корневой)
│
├── widgets/
│   └── widget-1/                 # 0 уровень (корневой), родитель widget-2
│       ├── libs-2/               # 1 уровень, потомок widget-1
│       └── widget-2/             # 1 уровень, потомок widget-1
│
└── pages/
    └── page-1/                   # 0 уровень (корневой), родитель widget-3, page-2
        ├── libs-3/               # 1 уровень, потомок page-1, родственник page-2, сородичь widget-2, libs-2
        ├── widget-3/             # 1 уровень, потомок page-1, родственник page-2, сородичь widget-2, libs-2
        └── pages/
            └── page-2/           # 1 уровень, потомок page-1, родственник widgets-3, libs-3, сородичь widget-2, libs-2, родитель widgets-4
                └── widget-4/     # 2 уровень, потомок page-2

1. Уровень Х – это папка конкретного widgets / pages / libs и каждая вложенная папка увеличивает значение Х
1. Потомок – вложенные widgets / pages / libs
2. Родитель – папка, в которую вложена текущая
3. Родственник – папки, которая находится прямо рядом
4. Сородич – папка, которая находится в других widgets / pages / libsна том же уровне вложенности, что и наш текущий (и сюда же пойдут все правила к его потомкам)

2. Корневой Уровень (уровень 0) – там, где лежат наши самые верхнеуровневые apps, pages, widgets, libs

3. Что во что можно класть
1. libs можно класть в любую из папок
2. widgets можно класть в любую из папок, даже в другие widgets
3. pages можно класть только в pages
4. apps могут быть только на корневом уровне

4. Правила переиспользования
1. Ничто не может переиспользовать Сородичей – если что-то находится в сторонней ветке, то его нельзя трогать
2. Все имеют право использовать widgets родителей, потомков и родственников
3. Все имеют право использовать libs родителей и родственников
4. libs не имеет право использовать никого, кроме других libs в родительских уровнях
5. pages имеют право использовать pages только вложенных в них, не Родительские и не Родственников

Дополнительно

1. По факту widget / page может состоять просто из index.ts файла, в котором будет и Логика, и UI

2. Если у вас всего 1 app, можете просто сделать index.ts в корне src и не создавать папку

3. Если хочется создать widget у которого не будет Компонента, значит, это надо создать библиотеку в libs

4. Не надо создать папки типа widget / page , если вы их не используете

Private namespace

src/
└── libs/
    └── @company/              # приватные библиотеки проекта
        ├── ui-kit/            # дизайн-система
        │   └── index.ts
        ├── backend-sdk/       # клиент backend API
        │   └── index.ts
        └── analytics-sdk/     # клиент аналитики
            └── index.ts

Без Уровней

# Вот все прям сюда:

src/
├── apps/
│   ├── app-1/
│   └── app-2/
│
├── pages/
│   ├── page-1/
│   └── page-2/
│
├── widgets/
│   ├── widget-1/
│   └── widget-2/
│
└── libs/
    ├── lib-1/
    └── lib-2/

Дополнительно

tests

src/
├── apps/
│   └── shop/
│       ├── index.tsx
│       └── tests.ts           # тест сборки приложения
│
├── tests/
│   └── auth-flow.ts           # глобальный e2e-тест
│
├── libs/
│   └── @company/
│       └── backend-sdk/
│           ├── index.ts
│           └── tests.ts       # тест SDK
│
├── widgets/
│   └── auth-widget/
│       ├── index.tsx
│       └── tests.tsx          # тест виджета
│
└── pages/
    └── home/
        ├── index.tsx
        ├── tests.tsx          # тест страницы
        ├── libs/
        │   └── home-api/
        │       └── index.ts
        └── widgets/
            └── cart-widget/
                ├── index.tsx
                └── tests.tsx  # тест локального виджета

Итоговая структура

src/
├── apps/
│   ├── shop/                          # приложение магазина
│   │   └── index.tsx
│   └── admin-panel/                   # приложение админки
│       └── index.tsx
│
├── tests/
│   └── auth-flow.ts                   # глобальный e2e-тест авторизации
│
├── libs/
│   ├── @company/
│   │   └── backend-sdk/               # SDK backend API
│   │       ├── index.ts
│   │       └── tests.ts
│   └── stripe/                        # локальная обёртка над Stripe
│       └── index.ts
│
├── widgets/
│   └── auth-widget/                   # глобальный виджет авторизации
│       ├── index.tsx
│       └── tests.tsx
│
└── pages/
    └── home/                          # страница /
        ├── index.tsx
        ├── tests.tsx
        ├── libs/
        │   └── home-api/
        │       └── index.ts
        ├── widgets/
        │   └── cart-widget/           # локальный виджет корзины
        │       ├── index.tsx
        │       └── tests.tsx
        └── pages/
            └── product/               # страница /product/:productId
                ├── index.tsx
                └── widgets/
                    └── product-description/
                        └── index.tsx

Похожие концепции

• FALSe – структура приложений, которая описывает подобный подход, но для backend приложений.

• Feature-Sliced Design — тоже пытается структурировать frontend по смысловым слоям и слайсам, но WSD проще: меньше терминов, меньше уровней, меньше пространства для трактовок – но FSD я даже не посоветую, поскольку его каждый трактует по-разному, а вольные трактовки всегда доказывают, что он чересчурно сложный и не “понятный”.

• Vertical Slice Architecture — идея держать весь код одной функции рядом: UI, состояние, логику, тесты. Похоже на правило WSD: “переносишь папку — переносишь функцию”.

• Colocation — принцип “держать связанный код рядом”: компонент, состояние, тесты, стили, локальные utils.

• Locality of Behavior — логика должна лежать рядом с местом, где она реально используется, а не в абстрактной глобальной папке.

• Clean Architecture / Hexagonal Architecture — полезны как аналогия для libs/business-логики, но для frontend часто слишком тяжелые.

• Package by Feature — структура не по техническим типам файлов, а по пользовательским/бизнес-возможностям.