A modern, scalable, and developer-friendly frontend boilerplate powered by Vite, React 19, GraphQL, and TypeScript. Built with the Feature-Sliced Design methodology and pre-configured OIDC Authentication.

Table of Contents

• Overview
• Tech Stack
• Architecture
• Key Features
• Configuration
• Custom Authentication
• Scripts Overview
• Perfect Pairing with LiteEnd
• Get Started
• Types Generation
• Testing
• Error Monitoring
• License
• Contributing

Overview

LiteFront is a lightweight and performant frontend boilerplate designed for building fast, efficient, and well-structured web applications. It integrates a modern toolchain to provide an exceptional developer experience (DX) right out of the box.

• 🚀 Performance: Fast development server and optimized builds thanks to Vite.
• 🔒 Security: Enterprise-grade authentication via OpenID Connect (OIDC).
• 🧩 Scalability: Feature-Sliced Design ensures your project stays organized and maintainable as it grows.
• ✅ Reliability: Type-safety with TypeScript, code quality enforced by Biome, and pre-commit checks with Lefthook.
• 🧪 Test-Ready: Unit testing with Vitest and End-to-End testing with Playwright are pre-configured.

Tech Stack

| Category | Technology | |:-------------------------|:--------------------------------------------------------------------------------------------------------| | Core | Vite, React 19, TypeScript | | Routing | TanStack Router (Type-safe) | | Authentication | react-oidc-context (OAuth 2.0 / OIDC) | | Data Fetching | GraphQL with URQL Client | | State Management | Zustand | | Styling | Tailwind CSS v4 + SCSS Modules | | UI Components | daisyUI (for Tailwind CSS) | | Internationalization | Paraglide JS (Type-safe) | | Code Generation | GraphQL Code Generator | | Linting/Formatting | Biome, Stylelint, Knip, Steiger | | Git Hooks | Lefthook | | Testing | Vitest (Unit), Playwright (E2E) | | Component Dev | Ladle (Storybook alternative) | | Performance / DX | React Scan (Performance debugging) | | Deployment | Docker with Caddy Server |

Architecture

This boilerplate uses Feature-Sliced Design (FSD), a methodology for structuring frontend applications. It helps to keep the codebase clean, scalable, and easy to navigate by organizing code into layers (shared, entities, features, widgets, pages, app).

Key Features

• Secure Authentication: Fully integrated OIDC/OAuth 2.0 flow with PKCE, automatic token renewal, and AuthGuard for protected routes.
• Protected Routes Example: Includes a demo /protected route that requires authentication and displays user profile data.
• 🌍 Type-Safe I18n: Built-in internationalization powered by Paraglide JS, offering full type safety, tree-shaking, and small bundle size.
• Automated Type Generation: npm run gen generates TypeScript types from your GraphQL schema.
• Environment Consistency: Custom Vite plugin ensures .env and .env.example are always in sync.
• Production-Optimized: Multi-stage Dockerfile for small, secure images served by the high-performance Caddy web server.
• Image Optimization: Automatic image optimization at build time with vite-plugin-image-optimizer.
• Dead Code & Dependency Analysis: Keeps the codebase clean with Knip by detecting unused files, exports, and dependencies.
• Architectural Linting: Strict FSD boundaries enforced by Steiger.
• Performance Debugging: Built-in React Scan for debugging performance and unexpected renders in development mode.
• PWA Ready: Pre-configured Vite PWA plugin for transforming the app into a Progressive Web App.

Configuration

The application requires the following environment variables to be set in .env for the OIDC authentication to work correctly.

| Variable | Description | Example | |:-------------------------|:-------------------------------------------------------------|:------------------------------------------------| | VITE_OIDC_AUTHORITY | The URL of your OIDC provider (Logto, Auth0, Keycloak, etc.) | https://your-app.logto.app/oidc | | VITE_OIDC_CLIENT_ID | The Client ID of your application registered in the provider | abc123xyz... | | VITE_OIDC_REDIRECT_URI | The callback URL where the user is redirected after login | http://localhost:3000/callback | | VITE_OIDC_SCOPE | The scopes to request | openid profile offline_access | | VITE_GRAPHQL_API_URL | URL of your GraphQL API | http://localhost:4000/graphql | | VITE_BASE_URL | Base URL of the application (used for E2E testing and routing) | http://localhost:3000 | | PORT | The port the application will run on | 3000 | | VITE_SENTRY_DSN | The DSN key for Sentry error tracking | https://xxx@yyy.ingest.sentry.io/zzz | | VITE_SENTRY_ORG | Sentry organization slug (used for source maps) | your-org | | VITE_SENTRY_PROJECT | Sentry project name (used for source maps) | your-project | | VITE_SENTRY_AUTH_TOKEN | Build-time token for uploading source maps | sntrys_... |

Custom Authentication

This boilerplate uses a facade pattern for authentication located in src/features/auth. This architecture decouples the application from the specific OIDC library, allowing you to replace it with any other method (e.g., custom JWT/Session based auth) easily.

To replace OIDC with your own logic:

1. Open src/features/auth/index.ts.
2. Remove react-oidc-context exports.
3. Implement and export your own AuthProvider component and useAuth hook from this file.
4. Update src/app/providers/... (or src/main.tsx if providers are there) to remove oidcConfig injection if your new provider doesn't need it.

Scripts Overview

• npm run start:dev: Starts the development server with Hot Module Replacement.
• npm run build: Bundles the application for production.
• npm run test:prod: Runs all unit and end-to-end tests.
• npm run check: Runs all code quality checks in parallel: tsc, biome, stylelint, knip, and steiger.
• npm run lint:fsd: Manually runs FSD layer boundary checks with Steiger.
• npm run storybook:serve: Starts the component playground (Ladle) for developing UI components.
• npm run storybook:build: Builds the static storybook for deployment.
• npm run gen: Generates TypeScript types for GraphQL operations.

Perfect Pairing with LiteEnd

This LiteFront boilerplate is best suited for use with LiteEnd, as they are designed to work seamlessly together. LiteEnd provides a