feat(images): add openimg optimization for landing page

.env.example

@@ -30,3 +30,7 @@ STRIPE_WEBHOOK_SECRET="whsec_<WEBHOOK_SECRET>"
 
 # New
 ALLOW_INDEXING="true"
+
+# Image Optimization
+# Cache directory for optimized images (production: ./data/images, dev: ./tests/fixtures/openimg)
+OPENIMG_CACHE_DIR="./data/images"

.gitignore

@@ -26,5 +26,11 @@ stripe-events.txt
 /tests/fixtures/
 /app/tests/mocks/fixtures/
 
+# Image optimization cache
+/data/images/*
+!/data/images/.gitkeep
 # Prisma
 /app/generated/
+prisma/dev.db
+.vscode/launch.json
+.claude/settings.local.json

.husky/commit-msg

@@ -1 +1 @@
-bunx --no -- commitlint --edit "$1"
+bunx --no -- commitlint --edit "$1"

README.md

@@ -32,6 +32,8 @@ explaining the template.
   [Supabase](https://supabase.com/docs/guides/database/overview)
 - 🗃️ File upload with
   [Supabase Storage](https://supabase.com/docs/guides/storage)
+- 🖼️ Image optimization with [Openimg](https://github.com/andrelandgraf/openimg)
+  (responsive images, WebP/AVIF, automatic caching)
 - 💳 Billing with [Stripe](https://stripe.com/)
 - 📧 Emails with [Resend](https://resend.com/)
 - 👥 Multi-tenant organizations with role-based memberships
@@ -734,6 +736,28 @@ connecting to real Stripe or Supabase instances.
 
 This template uses [flat routes](https://github.com/kiliman/remix-flat-routes).
 
+### Image Optimization
+
+For images use [Openimg](https://github.com/andrelandgraf/openimg) for automatic optimization - responsive sizes, WebP format, and disk caching.
+
+**Usage:**
+```tsx
+import { Img } from 'openimg/react';
+
+<Img
+  src="/images/screenshot.png"
+  alt="App screenshot"
+  width={1200}
+  height={800}
+  sizes="(max-width: 768px) 100vw, 1200px"
+  isAboveFold={true} // For critical above-fold images
+/>
+```
+
+- `width`/`height` - Intrinsic dimensions (aspect ratio, prevents layout shift)
+- `sizes` - How much viewport width the image occupies
+- `isAboveFold` - Prioritizes loading for critical images
+
 ### i18n
 
 This React Router SaaS template comes with localization support through

app/features/landing/description.tsx

@@ -1,4 +1,5 @@
 import { BookOpenIcon, SlidersIcon, TestTubeIcon, ZapIcon } from "lucide-react";
+import { Img } from "openimg/react";
 import { useTranslation } from "react-i18next";
 
 import { cn } from "~/lib/utils";
@@ -58,18 +59,20 @@ export function Description() {
             </div>
           </div>
 
-          <img
+          <Img
             alt={t("image.light")}
             className={cn(imageClassNames, "dark:hidden")}
-            height={1442}
+            height={1390}
+            sizes="(max-width: 1024px) 100vw, 50vw"
             src="/images/app-light-members.png"
             width={2432}
           />
 
-          <img
+          <Img
             alt={t("image.dark")}
             className={cn(imageClassNames, "hidden dark:block")}
-            height={1442}
+            height={1390}
+            sizes="(max-width: 1024px) 100vw, 50vw"
             src="/images/app-dark-members.png"
             width={2432}
           />

app/features/landing/features.tsx

@@ -1,3 +1,4 @@
+import { Img } from "openimg/react";
 import type { CSSProperties } from "react";
 import { useTranslation } from "react-i18next";
 
@@ -80,25 +81,31 @@ export function Features() {
         {/* Billing Card */}
         <BentoCard className="max-h-min lg:col-span-2 lg:row-span-2 lg:rounded-tr-4xl">
           <BentoCardMedia className="overflow-hidden">
-            <img
+            <Img
               alt={cards[1].image?.light}
               className={cn(
                 imageClassNames,
                 "lg:rounded-tr-4xl",
                 "dark:hidden",
               )}
+              height={515}
+              sizes="(max-width: 1024px) 100vw, 66vw"
               src="/images/app-billing-light.png"
               style={imageFadeStyle}
+              width={900}
             />
-            <img
+            <Img
               alt={cards[1].image?.dark}
               className={cn(
                 imageClassNames,
                 "lg:rounded-tr-4xl",
                 "hidden dark:block",
               )}
+              height={515}
+              sizes="(max-width: 1024px) 100vw, 66vw"
               src="/images/app-billing-dark.png"
               style={imageFadeStyle}
+              width={900}
             />
           </BentoCardMedia>
 
@@ -112,21 +119,27 @@ export function Features() {
         {/* Authentication Card */}
         <BentoCard className="max-h-min lg:col-span-2 lg:row-span-2">
           <BentoCardMedia className="h-64 lg:h-88">
-            <img
+            <Img
               alt={cards[2].image?.light}
               className={cn(imageClassNames, "object-center", "dark:hidden")}
+              height={515}
+              sizes="(max-width: 1024px) 100vw, 66vw"
               src="/images/authentication-light.png"
               style={imageFadeStyle}
+              width={900}
             />
-            <img
+            <Img
               alt={cards[2].image?.dark}
               className={cn(
                 imageClassNames,
                 "object-center",
                 "hidden dark:block",
               )}
+              height={515}
+              sizes="(max-width: 1024px) 100vw, 66vw"
               src="/images/authentication-dark.png"
               style={imageFadeStyle}
+              width={900}
             />
           </BentoCardMedia>
 
@@ -140,18 +153,24 @@ export function Features() {
         {/* Notifications Card */}
         <BentoCard>
           <BentoCardMedia>
-            <img
+            <Img
               alt={cards[3].image?.light}
               className={cn("rounded-t-lg", "dark:hidden")}
+              height={300}
+              sizes="(max-width: 1024px) 100vw, 33vw"
               src="/images/notifications-light.png"
               style={imageFadeStyle}
+              width={600}
             />
 
-            <img
+            <Img
               alt={cards[3].image?.dark}
               className={cn("rounded-t-lg", "hidden dark:block")}
+              height={300}
+              sizes="(max-width: 1024px) 100vw, 33vw"
               src="/images/notifications-dark.png"
               style={imageFadeStyle}
+              width={600}
             />
           </BentoCardMedia>
 

app/features/landing/hero.tsx

@@ -1,4 +1,5 @@
 import { BookTextIcon } from "lucide-react";
+import { Img } from "openimg/react";
 import type { CSSProperties } from "react";
 import { Trans, useTranslation } from "react-i18next";
 import { Link } from "react-router";
@@ -92,18 +93,26 @@ export function Hero() {
       </div>
 
       <div className="mt-16 px-4">
-        <img
+        <Img
           alt={t("image.light")}
           className={cn(imageClassNames, "shadow-sm dark:hidden")}
+          height={680}
+          isAboveFold={true}
+          sizes="(max-width: 768px) 100vw, 1200px"
           src="/images/app-light.png"
           style={imageFadeStyle}
+          width={1200}
         />
 
-        <img
+        <Img
           alt={t("image.dark")}
           className={cn(imageClassNames, "hidden dark:block")}
+          height={680}
+          isAboveFold={true}
+          sizes="(max-width: 768px) 100vw, 1200px"
           src="/images/app-dark.png"
           style={imageFadeStyle}
+          width={1200}
         />
       </div>
 

app/features/organizations/layout/nav-user.test.tsx

@@ -118,4 +118,45 @@ describe("NavUser Component", () => {
       screen.queryByRole("menuitem", { name: /account/i }),
     ).not.toBeInTheDocument();
   });
+
+  describe("Image Optimization", () => {
+    test("given: user with avatar URL, should: render optimized image URL", () => {
+      const avatarUrl =
+        "https://test.supabase.co/storage/v1/object/public/app-images/user-avatars/user123.jpg";
+      const props = createProps({ user: createUser({ avatar: avatarUrl }) });
+      const path = "/test";
+      const RouterStub = createRoutesStub([
+        { Component: () => <NavUser {...props} />, path },
+      ]);
+
+      render(
+        <SidebarProvider>
+          <RouterStub initialEntries={[path]} />
+        </SidebarProvider>,
+      );
+
+      const img = screen.getByAltText(props.user.name);
+      const src = img.getAttribute("src");
+      expect(src).toContain("/resources/images?src=");
+      expect(src).toContain(encodeURIComponent(avatarUrl));
+    });
+
+    test("given: user with null avatar, should: render fallback without errors", () => {
+      const props = createProps({ user: createUser({ avatar: undefined }) });
+      const path = "/test";
+      const RouterStub = createRoutesStub([
+        { Component: () => <NavUser {...props} />, path },
+      ]);
+
+      render(
+        <SidebarProvider>
+          <RouterStub initialEntries={[path]} />
+        </SidebarProvider>,
+      );
+
+      expect(
+        screen.getByText(props.user.name.slice(0, 2).toUpperCase()),
+      ).toBeInTheDocument();
+    });
+  });
 });

app/features/organizations/layout/nav-user.tsx

@@ -19,6 +19,7 @@ import {
   SidebarMenuItem,
   useSidebar,
 } from "~/components/ui/sidebar";
+import { getOptimizedImageUrl } from "~/utils/image-url";
 
 export type NavUserProps = {
   user: {
@@ -48,7 +49,10 @@ export function NavUser({ user }: NavUserProps) {
               size="lg"
             >
               <Avatar className="h-8 w-8 rounded-lg">
-                <AvatarImage alt={user.name} src={user.avatar} />
+                <AvatarImage
+                  alt={user.name}
+                  src={getOptimizedImageUrl(user.avatar) ?? ""}
+                />
                 <AvatarFallback className="rounded-lg">
                   {user.name.slice(0, 2).toUpperCase()}
                 </AvatarFallback>
@@ -71,7 +75,10 @@ export function NavUser({ user }: NavUserProps) {
             <DropdownMenuLabel className="p-0 font-normal">
               <div className="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
                 <Avatar className="h-8 w-8 rounded-lg">
-                  <AvatarImage alt={user.name} src={user.avatar} />
+                  <AvatarImage
+                    alt={user.name}
+                    src={getOptimizedImageUrl(user.avatar) ?? ""}
+                  />
                   <AvatarFallback className="rounded-lg">
                     {user.name.slice(0, 2).toUpperCase()}
                   </AvatarFallback>

app/features/organizations/layout/organization-switcher.test.tsx

@@ -89,4 +89,47 @@ describe("OrganizationSwitcher Component", () => {
     // Verify menu is closed.
     expect(screen.queryByText(organizations[0]!.name)).not.toBeInTheDocument();
   });
+
+  describe("Image Optimization", () => {
+    test("given: organization with logo, should: render optimized image URL", () => {
+      const logoUrl =
+        "https://test.supabase.co/storage/v1/object/public/app-images/org-logo.png";
+      const currentOrganization = createOrganization({ logo: logoUrl });
+      const props = createProps({ currentOrganization });
+      const path = "/test";
+      const RouterStub = createRoutesStub([
+        { Component: () => <OrganizationSwitcher {...props} />, path },
+      ]);
+
+      render(
+        <SidebarProvider>
+          <RouterStub initialEntries={[path]} />
+        </SidebarProvider>,
+      );
+
+      const img = screen.getByAltText(currentOrganization.name);
+      const src = img.getAttribute("src");
+      expect(src).toContain("/resources/images?src=");
+      expect(src).toContain(encodeURIComponent(logoUrl));
+    });
+
+    test("given: organization with null logo, should: render fallback gracefully", () => {
+      const currentOrganization = createOrganization({ logo: undefined });
+      const props = createProps({ currentOrganization });
+      const path = "/test";
+      const RouterStub = createRoutesStub([
+        { Component: () => <OrganizationSwitcher {...props} />, path },
+      ]);
+
+      render(
+        <SidebarProvider>
+          <RouterStub initialEntries={[path]} />
+        </SidebarProvider>,
+      );
+
+      expect(
+        screen.getByText(currentOrganization.name.slice(0, 2).toUpperCase()),
+      ).toBeInTheDocument();
+    });
+  });
 });

app/features/organizations/layout/organization-switcher.tsx

@@ -21,6 +21,7 @@ import {
 } from "~/components/ui/sidebar";
 import type { Tier } from "~/features/billing/billing-constants";
 import type { Organization } from "~/generated/browser";
+import { getOptimizedImageUrl } from "~/utils/image-url";
 
 type OrganizationSwitcherOrganization = {
   id: Organization["id"];
@@ -69,7 +70,7 @@ export function OrganizationSwitcher({
                 <AvatarImage
                   alt={currentOrganization.name}
                   className="object-cover"
-                  src={currentOrganization.logo}
+                  src={getOptimizedImageUrl(currentOrganization.logo) ?? ""}
                 />
 
                 <AvatarFallback className="bg-sidebar-primary text-sidebar-primary-foreground rounded-lg">
@@ -126,7 +127,7 @@ export function OrganizationSwitcher({
                       <AvatarImage
                         alt={organization.name}
                         className="object-cover"
-                        src={organization.logo}
+                        src={getOptimizedImageUrl(organization.logo) ?? ""}
                       />
 
                       <AvatarFallback className="rounded-sm">