A React Component Should Be a Contract, Not Just a .tsx File

In many React projects, components start simple.

One file. A few props. Some JSX. Maybe a test later.

Then the project grows.

Types move somewhere else. Styles become harder to trace. Storybook examples drift away from real usage. Tests are either missing or only cover snapshots. Documentation exists “somewhere”, but not near the component itself.

At some point, using a component requires reading its implementation.

That is usually a sign that the component boundary is not clear enough.

I wrote a new article about what I call Calm Component Structure — a component folder convention where every component becomes a small local contract.

The idea is simple:

component-name/
  README.md
  types.ts
  index.ts
  component-name.tsx
  component-name.test.tsx
  index.test.ts
  component-name.module.scss
  component-name.stories.tsx
  doc.mdx

Yes, it is more files.

But each file has exactly one job.

The README explains how to use the component. The types define the public contract. The implementation stays focused. The styles are local. The tests protect behavior and exports. Storybook gives a playground. MDX connects documentation and examples.

The result is a component that is easier to understand, easier to reuse, easier to test, and easier for AI tools to work with.

This is especially important for reusable UI packages, design system primitives, micro frontends, and CLI-generated project presets.

The component is not just code.

It is a contract.

Read the full article here:

https://vyriy.dev/blog/calm-component-structure/