Widget Sliced Design

From the author

 

Hello, dear reader. My name is David Shekunts, and I am a Tech Lead with 12 years of experience.

WSD is one of the best discoveries of my programming career. It maps so naturally onto how frontend is structured that it fits almost any task.

I have been using this approach for about 7 years, and I have never had a case where it created problems or failed me.

Does this sound like magic / a silver bullet? I may be a fool, but damn it, I will say “yes.” Surprisingly, I have not yet found a case where this structure does not work.

And now, dear reader, I challenge you to a duel: find such a case, show it to me, and do the most important thing in human history — destroy the first and last silver bullet.

Example applications

Glossary

• Entity — a description of some data. There are 3 types:
• UI — data of a specific UI component: whether it is visible, what is written in an input, etc. This is often 80% of all code.
• Util — geometry (Point in space, Triangle), an external API (Stripe), and everything else predefined by the external world.
• Business — the state of business entities your application works with. Very often, it comes from the backend and later goes back into the backend database.

// Entities are described through some kind of typing, whether type, interface, or class

// Example of a UI Entity

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

// Example of a Util Entity: Triangle

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

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

// Example of a Util Entity: Stripe API

type StripeCreateInvoceRequest = {
	id: string
	total: number
}

type StripeCreateInvoceResponse = {
	success: boolean
	message: string
}

// Example of a Business Entity
type Product = {
	name: string
	price: number
	comments: Comment[]
}

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

• State — a particular combination of Entities in a particular Component at a specific moment in time.

// loginPopup is already State based on the LoginPopup UI entity
const loginPopup = useState<LoginPopup>({ ... })

// State of util code for a triangle
const pointOne = useState<Point>({ x: 10, y: 10 })
// ...
const triangle = useState<Triangle>({ one: pointOne, ... })

// State of the Cart business entity
const cart = useState<Cart>({ ... })

• Logic — a set of functions that do something with State. Usually there are 3 categories:
• UI — logic for the state of a specific UI component: whether it is visible, what is written in an input, etc. This is often 80% of all code.
• Util — for example, functions for converting centimeters to meters, calculating a hypotenuse through cosine, converting dollars to rubles, and everything else predefined by the external world: physics, laws, mathematics, etc.
• Business — functions that work with the Business Entities of your specific application (Put Product into Cart, Delete Comment). This often involves working with the backend.

// UI logic — works with interface state

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 logic — knows nothing about your application

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 logic — works with the application's business entities

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 — a UI component with any variant or combination of logic:

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>
  )
}

Splitting the application into 5 parts

1. pages — Components with State and Business Logic that are opened through some URL. You could also say: “a widget for a URL.”

2. widgets — Components with State and Business Logic that are reused across different pages.

3. apps — allow us to assemble different applications from different sets of pages, for example for different URLs, different roles, or different environments such as web and Electron.js.

4. libs — code as libraries that could just as well live in npm, but you have reasons to keep them locally.

Structuring rules

src/
├── apps/                  # application assembly points
│   └── shop/
│       └── index.tsx
│
├── pages/                 # pages bound to URLs
│   ├── home/
│   │   └── index.tsx
│   └── cart/
│       └── index.tsx
│
├── widgets/               # globally reusable widgets
│   ├── auth-widget/
│   │   └── index.tsx
│   └── cart-widget/
│       └── index.tsx
│
└── libs/                  # local libraries
    ├── ui-kit/
    │   └── index.ts
    ├── auth-sdk/
    │   └── index.ts
    └── math-fns/
        └── index.ts

# This may look complicated, but it becomes intuitive very quickly.
# Literally look at how folders are nested inside each other — look at the indentation,
# and everything becomes clear.

src/
├── apps/                         # not considered, because apps cannot be reused; this is the highest point of the entire hierarchy
│
├── libs-1/                       # level 0 (root)
│
├── widgets/
│   └── widget-1/                 # level 0 (root), parent of widget-2
│       ├── libs-2/               # level 1, child of widget-1
│       └── widget-2/             # level 1, child of widget-1
│
└── pages/
    └── page-1/                   # level 0 (root), parent of widget-3 and page-2
        ├── libs-3/               # level 1, child of page-1, sibling of page-2, cousin of widget-2 and libs-2
        ├── widget-3/             # level 1, child of page-1, sibling of page-2, cousin of widget-2 and libs-2
        └── pages/
            └── page-2/           # level 1, child of page-1, sibling of widget-3 and libs-3, cousin of widget-2 and libs-2, parent of widget-4
                └── widget-4/     # level 2, child of page-2

1. Level X is the folder of a specific widgets / pages / libs, and each nested folder increases X by 1.
1. Child — nested widgets / pages / libs.
2. Parent — the folder that contains the current one.
3. Sibling — folders located directly next to the current one.
4. Cousin — a folder located in another widgets / pages / libs branch at the same nesting level as the current one. The same rules apply to its descendants.

2. Root Level (level 0) is where the highest-level apps, pages, widgets, and libs live.

3. What can be placed where:
1. libs can be placed inside any folder.
2. widgets can be placed inside any folder, even inside other widgets.
3. pages can be placed only inside pages.
4. apps can exist only at the root level.

4. Reuse rules:
1. Nothing can reuse Cousins — if something is in a separate branch, you cannot touch it.
2. Everything may use parent, child, and sibling widgets.
3. Everything may use parent and sibling libs.
4. libs may not use anything except other libs from parent levels.
5. pages may use only pages nested inside them, not parent pages and not sibling pages.

Additional notes

1. In practice, a widget / page may consist of just an index.ts file that contains both Logic and UI.

2. If you have only 1 app, you can simply create index.ts in the root of src and avoid creating an apps folder.

3. If you want to create a widget that has no Component, then it should be created as a library in libs.

4. Do not create folders like widget / page if you do not use them.

Private namespace

src/
└── libs/
    └── @company/              # private project libraries
        ├── ui-kit/            # design system
        │   └── index.ts
        ├── backend-sdk/       # backend API client
        │   └── index.ts
        └── analytics-sdk/     # analytics client
            └── index.ts

Without Levels

# Put everything right here:

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

Additional

tests

src/
├── apps/
│   └── shop/
│       ├── index.tsx
│       └── tests.ts           # application assembly test
│
├── tests/
│   └── auth-flow.ts           # global e2e test
│
├── libs/
│   └── @company/
│       └── backend-sdk/
│           ├── index.ts
│           └── tests.ts       # SDK test
│
├── widgets/
│   └── auth-widget/
│       ├── index.tsx
│       └── tests.tsx          # widget test
│
└── pages/
    └── home/
        ├── index.tsx
        ├── tests.tsx          # page test
        ├── libs/
        │   └── home-api/
        │       └── index.ts
        └── widgets/
            └── cart-widget/
                ├── index.tsx
                └── tests.tsx  # local widget test

Final structure

src/
├── apps/
│   ├── shop/                          # shop application
│   │   └── index.tsx
│   └── admin-panel/                   # admin panel application
│       └── index.tsx
│
├── tests/
│   └── auth-flow.ts                   # global auth e2e test
│
├── libs/
│   ├── @company/
│   │   └── backend-sdk/               # backend API SDK
│   │       ├── index.ts
│   │       └── tests.ts
│   └── stripe/                        # local wrapper around Stripe
│       └── index.ts
│
├── widgets/
│   └── auth-widget/                   # global authentication widget
│       ├── index.tsx
│       └── tests.tsx
│
└── pages/
    └── home/                          # / page
        ├── index.tsx
        ├── tests.tsx
        ├── libs/
        │   └── home-api/
        │       └── index.ts
        ├── widgets/
        │   └── cart-widget/           # local cart widget
        │       ├── index.tsx
        │       └── tests.tsx
        └── pages/
            └── product/               # /product/:productId page
                ├── index.tsx
                └── widgets/
                    └── product-description/
                        └── index.tsx

Related concepts

• FALSe — an application structure that describes a similar approach, but for backend applications.

• Feature-Sliced Design — also tries to structure frontend by semantic layers and slices, but WSD is simpler: fewer terms, fewer levels, and less room for interpretation. I would not even recommend FSD, because everyone interprets it differently, and loose interpretations always prove that it is too complex and not truly “understandable.”

• Vertical Slice Architecture — the idea of keeping all code for one feature nearby: UI, state, logic, and tests. It is similar to the WSD rule: “move the folder — move the feature.”

• Colocation — the principle of keeping related code nearby: component, state, tests, styles, local utils.

• Locality of Behavior — logic should live near the place where it is actually used, not in some abstract global folder.

• Clean Architecture / Hexagonal Architecture — useful as an analogy for libs and business logic, but often too heavy for frontend.

• Package by Feature — structure by user/business capabilities rather than by technical file types.