DEV Community

A0mineTV
A0mineTV

Posted on

A Minimal Yet Scalable React + TypeScript + styled-components Architecture

#react #typescript #styledcomponents #webdev

TL;DR — We’ll stand up a tiny project that still scales: a single, strongly-typed theme, colocated global styles, tiny reusable components, and pages that stay blissfully unaware of CSS. Grab the code, paste it into a fresh Vite/CRA repo, and you’re off to the races.

1 · Project layout 

my-app/
├── package.json
├── tsconfig.json
├── public/
│   └── index.html
└── src/
    ├── index.tsx          ← React entry point
    ├── App.tsx            ← root layout + providers
    ├── styles/
    │   ├── theme.ts       ← palette, spacing helpers, etc.
    │   ├── GlobalStyles.ts← reset + global styles
    │   └── styled.d.ts    ← module augmentation for typed theme
    ├── components/
    │   ├── Button.tsx
    │   └── Card.tsx
    └── pages/
        └── Home.tsx
Enter fullscreen mode Exit fullscreen mode

This folder-per-concern approach keeps your design system (styles + components) separate from features (pages). Swap in feature-first folders later without touching the underlying building blocks.

2 · The theme (src/styles/theme.ts) 

import { DefaultTheme } from "styled-components";

export const theme: DefaultTheme = {
  colors: {
    primary: "#1e88e5",
    secondary: "#ff7043",
    background: "#f5f7fa",
    text: "#1a1a1a",
  },
  spacing: (factor: number) => `${0.25 * factor}rem`,
};
Enter fullscreen mode Exit fullscreen mode

A single source of design truth. Bump the primary color or spacing scale once, every component updates instantly.

3 · Type augmentation (src/styles/styled.d.ts) 

import "styled-components";

declare module "styled-components" {
  export interface DefaultTheme {
    colors: {
      primary: string;
      secondary: string;
      background: string;
      text: string;
    };
    spacing: (factor: number) => string;
  }
}
Enter fullscreen mode Exit fullscreen mode

styled-components now autocompletes your palette and spacing helpers in every file—no more magic strings.

4 · Global styles (src/styles/GlobalStyles.ts) 

import { createGlobalStyle } from "styled-components";

export const GlobalStyles = createGlobalStyle`
  *, *::before, *::after { box-sizing: border-box; }
  body {
    margin: 0;
    font-family: system-ui, sans-serif;
    background: ${({ theme }) => theme.colors.background};
    color: ${({ theme }) => theme.colors.text};
  }
`;
Enter fullscreen mode Exit fullscreen mode

A minimal reset + theme-aware body styles.

5 · A typed Button component (src/components/Button.tsx) 

import styled from "styled-components";

type ButtonProps = {
  variant?: "primary" | "secondary";
};

export const Button = styled.button<ButtonProps>`
  border: none;
  cursor: pointer;
  padding: ${({ theme }) => theme.spacing(3)} ${({ theme }) => theme.spacing(4)};
  border-radius: 4px;
  font-weight: 600;
  background: ${({ variant = "primary", theme }) =>
    variant === "primary" ? theme.colors.primary : theme.colors.secondary};
  color: #fff;
  transition: opacity 0.2s;

  &:hover { opacity: 0.9; }
`;
Enter fullscreen mode Exit fullscreen mode

The generic <ButtonProps> unlocks variant-safe theming without prop drilling.

6 · A tidy Card component (src/components/Card.tsx) 

import styled from "styled-components";

export const Card = styled.div`
  background: #fff;
  border-radius: 6px;
  padding: ${({ theme }) => theme.spacing(6)};
  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.08);
`;
Enter fullscreen mode Exit fullscreen mode

7 · A sample page (src/pages/Home.tsx) 

import { Card } from "../components/Card";
import { Button } from "../components/Button";

export default function Home() {
  return (
    <Card>
      <h1>Welcome!</h1>
      <p>This page uses styled-components + TypeScript.</p>
      <Button variant="primary">Do the thing</Button>
    </Card>
  );
}
Enter fullscreen mode Exit fullscreen mode

Page files focus purely on product logic, not style details.

8 · App root (src/App.tsx) 

import { ThemeProvider } from "styled-components";
import { theme } from "./styles/theme";
import { GlobalStyles } from "./styles/GlobalStyles";
import Home from "./pages/Home";

export default function App() {
  return (
    <ThemeProvider theme={theme}>
      <GlobalStyles />
      <Home />
    </ThemeProvider>
  );
}
Enter fullscreen mode Exit fullscreen mode

All theme plumbing lives once at the root.

9 · Entry point (src/index.tsx) 

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>
);
Enter fullscreen mode Exit fullscreen mode

10 · Why this setup works

✅ Benefit How it helps in real life
Single source of design Change a color or spacing scale once, everywhere updates.
Full TypeScript safety No more typos in theme keys; IDE hints for every property.
Isolation of concerns Components are portable; pages hold only business logic.
Drop-in scalability Switch to a feature-first folder layout without refactor.

11 · Next steps

  • Storybook — document your design system as you grow.
  • Dark mode — add theme.dark.ts and toggle with React context.
  • Utility helpers — use polished or color for runtime color maths.
  • Performance — enable babel-plugin-styled-components for dead code elimination and better display names.

Top comments (0)