Forem: Amandeep Singh

I rebuilt this write-up after a full master-branch audit and focused it on what the code actually ships today: a single-page interactive algorithm visualizer with real-time constraint feedback, simulation playback, and responsive controls.

Live demo: https://singhAmandeep007.github.io/eight-queens-problem-visualizer/

Repository: https://github.com/singhAmandeep007/eight-queens-problem-visualizer

What the App Does
Architecture
Design System
Theming
Motion and Animations
Particles and Background Effects
Special Interaction
Projects Module
Posts and Blog Module
About and Profile Module
Responsiveness
Performance
Deployment
Key Implementation Details
Lessons Learned and Next Steps

What the App Does

The N-Queens puzzle asks us to place N pieces on an N x N board with zero conflicts.

This project turns that into an interactive engineering playground:

Piece-rule switching: queen, bishop, rook, knight
Manual mode for direct placement and conflict feedback
Simulation mode for animated backtracking exploration
Variable board size from 4x4 to 8x8
Solution list replay to inspect discovered arrangements

Architecture

The app is intentionally compact but still modular in behavior:

App shell in App.tsx
State domains in ControlContext and AlertContext
Algorithm and rendering orchestration in Chessboard
Rule engine utilities in constants
Reusable control primitives in ControlSelect and common/button

Flowchart image (static for Dev.to compatibility):

Design System

The design system is lightweight and practical:

CSS variables define core color tokens
Styled-components handle composable UI surfaces
Reusable button primitive keeps action affordances consistent
Board and controls share clear visual hierarchy and spacing

Theming

Even without a dark/light toggle, the app is tokenized:

Primary and secondary hues drive control and action zones
Surface and background tokens support layered feedback
Piece and board contrast remains readable across interactions

Because tokens are centralized, runtime theme switching can be introduced later with minimal component churn.

Motion and Animations

Motion is used to explain logic rather than decorate UI:

Simulation playback updates board state at user-selected speed
Alerts animate in and out for lightweight status communication
Solved-state celebration gives immediate completion feedback

Particles and Background Effects

This branch intentionally avoids heavy particle layers and uses informative effects instead:

Conflict squares use striped overlays
Board container shadows emphasize focus
Celebration overlay marks solved states

That keeps the experience fast while preserving strong visual state signaling.

Special Interaction

The standout interaction is simulation control + replayability:

Play/Stop orchestrates async search
Simulation auto-interrupt logic handles tab visibility changes
Solved boards can be reset and replayed rapidly

GIF fallback:

Projects Module

In this single-page architecture, the solution explorer acts as the project/results module:

Every valid solution is persisted
Entries are clickable to preview placements instantly
Duplicate solutions are deduplicated using serialized keys

Posts and Blog Module

The in-app information modal works as the educational content module:

Problem statement and interaction model are available inline
Portal rendering avoids z-index and stacking issues
Users can enter and exit context quickly without navigation

About and Profile Module

Profile attribution is implemented in the footer module:

Author identity is visible in the app shell
External profile link supports discoverability and ownership

Responsiveness

Responsive behavior is handled through global breakpoints and adaptive layouts:

Root font scaling across screen-size bands
Control bar wrapping under smaller widths
Chessboard + side panel stack behavior for mobile ergonomics

Performance

Performance decisions visible in the code:

useMemo for board-grid generation by board size
Cached solved-state checks for repeated position sets
Fast simulation mode for rapid enumeration
Input controls disabled while simulation runs to reduce race conditions

Known trade-off:

Position encoding uses row*10+col, which is compact and efficient for current board ranges (4-8), but not ideal for larger generalized boards.

Deployment

Deployment pipeline is straightforward and production-safe:

npm run build creates dist output
npm run deploy uses gh-pages
Vite base path is derived from GITHUB_PAGES_REPO for GitHub Pages correctness

Key Implementation Details

Context-driven state architecture
ControlContext owns mode, speed, piece type, board size, simulation state
AlertContext centralizes user feedback and timeout cleanup
Rule engine abstraction
checkConflictMethods encapsulates row/column, diagonal, and knight checks
checkIsAttacking and checkIsSolved compose these rules for both manual and simulation paths
Async simulation loop
Recursive backtracking-style search enumerates candidate positions
Board state updates are interleaved with delays for visual progression
Stop conditions are managed with refs and side effects for safe interruption

Lessons Learned and Next Steps

Lessons:

Explicit state boundaries make even single-page apps easier to reason about
Algorithm visualizers benefit from controls that expose execution speed and mode
Visual effects should carry semantic meaning, not just aesthetics

Next improvements:

Extract solver logic to a dedicated module for stronger unit testing
Add symmetry reduction for mathematically equivalent solutions
Move from row*10+col encoding to coordinate tuples for long-term extensibility
Add keyboard-first interaction flow for accessibility

How I Built My Portfolio Website with React + Vite: Themes, Particles, GitHub Visualizations, and a Dev.to-Powered Posts Page

Amandeep Singh — Sun, 05 Apr 2026 06:00:06 +0000

How I Built My Portfolio Website with React + Vite: Themes, Particles, GitHub Visualizations, and a Dev.to-Powered Posts Page

I recently rebuilt my personal portfolio to reflect how I like to build products: clear architecture, expressive UI, strong performance defaults, and data-backed sections that stay fresh.

Live website: https://singhamandeep007.github.io/

Repository: https://github.com/singhAmandeep007/singhAmandeep007.github.io

Project Overview
Design Direction
Architecture At A Glance
Theme Engine (Multi Theme)
Particles Background With Floating Tech Logos
Resume Open Animation
Projects Page
Posts Page (Powered By Dev.to API)
About Page + GitHub Contributions + GitHub Showcase
Responsive UX + Sidebar Navigation
Performance + Developer Experience
What I Would Improve Next
Final Thoughts

Project Overview

This portfolio is built with:

React 18 + TypeScript
Vite 5
styled-components
React Router (lazy route loading)
tsParticles for animated background motion
Dev.to API integration for articles
GitHub GraphQL API integration for contribution and profile showcase widgets

The goal was simple:

Keep the UI visually alive without becoming noisy.
Keep content dynamic where possible (GitHub + Dev.to).
Keep the codebase modular and easy to personalize.

Design Direction

I wanted the experience to feel like a blend of developer identity and product polish:

bright accent colors that can switch at runtime,
subtle glassmorphism where it helps depth,
playful details (handwave animation, envelope-style resume interaction),
high-density information modules on About (contributions, profile metrics, repo cards).

The whole layout stays section-based, with each page having a clear visual job:

Home: first impression + CTA
Projects: proof of work
Posts: writing and thought process
About: profile depth + GitHub signal

Architecture At A Glance

I use a shared layout route that always renders:

sidebar menu,
active route outlet,
theme toggler,
particle background.

flowchart LR
  A[ThemeProvider + GlobalStyle] --> B[Shared Layout]
  B --> C[SidebarMenu]
  B --> D[Route Outlet]
  B --> E[ToggleTheme]
  B --> F[ParticlesContainer]

  D --> H[Home]
  D --> I[Projects]
  D --> J[Posts]
  D --> K[About]

  K --> L[GitHub Contributions GraphQL]
  K --> M[GitHub Showcase GraphQL]
  J --> N[Dev.to Articles API]

This structure keeps global behavior centralized while pages remain focused.

Theme Engine (Multi Theme)

One of my favorite parts is the theme system.

Themes are created through a small theme factory (createTheme) using primary/background/font values.
The app generates CSS variables for each theme class.
Theme switching is class-based on document.documentElement for instant variable swapping.
A small transition class smooths the color shift.

I also map theme colors into GitHub contribution chart palettes, so the data visuals feel native to whichever theme is active.

Particles Background With Floating Tech Logos

The background uses tsParticles in two layers:

baseline moving particles,
floating image particles sourced from my tech logo list.

A batched loader progressively injects logo particles so the effect ramps up instead of appearing all at once. It gives the page ambient motion while keeping content readable.

Resume Open Animation

Instead of a normal download button, I built a small envelope interaction:

a cover flap rotates with rotateX,
the letter slides out,
click opens/closes,
click on letter triggers resume download.

It is intentionally playful, but still functional and accessible.

Projects Page

The Projects page is data-driven from a single projects data source:

markdown-supported descriptions,
per-project stack icons,
image/video slide support,
fullscreen preview support.

I alternate layout direction between odd/even project items for visual rhythm on larger screens, then collapse to a single-column flow on mobile.

Posts Page (Powered By Dev.to API)

The Posts page fetches articles directly from my Dev.to account and renders them as cards with:

cover image,
tags,
publish date,
comments count,
reactions count.

I filter out repost-like items by checking reading time so the page emphasizes full technical pieces.

About Page + GitHub Contributions + GitHub Showcase

This page combines static profile context with live GitHub data.

1) Contributions Calendar

I fetch contribution years and calendars from GitHub GraphQL, then render a custom SVG chart.

Features include:

virtualized week rendering for smoother scroll,
multiple visual modes (Heatmap, Forest, Garden, Skyline),
year jump controls,
auto-scroll playback,
palette adaptation by active theme.

2) GitHub Showcase

I also built a profile showcase module using GraphQL to display:

follower and repo metrics,
contribution metrics (commits/PRs),
language distribution bar,
pinned/top repositories with topic badges.

Full About page context:

Responsive UX + Sidebar Navigation

Responsiveness is handled through centralized breakpoints and component-level media rules.

Key UX behaviors:

focus-trapped sidebar menu,
click-outside to close overlays,
blur treatment on background content when overlays are active,
typography scaling by breakpoint,
horizontal overflow handling for dense visual modules.

This keeps keyboard and touch interactions practical across sizes.

Performance + Developer Experience

Some implementation decisions that helped:

route-level lazy imports,
manual chunk grouping for vendor and particle libraries,
optional dev-time TypeScript/ESLint checking via environment toggles,
build visualizer output for bundle inspection,
strict TypeScript config and lint/format scripts.

For deployment, GitHub Actions builds and ships to GitHub Pages.

What I Would Improve Next

If I take this further, I would like to add:

richer skeleton/loading states instead of blank transitions,
offline support + cache strategy for API-backed sections,
more accessibility audits (focus indicators, reduced-motion pathways),
analytics on which projects/posts get most engagement.

Final Thoughts

This portfolio became more than a profile page. It is now a living frontend playground where I can experiment with UI systems, data visualizations, and interaction patterns in production.

If you want to explore or fork it:

I would love feedback on the architecture and UX decisions.

Building a Production-Ready React + Vite + TypeScript Boilerplate: Architecture, Choices & DX Deep-Dive

Amandeep Singh — Sat, 04 Apr 2026 11:47:37 +0000

Table of Contents
🎯 Why Another Boilerplate?
🏗️ High-Level Architecture
📁 Project Structure — Organized for Scale
⚡ The Foundation: Vite + React + TypeScript
- Why Vite?
🧭 Routing: TanStack Router
- Why TanStack Router over React Router?
🗄️ State Management: The Two-Store Strategy
- TanStack Query — Server State
- Zustand — Client State
- Auto-Generated Selectors
🌐 API Layer: ky + ApiService Pattern
- Why ky over Axios or fetch?
- The ApiService abstraction
🎭 API Mocking: MSW
🌍 Internationalization: i18next
🧪 Testing Strategy: The Full Pyramid
- Unit Tests: Vitest + React Testing Library
- Component Tests: Storybook + Vitest Browser
- E2E Tests: Cypress
🎨 UI Layer: Shadcn UI + Tailwind CSS
- Why Shadcn UI?
🔧 Developer Experience (DX) Toolchain
- Code → Lint → Format → Commit
- ESLint: Context-Aware Rules
🛠️ DevTools: Development-Only by Design
🔒 TypeScript: Beyond the Basics
🚀 The Release Pipeline
📊 Dependency Philosophy
🏁 Getting Started in 30 Seconds
🎬 Wrapping Up

🎯 Why Another Boilerplate?

Every new React project starts with the same ritual: configure the bundler, set up linting, add routing, figure out state management, wire up testing... and before you know it, you have spent two days on tooling instead of building features.

I built react-vite-boilerplate to eliminate that friction. It is not a minimal starter — it is an opinionated, production-ready foundation that codifies hard-won architectural decisions so you can ship from day one.

In this post, I will walk you through:

The architecture and how each layer connects
Why each dependency was chosen (and what alternatives were rejected)
The developer experience toolchain that keeps the codebase healthy
The testing strategy that spans unit, component, and E2E layers
The release pipeline with automated versioning and npm publishing

🏗️ High-Level Architecture

The boilerplate follows a clear layered architecture where each tier has a single, well-defined responsibility:

┌─────────────────────────────────────────────────┐
│              UI Layer                           │
│   React Components · Shadcn UI · Tailwind CSS   │
│   Storybook (component workshop)                │
├─────────────────────────────────────────────────┤
│              Routing Layer                      │
│   TanStack Router (file-based, fully typesafe)  │
├────────────────────┬────────────────────────────┤
│  Server State      │  Client State              │
│  TanStack Query    │  Zustand                   │
├────────────────────┴────────────────────────────┤
│              API Layer                          │
│   ky HTTP client · ApiService class             │
├─────────────────────────────────────────────────┤
│              Mock Layer                         │
│   MSW (Mock Service Worker)                     │
└─────────────────────────────────────────────────┘

Why layers? Each layer can be understood, tested, and replaced independently. Swap Zustand for Jotai? Only the client state layer changes. Switch from ky to axios? Only the API layer is affected.

📁 Project Structure — Organized for Scale

The folder structure is intentionally feature-oriented at the top level yet technically separated within each feature:

src/
├── app/           # App shell: providers, router, auth context
├── api/           # Service classes + React Query hooks per domain
│   ├── apiService.ts   # Base HTTP client (ky wrapper)
│   ├── auth/           # Auth-specific API logic
│   ├── posts/          # Posts domain: service + hooks + types
│   └── user/           # User domain
├── components/    # Shared components
│   ├── ui/           # Shadcn UI primitives (Button, Toast, etc.)
│   ├── layout/       # Navbar, Footer, Sidebar
│   ├── forms/        # Form components with React Hook Form
│   └── hooks/        # Shared custom hooks
├── config/        # App configuration constants
├── mocker/        # MSW handlers and server setup
├── modules/       # Cross-cutting modules
│   └── i18n/         # Internationalization (i18next)
├── pages/         # Page-level components
│   ├── Home/
│   ├── Auth/
│   └── App/
├── routes/        # TanStack Router file-based route definitions
├── store/         # Zustand store with slices + middlewares
├── tests/         # Test utilities, setup, and wrappers
├── types/         # Global TypeScript type definitions
└── utils/         # Pure utility functions

Key insight: The api/ directory co-locates service classes, React Query hooks, and TypeScript types for each domain. This means everything related to "posts" lives in api/posts/ — making it trivial to find, modify, or delete an entire feature.

⚡ The Foundation: Vite + React + TypeScript

Why Vite?

Vite is the fastest development server in the React ecosystem. But we go further with a carefully tuned vite.config.ts:

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd() + "/env");
  const isDevMode = mode === "development";

  const plugins = [
    svgr(),                    // Import SVGs as React components
    TanStackRouterVite(),      // Auto-generate route tree
    react(),                   // React Fast Refresh
    inspect(),                 // Vite plugin inspector (dev)
  ];

  // Conditional dev-time checks
  if (isDevMode) {
    plugins.push(
      checker({
        typescript: shouldCheckTypeScriptDev,
        eslint: shouldCheckESLintDev ? { ... } : undefined,
      })
    );
  }

  // Bundle analysis on demand
  if (process.env.ANALYZE === "true") {
    plugins.push(visualizer({ template: "treemap", open: true }));
  }

  return { plugins };
});

What makes this special:

Plugin	Purpose
`vite-plugin-svgr`	Import `.svg` files as React components
`@tanstack/router-plugin`	Auto-generates the route tree from the file system
`vite-plugin-checker`	TypeScript + ESLint checks during dev (configurable via env vars)
`vite-plugin-inspect`	Inspect Vite internals — useful for debugging transform pipelines
`rollup-plugin-visualizer`	On-demand bundle analysis with treemap, gzip, and brotli sizes

💡 Pro tip: The TypeScript and ESLint dev checks are toggleable via environment variables (VITE_TSC_DEV_CHECK, VITE_ESLINT_DEV_CHECK). This lets you disable them when iterating quickly and re-enable for pre-commit validation.

🧭 Routing: TanStack Router

Why TanStack Router over React Router?

Full type safety. TanStack Router is the only React router that provides end-to-end TypeScript inference — from route params, to search params, to loader data, to the context object.

// routes/app.tsx — Protected route with type-safe context
export const Route = createFileRoute("/app")({
  beforeLoad: ({ context }) => {
    // context.auth is fully typed as TAuthStoreState | null
    if (!context.auth?.user) {
      redirect({ to: "/auth/login", throw: true });
    }
  },
  component: AppLayout,
});

File-based routing means the route hierarchy mirrors the file system:

routes/
├── __root.tsx      → Root layout (devtools, document title)
├── index.tsx       → "/"  (landing page)
├── app.tsx         → "/app" (protected layout)
├── app/
│   └── ...         → "/app/*" child routes
├── auth.tsx        → "/auth" (guest-only layout)
└── auth/
    └── login.tsx   → "/auth/login"

The router is configured to work seamlessly with React Query by sharing the queryClient via context:

export const router = createRouter({
  routeTree,
  context: { auth: null, queryClient },
  defaultPreload: "intent",
  defaultPreloadStaleTime: 0, // Always re-fetch on preload
});

Why defaultPreloadStaleTime: 0? Since React Query manages caching, we want the router to always invoke the loader so React Query can decide whether to serve from cache or refetch. This gives us a single source of truth for cache policy.

🗄️ State Management: The Two-Store Strategy

State management is where most boilerplates get it wrong by choosing a single solution for everything. This boilerplate makes a deliberate split:

┌──────────────────────────────────────────────┐
│           State Management Strategy          │
├──────────────────────┬───────────────────────┤
│   Server State       │   Client State        │
│   TanStack Query     │   Zustand             │
│                      │                       │
│   • API responses    │   • Auth state        │
│   • Caching          │   • UI preferences    │
│   • Refetching       │   • Session data      │
│   • Pagination       │   • Form state        │
│   • Optimistic       │   • Theme             │
│     updates          │                       │
└──────────────────────┴───────────────────────┘

TanStack Query — Server State

Server state is data that lives on the server and is temporarily borrowed by the client. React Query handles caching, background refetching, stale-while-revalidate, pagination, and more.

Here is how we structure API queries:

// api/posts/posts.hooks.ts
export const useGetPostsQuery = (
  options?: Omit<UseQueryOptions<TGetPostsResponsePayload, TApiServiceError>,
    "queryKey" | "queryFn">
) => {
  return useQuery({
    queryKey: [GET_POSTS_QUERY_KEY],
    queryFn: async () => await postsService.getPosts(),
    ...options,
  });
};

Why wrap useQuery in custom hooks? Encapsulation. The consuming component does not need to know the query key, the service method, or how to handle errors — it just calls useGetPostsQuery().

Zustand — Client State

For client-only state (auth, theme, UI preferences), Zustand provides a lightweight, boilerplate-free solution:

// store/store.ts
export const useStoreBase = create<TStore>()(
  logger(                      // Custom logging middleware
    devtools(                  // Redux DevTools integration
      subscribeWithSelector(   // Fine-grained subscriptions
        persist(store, {       // Session storage persistence
          name: STORE_NAME,
          storage: createJSONStorage(() => sessionStorage),
          version: STORE_VERSION,
          migrate: (persistedState, prevVersion) => {
            // Handle breaking changes gracefully
          },
        })
      ),
      { enabled: isDebugMode }
    ),
    { name: STORE_NAME, enabled: isDebugMode }
  )
);

The middleware stack tells a story:

persist — Survives page refreshes via sessionStorage with versioned migrations
subscribeWithSelector — Components re-render only when their specific slice changes
devtools — Time-travel debugging in Redux DevTools (only in dev)
logger — Custom middleware that logs state transitions with styled console output

Auto-Generated Selectors

Instead of writing selectors by hand, the createSelectors utility generates them automatically:

// Instead of:
const user = useStore((state) => state.user);

// You write:
const user = useStore.use.user();

This is powered by a small but elegant utility:

export const createSelectors = <S extends UseBoundStore<StoreApi<object>>>(_store: S) => {
  const store = _store as TWithSelectors<typeof _store>;
  store.use = {};
  for (const k of Object.keys(store.getState())) {
    (store.use as any)[k] = () => store((s) => s[k as keyof typeof s]);
  }
  return store;
};

🌐 API Layer: ky + ApiService Pattern

Why ky over Axios or fetch?

Feature	`fetch`	`axios`	`ky`
Bundle size	0 KB	~13 KB	~3 KB
Retry logic	Manual	Manual	Built-in
Hook system	No	Interceptors	Hooks
JSON parsing	Manual	Automatic	Automatic
TypeScript	OK	OK	Excellent

ky gives us the best of both worlds: a tiny bundle with powerful features like hooks, timeout, and retry — without the overhead of axios.

The ApiService abstraction

Rather than coupling ky throughout the app, we wrap it in a class that implements a generic THttpService interface:

export type THttpService<Options> = {
  get<R>(url: string, options?: Options): Promise<R>;
  post<R, B>(url: string, body: B, options?: Options): Promise<R>;
  put<R, B>(url: string, body?: B, options?: Options): Promise<R>;
  // ...
};

export class ApiService implements THttpService<Options> {
  constructor(options: Options = {}) {
    this.kyInstance = ky.create({
      hooks: {
        beforeRequest: [(request) => {
          request.headers.set("Accept-Language", i18n.currentLanguage);
        }],
        beforeError: [(error) => {
          // Translate HTTP error codes to i18n messages
          error.message = i18n.t(["errors:http.status", "errors:http.unknown"], {
            context: response.status,
          });
          return error;
        }],
      },
      prefixUrl: apiURL(),
      retry: { limit: 0 },
    });
  }
}

Why this pattern?

Swap-ability: Replacing ky with axios or fetch requires changing only ApiService
Cross-cutting concerns: Language headers, error translations, and auth tokens are configured once
Testability: Mock the ApiService in tests without mocking HTTP internals

🎭 API Mocking: MSW

Mock Service Worker is the unsung hero of this boilerplate. It intercepts HTTP requests at the network level, meaning your application code does not know (or care) whether it is talking to a real API or a mock.

// mocker/server.ts
const worker = setupWorker(...handlers);

export const runServer = () => {
  return worker.start({
    onUnhandledRequest: "bypass",
    serviceWorker: {
      url: serviceWorkerUrl,
      options: { scope: appBasePath },
    },
  });
};

Why MSW over JSON server or local Express?

Works in the browser (dev) and in Node (unit tests) with the same handlers
No separate process to start — it runs alongside your app
Handlers are strongly typed and co-located with API code
E2E tests can override individual handlers for edge cases

In main.tsx, the MSW server starts before React renders:

async function setupApp() {
  await i18n.configure();
  const mocker = await import("./mocker/index.ts");
  await mocker.runServer();
}

setupApp().then(() => {
  root.render(<StrictMode><App /></StrictMode>);
});

🌍 Internationalization: i18next

The I18n class wraps i18next with a clean, testable API:

export class I18n {
  async configure({ initOptions, config } = {}) {
    const i18nInstance = this.i18n.use(initReactI18next);
    if (config.withLanguageDetector) {
      i18nInstance.use(LanguageDetector);
    }
    // Dynamic imports for locale files via Vite glob
    i18nInstance.use({
      type: "backend",
      read: async (language, namespace, callback) => {
        const modules = import.meta.glob("./locales/*/*.json");
        const data = await modules[`./locales/${language}/${namespace}.json`]();
        callback(null, data);
      },
    });
  }
}

Key design decisions:

Vite import.meta.glob for lazy-loading locale files — only the active language is loaded
Custom formatters (uppercase, lowercase) registered at init time
Browser language detection with localStorage caching and graceful fallback
Namespace-based organization — separate common.json, errors.json, auth.json per language
Type-safe translations via i18next.d.ts declarations

🧪 Testing Strategy: The Full Pyramid

The boilerplate implements a complete testing pyramid with MSW as the mocking backbone across all layers:

          ╱╲
         ╱  ╲
        ╱ E2E╲         Cypress
       ╱──────╲
      ╱Component╲      Storybook + Vitest Browser Mode
     ╱────────────╲
    ╱  Unit Tests   ╲   Vitest + React Testing Library
   ╱──────────────────╲
  ╱   MSW (all layers)  ╲
 └───────────────────────┘

Unit Tests: Vitest + React Testing Library

Vitest shares Vite's config and transformation pipeline, which means zero config drift between dev and test environments:

// vitest.config.ts (simplified)
test: {
  name: "unit",
  environment: "jsdom",
  setupFiles: ["./tests/setup.ts"],
  typecheck: { enabled: true },  // Test your types too!
  mockReset: true,
  coverage: {
    provider: "v8",
    reporter: ["html"],
  },
}

The test wrapper is designed for maximum realism:

export const Wrapper: FC<PropsWithChildren<TWrapperProps>> = ({
  children,
  config = { withToaster: true, withRouter: true },
}) => {
  const providers: TProvider[] = [];
  providers.push({ Provider: ThemeProvider, props: {} });

  if (config?.withRouter) {
    // Sets up a real TanStack Router instance for each test
    const rootRoute = createRootRoute({ component: Outlet });
    const indexRoute = createRoute({ /* ... */ });
    providers.push({ Provider: RouterProvider, props: { router } });
  }

  return <>{addProviders(providers, children)}</>;
};

Component Tests: Storybook + Vitest Browser

Storybook is not just for documentation — it is a testing runtime. The boilerplate uses @storybook/addon-vitest to run story-based tests in a real browser via Playwright:

// vitest.config.ts — storybook project
{
  plugins: [
    storybookTest({ configDir: ".storybook" }),
  ],
  test: {
    name: "storybook",
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: "chromium" }],
    },
  },
}

Accessibility is enforced: The @storybook/addon-a11y plugin runs axe-core checks on every story, configured to fail on violations.

E2E Tests: Cypress

For full user-journey validation:

npm run test:e2e          # Interactive mode
npm run test:e2e:headless # CI mode

Cypress tests live in cypress/specs/ and use custom ESLint rules to enforce best practices like data-* selectors and assertion-before-screenshot.

🎨 UI Layer: Shadcn UI + Tailwind CSS

Why Shadcn UI?

Shadcn is not a component library — it is a collection of copy-paste components built on Radix UI primitives. You own the code:

components/ui/
├── Button/          # Button with variants via CVA
├── Toast/           # Toast notifications (Radix)
├── DropdownMenu/    # Dropdown with keyboard nav
├── Tooltip/         # Accessible tooltips
├── ThemeToggler/    # Dark/light mode switch
├── LangToggler/     # Language switcher
├── Typography/      # Consistent text styles
├── Brand/           # Logo and branding
└── RouteLink/       # Type-safe navigation link

Why this over Material UI or Ant Design?

Zero runtime overhead — it is just your code
Full customization — no fighting framework CSS
Radix primitives — best-in-class accessibility (WAI-ARIA)
CVA (Class Variance Authority) — Type-safe component variants

🔧 Developer Experience (DX) Toolchain

The DX pipeline ensures quality at every stage:

Code → Lint → Format → Commit

 Developer writes code
         │
    ┌────▼────┐
    │  ESLint │  Static analysis with 8 plugins
    └────┬────┘   (react, hooks, refresh, cypress,
         │        storybook, testing-library, typescript)
    ┌────▼──────┐
    │  Prettier │  Opinionated formatting with
    └────┬──────┘   import sorting + Tailwind ordering
         │
    ┌────▼──────────┐
    │  lint-staged  │  Only processes staged files
    └────┬──────────┘
         │
    ┌────▼──────────┐
    │  Commitizen   │  Conventional commit messages
    └────┬──────────┘
         │
    ┌────▼──────┐
    │  Devmoji  │  Automatic emoji decoration ✨
    └────┬──────┘
         │
    ┌────▼──────┐
    │   Husky   │  Git hooks orchestration
    └───────────┘

ESLint: Context-Aware Rules

The ESLint config uses flat config with context-aware rule sets:

export default tseslint.config(
  // Base: TypeScript recommended + stylistic
  { extends: [...tseslint.configs.recommendedTypeChecked] },

  // Stories: Storybook-specific rules
  { files: ["**/*.stories.{ts,tsx}"], extends: storybook.configs["flat/recommended"] },

  // Tests: Testing Library rules
  { files: ["**/*.{spec,test}.{ts,tsx}"], extends: testingLibrary.configs["flat/react"] },

  // E2E: Cypress rules
  { files: ["cypress/**/*"], extends: cypress.configs.recommended },
);

Naming conventions are enforced at the type level:

// All type aliases must start with "T"
"@typescript-eslint/naming-convention": [
  "error",
  { selector: ["typeAlias"], format: ["PascalCase"],
    custom: { regex: "^T[A-Z]", match: true } },
]

🛠️ DevTools: Development-Only by Design

The boilerplate ships with three sets of devtools that are automatically tree-shaken in production:

// components/developmentTools.tsx
export const TanStackRouterDevelopmentTools = !isDevelopment
  ? (): null => null  // No-op in production
  : React.lazy(() =>
      import("@tanstack/router-devtools").then((result) => ({
        default: result.TanStackRouterDevtools,
      }))
    );

The pattern:

Check isDevelopment at module scope
In production: export a component that returns null (zero bundle cost)
In development: React.lazy() for code-split loading

This means devtools are never included in your production bundle — not even as dead code.

🔒 TypeScript: Beyond the Basics

The boilerplate includes a set of global utility types that solve real problems:

// Deeply partial types (useful for Zustand store updates)
type RecursivePartial<T> = {
  [P in keyof T]?: T[P] extends (infer U)[]
    ? RecursivePartial<U>[]
    : T[P] extends object | undefined
      ? RecursivePartial<T[P]>
      : T[P];
};

// Type-safe value extraction from const objects
type ValueOf<T> = T[keyof T];
// const THEME = { LIGHT: "light", DARK: "dark" } as const;
// type TTheme = ValueOf<typeof THEME>; // "light" | "dark"

// String manipulation at the type level
type ReplaceFirst<TString, TToReplace, TReplacement> =
  TString extends `${infer P}${TToReplace}${infer S}`
    ? `${P}${TReplacement}${S}`
    : TString;

Type testing is first-class — all *.test-d.ts files are automatically discovered and validated by Vitest.

🚀 The Release Pipeline

The boilerplate includes a complete automated release system powered by Changesets + GitHub Actions:

Feature Branch ──► PR to main ──► Merge
                                    │
                         ┌──────────▼──────────┐
                         │   release.yml runs  │
                         │   lint → typecheck  │
                         │   → test → publish  |
                         └──────────┬──────────┘
                                    │
                   ┌────────────────▼────────────────┐
                   │     Release PR created          │
                   │  version bump + changelog       │
                   └────────────────┬────────────────┘
                                    │
                             Merge Release PR
                                    │
                         ┌──────────▼──────────┐
                         │  npm publish        │
                         │  + GitHub Release   │
                         └─────────────────────┘

The published CLI package @singhamandeep/crvb lets anyone scaffold a new project:

npx @singhamandeep/crvb@latest my-app
cd my-app && npm install && npm run dev

📊 Dependency Philosophy

Every dependency was chosen based on three criteria:

Criteria	Question
Necessity	Does this solve a real problem that would require significant custom code?
Quality	Is this actively maintained, well-tested, and has a healthy community?
Size	Is this the smallest possible solution that meets our needs?

Category	Choice	Why This Over Alternatives
Bundler	Vite	10-100x faster than Webpack; native ESM
Router	TanStack Router	Only fully type-safe React router
Server State	TanStack Query	Best caching + devtools; de facto standard
Client State	Zustand	~1KB; no boilerplate; middleware-composable
HTTP Client	ky	~3KB fetch wrapper with hooks and retry
Forms	React Hook Form + Zod	Uncontrolled perf; schema-first validation
UI	Shadcn + Radix	You own the code; best a11y primitives
Styling	Tailwind CSS	Utility-first; no CSS-in-JS runtime cost
i18n	i18next	Most mature; plugin ecosystem
Utilities	Radash	Modern lodash; tree-shakeable; zero deps
Date	date-fns	Modular; tree-shakeable; immutable
API Mocking	MSW	Network-level; browser + Node
Unit Test	Vitest	Vite-native; Jest-compatible API
E2E Test	Cypress	Best DX for E2E; time-travel debugging
Components	Storybook	Industry standard; visual testing

🏁 Getting Started in 30 Seconds

# Option 1: Scaffold via CLI
npx @singhamandeep/crvb@latest my-app
cd my-app && npm install && npm run dev

# Option 2: Clone directly
git clone https://github.com/singhAmandeep007/react-vite-boilerplate.git
cd react-vite-boilerplate
npm install && npm run prepare && npm run dev

🎬 Wrapping Up

This boilerplate is the result of years of iterating on production React applications. Every choice — from the middleware stack in Zustand to the ESLint naming conventions — was battle-tested in real projects before making it into the template.

The goal is not to provide every feature, but to provide the right foundation that scales from a side project to a production application without requiring an architectural rewrite.

Star the repo if you found this useful: ⭐ react-vite-boilerplate

Scaffold your next project:

npx @singhamandeep/crvb@latest my-next-app

Have questions or suggestions? Open an issue or drop a comment below — I would love to hear how you are using it! 🚀

singhAmandeep007 / react-vite-boilerplate

Delightful boilerplate for starting your awesome react + vite application.

React Vite Boilerplate

Everything you need to start with your next Vite + React web app! Delighful developer experience with batteries included.

Demo

react-vite-boilerplate.webm

Technical Blog

Overview

Built with type safety, scalability, and developer experience in mind. A batteries included Vite + React template.

A more detailed list of the included packages can be found in the Installed Packages section.

Requirements

NodeJS 24.x (see .nvmrc)
npm

Getting Started

Getting started is a simple as cloning the repository

git clone https://github.com/singhAmandeep007/react-vite-boilerplate.git

Changing into the new directory

cd react-vite-boilerplate

Removing the .git folder (and any additional files, folders or dependencies you may not need)

rm -rf .git

Installing dependencies

npm install

And running the setup script…

View on GitHub

Happy coding! ✨

Hey devs, checkout my article on building a production ready react + vite application using an awesome boilerplate. 🚀

Amandeep Singh — Thu, 11 Sep 2025 14:51:52 +0000

Amandeep Singh

Nov 25 '24

Building a Production Ready React Vite TypeScript Boilerplate

#react #vite #typescript

Comments

5 min read

Hey devs, checkout my new article on hosting your own n8n server for free, this can save you a lot of $$$. Try it out. 🙂

Amandeep Singh — Thu, 11 Sep 2025 14:44:49 +0000

Amandeep Singh

Sep 10 '25

The Ultimate Guide to Self-Hosting n8n for Free using Render and Nhost

#automation #tutorial #hosting #n8n

Comments 1

7 min read

The Ultimate Guide to Self-Hosting n8n for Free using Render and Nhost

Amandeep Singh — Wed, 10 Sep 2025 18:03:38 +0000

Are you tired of manual, repetitive tasks? Do you wish you had a powerful, open-source automation tool that you could truly own and control?

Then welcome to the world of n8n!

N8n is a powerful, open-source, and feature-rich workflow automation tool. With its intuitive visual editor and a wide array of over 400 integrations, it's a stellar alternative to SaaS giants like Zapier and Make. But where should you run it? That's the first question on every developer's mind.

The Hosting Dilemma

Every journey with n8n begins with a choice: do you opt for the convenience of a managed cloud service or do you take the road of self-hosting? This is the central hosting dilemma.

n8n Cloud: This is the easiest, most hassle-free option for those who want to get started quickly and don't want to worry about server maintenance. Updates, security patches, backups, and scaling are all handled for you. However, n8n's cloud plan can start around $24/month for a limited number of executions, with costs quickly climbing for higher usage, which can be a significant barrier for students and hobbyists.
Self-Hosting: Self-hosting means you install and run n8n on your own infrastructure, giving you complete control over your data, a key advantage for organizations with strict data privacy requirements. You can easily accomplish this with Docker, which offers portability, reproducibility, and simplified updates. However, this comes with the responsibility of managing the server, including security, backups, and updates.
The Best of Both Worlds: The Solution: This article proposes a middle ground that combines the flexibility and cost-effectiveness of self-hosting with the simplified management of a cloud platform. By using a managed service like Render for application hosting and Nhost for a free PostgreSQL database, you can bypass many of the complexities of traditional self-hosting.

Cloud Hosting Providers Comparison

For those who choose the self-hosting path, selecting the right cloud provider is a critical decision. While a traditional VPS (Virtual Private Server) from a company like DigitalOcean offers a high degree of control, platforms like Render and Railway have emerged as strong contenders with their simplified, managed services.

Here’s a comparison of these providers to help you decide.

Provider	Starting Price	Specs Included	Notes
Render	$0/month + DB	0.5 vCPU, 512 MB RAM (Web)	Free web service, but spins down after 15 mins of inactivity. The database is a separate, paid service starting at $7/month.
Railway	$5/month (Hobby plan)	~$5 in usage credit; pay for usage	Usage-based pricing can be hard to predict but avoids over-provisioning.
DigitalOcean	~$6/month (Droplet)	1 vCPU, 2 GB RAM, 25–50 GB SSD	Polished UI, but requires manual setup and management.
Sliplane	€9/month	2 GB RAM, 2 vCPU, 40 GB SSD	Offers one-click n8n deployment with backups and HTTPS.
Hetzner	~€3.79/month	2 vCPU, 4 GB RAM, 40 GB SSD (CX22)	Requires a lot of technical know-how. You are responsible for all management, including SSL and backups.

For this tutorial, we will focus on Render and Nhost because they offer a powerful, zero-cost entry point for a fully functional, self-hosted n8n instance.

The Backend: Why a PostgreSQL Database is a Must

While n8n can function with a default SQLite database, a production-level, self-hosted deployment requires a more robust solution. This is where PostgreSQL comes in as the recommended choice for your backend database.

SQLite: By default, n8n uses SQLite, which is a file-based database. It's excellent for local development and single-user scenarios because of its simplicity. However, it is not designed for concurrent write operations, which makes it unsuitable for a cloud environment where multiple processes might access it at the same time.

PostgreSQL: Switching to a client-server database like PostgreSQL unlocks a new level of performance, reliability, and scalability.

Concurrency and Reliability: PostgreSQL is a highly reliable and fault-tolerant database that uses Multi-Version Concurrency Control (MVCC) to handle multiple users accessing data simultaneously without conflicts.
Scalability: PostgreSQL can handle a significant quantity of data and a large number of concurrent users, making it ideal for growing applications.
Data Integrity and Security: PostgreSQL is ACID-compliant (Atomicity, Consistency, Isolation, and Durability), which ensures that database transactions are processed reliably and data integrity is maintained.
Managed Services: By using a managed PostgreSQL service like Nhost, you are freed from the burden of database administration, including tasks like optimization and backup management.

Step-by-Step Deployment Guide

This tutorial will walk you through the step-by-step process of deploying your own self-hosted n8n instance on Render, using a managed PostgreSQL database from Nhost.

1. Set Up Your Nhost Database

First, you need to set up your database on Nhost.

Sign up and Create a Project: Sign up for Nhost using your GitHub account or email. Once in the dashboard, click "Create Project" and give it a name.
Configure Database and Get Credentials:
- Navigate to your project's settings, then go to the "Database" section.
- Here you need to enable Public access to Connect directly to the Postgres database.
- Here, you will find the connection information for your PostgreSQL database.
- Crucial Step: Note down all the individual components from the connection string: the host, port, user, password, and database name. You will need to parse the single DATABASE_URL into these separate environment variables for Render.
- Change the password for your database and save it securely.

Deploy n8n on Render

Next, you will deploy the n8n application to Render, connecting it to your Nhost database.

Sign Up for Render: If you don't have an account, sign up for Render.
Create a New Web Service: From the Render dashboard, click "+ New" and select "Web Service".

Choose the Docker Image:
- Under "Source," select "Existing Image".
- In the "Image URL" field, enter n8nio/n8n:latest and click "Connect". This will use the official n8n Docker image.
- Give your service a name, choose a region closest to you, and select the "Free" instance type.

Add Environment Variables: This is the most important step for connecting your n8n app to the Nhost database and configuring it properly.
- Expand the "Advanced" section and add the following environment variables.
- DB_TYPE: postgresdb
- DB_POSTGRESDB_DATABASE: <nhost database name>
- DB_POSTGRESDB_HOST: <nhost postgres host>
- DB_POSTGRESDB_PASSWORD: <nhost postgres password>
- DB_POSTGRESDB_PORT: 5432
- DB_POSTGRESDB_USER: postgres
- DATABASE_URL: <nhost connection string> + ?sslmode=require. E.g. postgres://postgres:<password>@<host>:<port>/<name>?sslmode=require
- GENERIC_TIMEZONE: America/New_York
- N8N_ENCRYPTION_KEY: LTZl8zNn721OB3x73nGS1QNKu9mXoqblHw0LFr9ifq4= (This is a unique key for encrypting credentials in your database. For security, you must generate your own!)
- N8N_HOST: This will be the URL that Render assigns to your service. You will add this after the first deployment. E.g. self-hosted-n8n.onrender.com
- N8N_PORT: 5678
- N8N_PROTOCOL: https
- WEBHOOK_URL: <render web service URL> This will also be the Render URL, added after the first deployment. E.g. https://self-hosted-n8n.onrender.com/
- TZ: America/New_York
- NODE_ENV: production
- N8N_RUNNERS_ENABLED: true
- N8N_PAYLOAD_SIZE_MAX: 16
- N8N_LOG_LEVEL: info
- N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: false

Initial Deployment: Click "Create Web Service" to start the deployment.

3. Final Configuration and Verification

After the initial deployment, you need to update the two environment variables and verify everything is working.

Update URLs: Once your service is live, Render will provide a public URL (e.g., self-hosted-n8n.onrender.com). Go to your service's settings, then "Environment," and click "Edit". Replace the placeholder values for N8N_HOST with your new Render URL and WEBHOOK_URL with your Render URL including https://.
Check Logs: After the redeployment, check the logs on the Render dashboard. A successful deployment will show lines like "Starting migration," "Finished migration," and "n8n ready on ::, port 5678".
Verify Functionality: Visit the Render URL to access your n8n instance and create your first user account. Your cloud-hosted n8n is now ready to use, and all your workflows and data will be persisted in your Nhost PostgreSQL database.

First Workflow & Verification

At first, it may take a few minutes for the container to download the n8n image and spin up the service, especially for the first-time deployment. Also, note that Render's free web services will "sleep" after 15 minutes of inactivity and will take some time to wake up when accessed again. This is normal for the free tier and a small price to pay for a free, managed service.

After signing up wiht email and password start creating your own workflows and credentials, which are now safely stored and secured in the cloud and remotely accessible. You have unlocked all the features available by hosting it on the cloud, such as making your workflows public.

Final Thoughts & Next Steps

Congratulations! You have successfully deployed your own n8n instance with a robust PostgreSQL backend for little to no cost. This powerful setup gives you the freedom and control of self-hosting, combined with the convenience of a managed cloud environment. Now, go build something amazing!

Bonus

List of some awesome n8n workflows

Building a Production Ready React Vite TypeScript Boilerplate

Amandeep Singh — Mon, 25 Nov 2024 12:19:49 +0000

Overview

As developers, we often find ourselves setting up the same tools and configurations when starting new projects. To address this challenge, I've created a fully type-safe React + Vite boilerplate/starter that serves as a solid foundation for production-ready web applications which scales well.

This template emerged from a need to standardize new projects at work, focusing on developer experience, code quality, and scalability. Let me walk you through what makes this boilerplate special and how you can use it for your next project.

Key Features

🚀 Lightning-fast development with Vite
💪 Full TypeScript support
🗂️ Well organized project structure
🔒 Includes JWT authentication implementation
📡 Modern data fetching with Tanstack React Query
🗃️ State management using Zustand
🛣️ Type-safe and File based routing with Tanstack Router
🌐 Internationalization support (i18n)
📝 Form handling with React Hook Form + Zod
🎨 UI components with Tailwind CSS + shadcn/ui
📚 Component documentation using Storybook
✅ Comprehensive testing setup with Vitest + Cypress + MSW

Requirement

Node.js 20+
npm
git

Getting Started

Installation

# Clone the repository
git clone https://github.com/singhAmandeep007/react-vite-boilerplate.git

# cd into folder
cd react-vite-boilerplate

# Removing the .git folder (and any additional files, folders or dependencies you may not need)
rm -rf .git

# Install dependencies
npm install

# Run the setup script (initializes git repository and husky)
npm run prepare

# Start development server, yeah that's all
npm run dev

Project Structure


├── .storybook
├── cypress
│   ├── downloads
│   ├── fixtures
│   ├── specs
│   ├── support
|   └── tsconfig.json
├── env
├── public
├── src
│   ├── __mocks__
│   ├── app
│   │   ├── auth.ts
│   │   ├── App.ts
│   │   └── router.ts
│   ├── assets
│   ├── api
│   │   ├── auth
│   │   ├── posts
│   │   ├── user
│   │   └── apiService.ts
│   ├── components
│   │   ├── forms
│   │   ├── hooks
│   │   ├── layout
│   │   ├── ui
│   │   └── developmentTools.tsx
│   ├── config
│   ├── mocker
│   ├── modules
│   │   └── i18n
│   ├── pages
│   │   ├── app
│   │   ├── home
│   │   └── auth
│   ├── routes
│   ├── store
│   │   └── auth
│   ├── tests
│   ├── types
│   ├── utils
│   └── index.css
│   └── main.tsx
├── index.html
├── .editorconfig
├── eslint.config.js
├── prettier.config.js
├── cypress.config.js
├── tailwind.config.js
├── .gitignore
├── tsconfig.json
├── vite.config.ts
└── package.json

Key folders and files with purpose

Root Directory

.storybook/: Contains configuration files for Storybook, a popular tool for building UI components and testing them in isolation.
cypress/: Holds end-to-end testing configurations and files.
- downloads/: For storing temporary downloads during tests.
- fixtures/: Mock data for testing.
- specs/: Test cases for Cypress.
- support/: Custom commands and reusable configurations.
- tsconfig.json: TypeScript configuration specific to Cypress.
env/: Environment-specific files (e.g., .env.development, .env.production).
public/: Publicly accessible assets, such as images or static files.
index.html: Entry point for the application.
Configuration files for linting, formatting, and build tools:
- .editorconfig, eslint.config.js, prettier.config.js
- tailwind.config.js: Tailwind CSS configuration.
- vite.config.ts: Vite configuration.
- tsconfig.json: TypeScript compiler configuration.

src Directory
The src folder contains the core of the application:

__mocks__/: Mock files for testing purposes.
app/: Application-level configurations, such as providers (e.g., for React Query, Router, etc.).
api/: Directory is organized into folders of related API endpoints.
assets/: Stores static resources that are part of application.
components/:
- forms/: Reusable form components like input fields or buttons.
- hooks/: Custom React hooks.
- layout/: Components related to the app's layout (headers, footers).
- ui/: Reusable UI components (buttons, cards).
- developmentTools.tsx: Tools or utilities for local development, such as react query devtools.
config/: Configuration files, such as API base URLs or environment settings.
mocker/: For mocking API responses or other utilities during development.
modules/:
- i18n/: Internationalization configurations and translation files.
pages/: Top-level pages, often aligned with routes.
- App/: Pages related to the main application (dasboard, settings).
- Home/: Homepage or landing page.
- Auth/: Authentication-related pages (login, signup).
routes/: File based Route configuration for the app, using Tanstack router.
store/: Global state management, organized by domain.
- auth/: State management logic for authentication.
tests/: Utility functions and wrappers for unit testing.
types/: Shared TypeScript types and interfaces.
utils/: Reusable utility functions and helpers.
index.css: Global CSS or Tailwind imports.
main.tsx: Application entry point, initializing React and rendering the app.

Authentication Implementation

The boilerplate includes a complete JWT authentication setup demonstrating best practices:

Data Flow

API requests using ky for modern HTTP client capabilities. Ky allows modification the request lifecycle using hooks.
Request/response handling with React Query for caching and synchronization
State management through Zustand for auth status and user data
Protected routes implementation with Tanstack Router

Testing

The boilerplate comes with a comprehensive testing setup:

Unit Tests: Vitest + React Testing Library
E2E Tests: Cypress
API Mocking: MSW (Mock Service Worker)

Unit Testing

npm run test:unit

# or with coverage
npm run test:unit:coverage

# or in watch mode
npm run test:unit:watch

# or in ui mode
npm run test:unit:ui

Testing types is also supported with vitest and this application is set up to run tests for types using it. By default all tests inside *.test-d.ts files are considered type tests.

End-to-End (E2E) Testing

npm run test:e2e

# or in headless mode
npm run test:e2e:headless

Development Tools

Dev tools
- @tanstack/react-query-devtools - Dedicated dev tools to help visualize the inner workings of React Query
- @tanstack/router-devtools - Dedicated dev tools to help visualize the inner workings of TanStack Router
- @hookform/DevTools - React Hook Form Devtools to help debug forms with validation
Code Quality
- ESLint for code linting
- Prettier for code formatting
- husky for git hooks
- commitizen + devmoji for standardized commit messages
Pre-commit Checks
- The boilerplate automatically runs the following checks before each commit:
- Linting
- Type checking
- Format checking

Deployment

The project includes GitHub Actions workflows for:

Continuous Integration
- Running e2e tests
- Code quality checks
Continuous Deployment
- Automatic deployment to production environments

Conclusion

This boilerplate aims to provide a solid foundation for your React projects while maintaining flexibility. It incorporates modern tools and best practices without being overly opinionated, allowing you to adapt it to your specific needs.

What's Next?

Clone the repository
Check out the demo implementation
Customize it for your project
Provide feedback or contribute

Remember one design doesn't fit all, so feel free to customize it according to your needs.

Your feedback and contributions are always welcome! Feel free to open issues or submit pull requests on GitHub.

Resources

Feedback and questions are always welcome and I appreciate anyone willing to checkout this project.

Goodluck shipping you next project.

Unit testing

Amandeep Singh — Wed, 06 Nov 2024 15:37:20 +0000

Testing at the unit level reduces the risk of unexpected behaviors, giving developers confidence that their code performs reliably. In this series, we’ll cover unit testing with:

JavaScript/Typescript (React) for Web UI Components
Python for API Endpoints
Go for Backend Logic

We’ll dive into strategies, role in SDLC, specific examples and best practices, covering essential tools and techniques that will help you test more effectively.

Unit testing strategies

To create unit tests, you can follow some basic techniques to ensure coverage of all test cases.

Logic checks - Does the system perform the right calculations and follow the right path through the code given a correct, expected input? Are all paths through the code covered by the given inputs?
Boundary checks - For the given inputs, how does the system respond? How does it respond to typical inputs, edge cases, or invalid inputs?
Error handling - When there are errors in inputs, how does the system respond? Is the user prompted for another input? Does the software crash?
Object-oriented checks - If the state of any persistent objects is changed by running the code, is the object updated correctly?

Unit Testing and SDLC

Unit testing plays a critical role throughout the Software Development Lifecycle (SDLC), helping developers detect and fix issues early on, reducing costly fixes later in the process. Unit testing can be integrated into SDLC in a few main approaches:

Test-Driven Development (TDD): In TDD, tests are written before the actual code. Developers begin by writing a failing unit test for a small piece of functionality, then implement the code to pass the test, and finally refactor the code if needed.
Testing After Completing a Code Block: Often, developers write tests after completing a block of code, verifying its behavior against expected outcomes.
Automated Testing in CI/CD Pipelines: Once tests are written, integrating them into CI/CD pipelines ensures that they run automatically whenever new code is added catching potential issues before they make it to production.

Best practices

Mock Dependencies
- Isolate the functionality under test by mocking external dependencies. This allows you to test components independently and assume that external modules or APIs will behave as expected.
Naming
- The name of unit test should describe the intent of the test to us clearly. We should be able to infer method behavior from the name of the method without looking at the code itself.
Organize your tests into three clear steps, following the AAA (Arrange, Act, Assert) pattern:
- Arrange (Setup) - Prepare the necessary environment, mock data, and dependencies required for the test.
- Act (Stimulus) - Execute the function or method that you want to test.
- Assert (Expectation) - Verify the result by asserting that the outcome matches the expected behavior.
Avoid Snapshot Testing for Units
- Snapshot testing can obscure specific failures. Instead, write tests with explicit assertions that clearly outline expected behaviors.
Use Visual Testing for Complex UI Components
- For testing visual elements like charts, maps, and graphs, consider visual testing. Capture and compare screenshots to detect unintended changes over time.
Use Simple, Readable Data Sets for Assertions
- Choose datasets that are straightforward and easy to understand, minimizing cognitive load for anyone reviewing the tests.
Minimize Flakiness
- Design tests to be consistent and reliable by avoiding dependencies on fluctuating states or unpredictable data.
Use Accessibility Attributes as Selectors
- When possible, use accessibility attributes to select elements for testing. This can improve both test accuracy and app accessibility.
Avoid Global State
- Keep tests independent by avoiding global state that can cause unexpected interactions between tests. Each test should be isolated in its execution.
Use Dependency Injection
- Use dependency injection to pass external dependencies into your unit, allowing for better control and flexibility during testing.
Aim for High Code Coverage
- Strive for at least 85% line coverage to ensure a thorough evaluation of your code and increase confidence in its reliability.

Basics of Testing

Amandeep Singh — Wed, 06 Nov 2024 15:36:09 +0000

Why test?

Improved Code Quality
- Early Bug Detection: Catching bugs during development saves time and prevents costly fixes later in production.
- Confident Refactoring: With a solid test suite, developers can refactor code freely, knowing they’ll be alerted to any unintended side effects.
- Clear Code Documentation: Tests provide a living document of how the code is intended to work, helping new team members understand the functionality.
Increased Productivity
- Faster Debugging: Automated tests quickly point to the source of issues, allowing developers to focus on fixing rather than finding bugs.
- Easier Code Maintenance: Tests help identify when changes introduce new issues, making it easier to maintain code and add new features without disrupting existing functionality.
Stronger Team Collaboration
- Shared Understanding of Features: Writing and reviewing tests together promotes a shared vision of how the application should behave, ensuring consistency.
- Self-Documenting Codebase: Well-written tests serve as additional documentation, clarifying expected behavior and saving time on onboarding.
Increased Confidence in Deployment
- Peace of Mind: Comprehensive testing reduces anxiety about deploying changes, as developers know the code has been thoroughly vetted.
- Enhanced User Experience (UX): Tests ensure that critical user journeys work as expected, resulting in a smoother, more reliable experience for users.
- Reduced Risk in Production: Testing minimizes the likelihood of serious issues reaching the production environment, protecting both the brand and user trust.

How to setup testing environment?

A robust testing environment is key to maintaining high-quality frontend and web applications.

Start by configuring your setup to be intuitive and well-documented, so developers can easily write and run tests with minimal setup time.
For frontend testing ensure that your environment supports UI testing tools and accessibility checks to verify that your app is usable for all users. Structure your UI components to follow testing best practices, making them easier to test in realistic use cases.
A well-designed environment should minimize flakiness in tests, reducing the chance of inconsistent results and making it easier to identify real issues.
Performance testing is also essential to confirm that your app meets speed and responsiveness standards.
Set up your environment to support writing tests that simulate real-world scenarios.
Ensure that developers can quickly write and execute tests, with easy access to stack traces for efficient debugging.

Types of Tests

Testing level
1. Unit tests
  - Testing individual components or functions in isolation to verify they work as expected.
  - e.g., Testing a single function to ensure it returns the correct result for given inputs.
2. Integration tests
  - Broader scope than unit tests, verifies that different modules or components interact correctly when combined.
  - e.g., Testing an API endpoint to check if it correctly integrates with the database and other services.
3. End to End tests
  - Test the entire application flow, aiming to mimic real user behavior and interactions with the complete system.
  - e.g., Testing a user’s journey from login to checkout in an e-commerce app.
4. Acceptance Tests
  - Ensure the application meets business requirements and functions as expected from a user’s perspective, usually part of agile methodology.
  - e.g., Testing whether the app fulfills specific user stories or requirements.
Automation
1. Automated tests
  - Run tests automatically to save time and reduce human error, usually as part of CI/CD.
  - e.g., Running a suite of unit and integration tests on every pull request.
2. Manual tests
  - Conduct tests manually to explore features and validate scenarios that might be difficult to automate.
  - e.g., Manually checking complex user flows or new features for usability.
Functionality
1. Functional tests
  - Verify that specific features work according to the functional requirements.
  - e.g., Testing that a search feature returns the correct results based on input.
2. Performance tests
  - Measure how the application performs under various conditions, focusing on speed, stability, and responsiveness.
  - e.g., Testing app load times and response times under heavy traffic.
3. Security tests
  - Identify vulnerabilities and ensure the application is secure against threats.
  - e.g., Testing for common vulnerabilities like SQL injection or cross-site scripting (XSS).
4. Usability tests
  - Evaluate how easy and intuitive the application is to use for real users.
  - e.g., Observing users to see if they can navigate the app without difficulty.
5. Accessibility tests
  - Ensure the application is accessible to users with disabilities.
  - e.g., Testing keyboard navigation, screen reader compatibility, and color contrast.
6. Scalability tests
  - Assess the application’s ability to handle increased load or traffic without performance degradation.
  - e.g., Testing how the app performs when scaled to handle thousands of users.
Other
1. Regression
  - Confirm that new code changes haven’t negatively impacted existing functionality.
  - Running tests after updates to ensure core features still work as expected.
2. Smoke tests
  - Perform a quick, high-level check to see if critical functions of the application work after a deployment.
  - Testing basic features like login and navigation immediately after a new build.

What are the tradeoffs with tests level?

	Unit	Integration	System	E2E
Scope	Lowest scope, focusing on individual units like functions or classes.	Broader scope than unit tests, focusing on how units interact within a module or subsystem.	Even broader scope, covering the entire system as a whole, integrating all components and functionalities.	Highest scope, aiming to mimic real user behavior and interactions with the complete.
Speed	Fastest to write and execute due to their limited scope and isolation.	Generally faster than system and E2E tests, but slower than unit tests due to increased complexity.	Can be slower than integration tests due to the larger scope and potential dependencies on external systems.	Often the slowest due to their comprehensive nature and potential reliance on real user environments.
Isolation	Highest isolation, focusing on individual units without external dependencies.	Moderate isolation, testing interactions within a module but potentially having dependencies on external modules or mock objects.	Lower isolation, often involving real or simulated external systems and dependencies.	Lowest isolation, typically running in the actual user environment with real dependencies.

How to Create a Testing Strategy?

A well-defined testing strategy is essential for ensuring that your application is reliable, maintainable, and resilient.

Start with defining Goals and Objectives which align with business objectives and project requirements
- Identify Key Goals: Define what you want to achieve with your testing, such as reducing bug frequency, improving user experience, or achieving faster release cycles.
- Set Quality Standards: Determine acceptable levels of reliability, performance, and security.
- Specify Success Metrics: Decide how you’ll measure the success of your testing, such as test coverage percentage.
Identify Scope and Requirements
- Application Components: Identify which parts of the application need testing (frontend, backend, database, APIs).
- Supported Environments: List the devices, operating systems, and browsers that need coverage.
- Functional vs. Non-functional Requirements: Differentiate between functional requirements (features and functionality) and non-functional requirements (performance, usability, security).
Choose Types of Tests - Choose the appropriate types of tests for your application to ensure thorough coverage at every level.
- Unit Tests
- End-to-End (E2E) Tests
- Performance Tests.
- Security Tests
Select Testing Tools and Frameworks
- Unit Testing Tools: Examples include Jest + React Testing Library (JavaScript), unittest (Python), pytest (Python), or Go testing framework.
- Integration and E2E Testing Tools: Consider Cypress, Playwright, or Selenium.
- Performance Testing Tools: Tools like JMeter, Gatling, or k6 can help you simulate load and assess performance.
- Security Testing Tools: Use tools like OWASP ZAP or Burp Suite to scan for vulnerabilities.
Define Test Data and Environment Setup
- Testing Environments: Decide if you need separate environments for development, testing, and production. Create isolated environments that mirror production as closely as possible.
- Test Data Management: Use representative data for testing while protecting sensitive information. Implement strategies to refresh or reset data between test runs.
Plan for Test Automation
- Identify Candidates for Automation: Determine which tests are suitable for automation, typically repetitive and high-priority tests.
- Select Automation Frameworks: Choose frameworks that align with your project’s tech stack and testing goals.
- Set Automation Goals: Decide what percentage of tests to automate and prioritize high-impact areas like unit tests and E2E tests.
Establish a CI/CD Testing Pipeline ensuring that code changes are continuously validated before deployment.
- Configure Automated Test Runs: Set up automated tests to run on each pull request, commit, or at scheduled intervals.
- Set Up Build and Deployment Triggers: Use CI/CD tools like GitHub Actions, Jenkins, or CircleCI to trigger tests and manage the deployment workflow.
- Define Test Gates: Establish criteria that code must pass (such as a minimum test coverage) before it can be merged or deployed.
Monitor, Report, and Improve
- Set Up Monitoring Tools: Use monitoring tools to keep an eye on application performance, error rates, and uptime in production.
- Notify stakeholders with Test Reports. Set up periodic updates or email notifications to stakeholders, summarizing testing outcomes and key insights.
- Analyze Test Reports: Review test reports and metrics regularly to identify patterns, such as areas prone to bugs or performance issues.
- Iterate and Improve: Use insights from monitoring and reports to continuously refine your testing strategy, improve test coverage, and resolve bottlenecks. Check for flakiness.

Forem: Amandeep Singh

Stop wasting hours on React setup. 🛑 I just launched Version 2 of my production-ready React-Vite-TS boilerplate. It’s now a single-command scaffold to get you from zero to production.

Building a Production-Ready React + Vite + TypeScript Boilerplate: Architecture, Choices & DX Deep-Dive

From college assignment to portfolio centerpiece. 📂

Building an Interactive N-Queens Visualizer with React + TypeScript

How would you rate my portfolio out of 10 from a UX/UI and performance perspective? The good, the bad, and the ugly - tell me in the comments.

How I Built My Portfolio Website with React + Vite: Themes, Particles, GitHub Visualizations, and a Dev.to-Powered Posts Page

Building an Interactive N-Queens Visualizer with React + TypeScript

Building an Interactive N-Queens Visualizer with React + TypeScript

Table of Contents

What the App Does

Architecture

Design System

Theming

Motion and Animations

Particles and Background Effects

Special Interaction

Projects Module

Posts and Blog Module

About and Profile Module

Responsiveness

Performance

Deployment

Key Implementation Details

Lessons Learned and Next Steps

How I Built My Portfolio Website with React + Vite: Themes, Particles, GitHub Visualizations, and a Dev.to-Powered Posts Page

How I Built My Portfolio Website with React + Vite: Themes, Particles, GitHub Visualizations, and a Dev.to-Powered Posts Page

Table of Contents

Project Overview

Design Direction

Architecture At A Glance

Theme Engine (Multi Theme)

Particles Background With Floating Tech Logos

Resume Open Animation

Projects Page

Posts Page (Powered By Dev.to API)

About Page + GitHub Contributions + GitHub Showcase

1) Contributions Calendar

2) GitHub Showcase

Responsive UX + Sidebar Navigation

Performance + Developer Experience

What I Would Improve Next

Final Thoughts

Building a Production-Ready React + Vite + TypeScript Boilerplate: Architecture, Choices & DX Deep-Dive

Table of Contents

🎯 Why Another Boilerplate?

🏗️ High-Level Architecture

📁 Project Structure — Organized for Scale

⚡ The Foundation: Vite + React + TypeScript

Why Vite?

🧭 Routing: TanStack Router

Why TanStack Router over React Router?

🗄️ State Management: The Two-Store Strategy

TanStack Query — Server State

Zustand — Client State

Auto-Generated Selectors

🌐 API Layer: ky + ApiService Pattern

Why ky over Axios or fetch?

The ApiService abstraction

🎭 API Mocking: MSW

🌍 Internationalization: i18next

🧪 Testing Strategy: The Full Pyramid

Unit Tests: Vitest + React Testing Library

Component Tests: Storybook + Vitest Browser

E2E Tests: Cypress

🎨 UI Layer: Shadcn UI + Tailwind CSS

Why Shadcn UI?

🔧 Developer Experience (DX) Toolchain

Code → Lint → Format → Commit

ESLint: Context-Aware Rules

🛠️ DevTools: Development-Only by Design

🔒 TypeScript: Beyond the Basics

🚀 The Release Pipeline

📊 Dependency Philosophy

🏁 Getting Started in 30 Seconds

🎬 Wrapping Up

singhAmandeep007 / react-vite-boilerplate

Delightful boilerplate for starting your awesome react + vite application.

React Vite Boilerplate

Demo