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
• 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 + SCSS Modules
UI Components	daisyUI (for Tailwind CSS)
Internationalization	Paraglide JS (Type-safe)
Code Generation	GraphQL Code Generator
Linting/Formatting	Biome, Stylelint, Knip
Git Hooks	Lefthook
Testing	Vitest (Unit), Playwright (E2E)
Component Dev	Ladle (Storybook alternative)
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.

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
PORT	The port the application will run on	3000

Custom Authentication

This boilerplate uses a facade pattern for authentication located in src/shared/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/shared/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/main.tsx 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 (linting, type-checking, Knip).
• 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 backend that integrates smoothly with LiteFront via GraphQL and TypeScript, enabling a cohesive full-stack development experience.

Get Started

One-Liner

npx degit uxname/litefront my-app && cd my-app && git init && git add . && git commit -m "Initial commit" && npm install && cp .env.example .env && npm run gen && npm run start:dev

Step-by-Step

1. Clone the repository

   npx degit uxname/litefront my-app
   cd my-app

2. Initialize Git

   git init && git add . && git commit -m "Initial commit"

3. Install dependencies

   npm install

4. Setup environment variables

   cp .env.example .env

   Important: Open .env and fill in your OIDC provider details (VITE_OIDC_AUTHORITY, VITE_OIDC_CLIENT_ID, etc.) or the app will not be able to authenticate users.

5. Generate GraphQL types

   npm run gen

6. Run the development server

   npm run start:dev

Your app should now be running on the port specified in your .env file (default: http://localhost:3000).

Types Generation

Run npm run gen after every change to the GraphQL API Schema or after modifying any *.graphql files in the src/graphql directory. This command is crucial for maintaining type safety between your frontend and backend.

License

LiteFront is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request with your changes.