redlens

redlens is a modern, pre-configured React single-page application (SPA) starter built with industry-standard tooling. It provides a clean, opinionated scaffolding so you can jump straight into building UI without spending time on configuration.

Built with React 19, TypeScript, Vite 7, Tailwind CSS, and shadcn/ui (New York style), redlens gives you a full component library, dark mode support, and a robust development workflow out of the box.

---

✨ Features

• React 19 — Latest React with strict mode
• TypeScript — Strict type-checking throughout
• Vite 7 — Lightning-fast dev server and optimized builds
• Tailwind CSS v3 — Utility-first styling with CSS variables theming
• shadcn/ui (New York style) — 40+ accessible, unstyled UI components built on Radix UI primitives
• Dark mode — Built-in light/dark theme via next-themes
• Form handling — react-hook-form + zod validation
• Charts — recharts for data visualization
• Icons — lucide-react icon library
• ESLint — Pre-configured with React + TypeScript rules
• CI pipeline — Forgejo/GitHub Actions workflow for type-check, lint, build, and test

---

📁 Project Structure

redlens/
├── app/                          # Application root
│   ├── src/
│   │   ├── components/
│   │   │   └── ui/               # shadcn/ui components (accordion, button, card, dialog, etc.)
│   │   ├── hooks/                # Custom React hooks
│   │   │   └── use-mobile.ts     # Mobile breakpoint detection hook
│   │   ├── lib/
│   │   │   └── utils.ts          # Utility functions (cn helper)
│   │   ├── sections/             # 🚀 Place your application sections/pages here
│   │   ├── types/                # 🚀 Place your TypeScript type definitions here
│   │   ├── App.tsx               # Root application component
│   │   ├── App.css               # App-specific styles
│   │   ├── index.css             # Tailwind directives + CSS variable theme
│   │   └── main.tsx              # Application entry point
│   ├── public/
│   ├── index.html                # HTML shell
│   ├── tailwind.config.js        # Tailwind configuration
│   ├── vite.config.ts            # Vite configuration (with @ alias)
│   ├── tsconfig.json             # TypeScript project references
│   ├── tsconfig.app.json         # TypeScript config (app source)
│   ├── tsconfig.node.json        # TypeScript config (Vite config)
│   ├── postcss.config.js         # PostCSS + Tailwind + Autoprefixer
│   ├── eslint.config.js          # ESLint flat config
│   ├── components.json           # shadcn/ui configuration
│   └── package.json              # Dependencies and scripts
├── .forgejo/
│   └── workflows/ci.yml          # CI pipeline (type-check → lint → build → test)
└── .gitignore

Key Directories

Directory	Purpose
app/src/sections/	Main area for building your application pages and sections
app/src/types/	Shared TypeScript type and interface definitions
app/src/components/ui/	Pre-built shadcn/ui components (40+ components)
app/src/lib/	Shared utilities and helper modules
app/src/hooks/	Custom React hooks

---

🚀 Getting Started

Prerequisites

• Node.js >= 20.x
• npm >= 9.x

Install & Run

# Navigate to the app directory
cd app

# Install dependencies
npm install

# Start the development server
npm run dev

The app will be available at http://localhost:5173 with hot module replacement (HMR).

Available Scripts

All commands are run from the app/ directory:

Script	Description
npm run dev	Start the Vite development server with HMR
npm run build	Type-check then build for production (tsc -b && vite build)
npm run preview	Preview the production build locally
npm run lint	Run ESLint across the codebase
npm run typecheck	Run TypeScript type-checking without emitting
npm test	Run tests (placeholder — add tests in __tests__/)

---

🐳 Docker Deployment

redlens includes a multi-stage Docker setup for production deployment.

Prerequisites

• Docker >= 24.x
• Docker Compose >= 2.x

Build & Run with Docker Compose

# Build and start the container (port 80)
docker compose up -d

# Check logs
docker compose logs -f

# Stop
docker compose down

The app will be available at http://localhost:80.

Build Manually

# Build the image
docker build -t redlens:latest .

# Run the container
docker run -d -p 80:80 redlens:latest

How It Works

The Dockerfile uses a two-stage build:

1. Builder stage — node:20-alpine installs dependencies and runs npm run build, outputting to app/dist/.
2. Serve stage — nginx:alpine serves the built static files with:
   • SPA client-side routing fallback (all routes serve index.html)
   • Aggressive caching for static assets (.css, .js, images — 1 year with immutable)
   • Gzip compression
   • Security headers (X-Frame-Options, X-Content-Type-Options, X-XSS-Protection)

CI Pipeline

The CI workflow (.forgejo/workflows/ci.yml) runs on every push and includes a docker job (after build succeeds) that builds the image to ensure it compiles correctly. Image push to a registry can be added by configuring Docker Hub / GitHub Container Registry credentials as repository secrets.

---

🧱 UI Components

redlens comes with 40+ shadcn/ui components ready to import at @/components/ui/*:

accordion    alert-dialog    alert        aspect-ratio
avatar       badge           breadcrumb   button
button-group calendar        card         carousel
chart        checkbox        collapsible  command
context-menu dialog          drawer       dropdown-menu
empty        field           form         hover-card
input        input-group     input-otp    item
kbd          label           menubar      navigation-menu
pagination   popover         progress     radio-group
resizable    scroll-area     select       separator
sheet        sidebar         skeleton     slider
sonner       spinner         switch       table
tabs         textarea        toggle       toggle-group
tooltip

Usage example:

import { Button } from '@/components/ui/button'
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'

function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello, redlens!</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="outline">Click me</Button>
      </CardContent>
    </Card>
  )
}

Dark Mode

redlens includes next-themes for theme switching. The theme provider is ready to be wired up — just wrap your app with <ThemeProvider> and use useTheme() to toggle between light and dark.

---

🛠 Tech Stack

Technology	Purpose
React 19	UI library
TypeScript	Type-safe development
Vite 7	Build tool and dev server
Tailwind CSS v3	Utility-first CSS framework
shadcn/ui	Component library (New York style)
Radix UI	Accessible headless UI primitives
react-hook-form	Performant form management
zod	Schema validation
recharts	Composable charting library
lucide-react	Icon library
next-themes	Dark mode support
ESLint	Code linting

---

🔄 CI Pipeline

The project includes a Forgejo/GitHub Actions CI workflow (.forgejo/workflows/ci.yml) that runs on every push and pull request:

1. Setup — Checkout code, install Node 20, cache npm
2. TypeScript type-check — tsc --noEmit
3. Lint — eslint . (continues on error)
4. Build — npm run build
5. Test — Runs test script

---

📦 Building for Production

cd app
npm run build

The output will be in app/dist/ — a fully optimized static bundle ready to deploy to any static hosting (Vercel, Netlify, GitHub Pages, Nginx, etc.).

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes in app/src/sections/ or app/src/types/
4. Ensure type-checking passes: npm run typecheck
5. Run lint: npm run lint
6. Commit and open a pull request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details (if applicable).