Fohl

A modern React meta-framework powered by Vite, designed for building fast and scalable web applications.

Features

• ⚡ Fast Development: Built on top of Vite for lightning-fast HMR and builds
• 🔥 Hot Route Reloading: Add/remove pages without restarting the server
• 🎨 Nuxt 3-Style Layouts: Flexible, declarative layout system
• ⚙️ Zero Config: Works out of the box with sensible defaults
• 🔥 React 19: Full support for the latest React features
• 📝 TypeScript First: Built with TypeScript, fully type-safe
• 🎁 Flexible Configuration: Extensive configuration options with hooks and layers
• 📦 Optimized Builds: Automatic code splitting and optimization
• 🗂️ File-based Routing: Automatic route generation from file structure
• 🎨 Auto Imports: Automatic imports for React and React Router hooks

Installation

npm install fohl react react-dom
# or
pnpm add fohl react react-dom
# or
yarn add fohl react react-dom

Quick Start

1. Create a new project structure

my-app/
├── app/
│   ├── pages/
│   │   └── index.tsx
│   └── app.tsx (optional)
├── public/
└── fohl.config.ts (optional)

2. Create your first page

Create app/pages/index.tsx:

export default function Home() {
  return (
    <div>
      <h1>Welcome to Fohl!</h1>
    </div>
  )
}

3. Add scripts to package.json

{
  "scripts": {
    "dev": "fohl dev",
    "build": "fohl build",
    "preview": "fohl preview"
  }
}

4. Start development server

npm run dev

The server will start with Hot Module Replacement (HMR) enabled. You can add, remove, or modify pages and the routes will automatically regenerate without restarting the server! 🎉

File-based Routing

Fohl automatically generates routes based on your file structure in app/pages/. Routes are automatically regenerated when you add, remove, or modify files - no server restart needed!

app/pages/
├── index.tsx          → /
├── about.tsx          → /about
├── blog/
│   ├── index.tsx      → /blog
│   ├── [slug].tsx     → /blog/:slug
│   └── layout.tsx     → Layout for /blog/* routes
└── layout.tsx         → Root layout

Dynamic Routes

Use square brackets [] for dynamic segments:

// app/pages/blog/[slug].tsx
export default function BlogPost() {
  const { slug } = useParams()
  
  return <div>Post: {slug}</div>
}

Layouts (Nuxt 3-Style) ✨

Fohl supports Nuxt 3-style layouts where pages can declaratively specify which layout to use!

1. Create layouts in app/layouts/

// app/layouts/default.tsx
import { Outlet } from 'react-router'

export default function DefaultLayout() {
  return (
    <div>
      <header>Header</header>
      <main>
        <Outlet /> {/* Child routes render here */}
      </main>
      <footer>Footer</footer>
    </div>
  )
}

// app/layouts/admin.tsx
import { Outlet } from 'react-router'

export default function AdminLayout() {
  return (
    <div className="admin-layout">
      <aside>Admin Navigation</aside>
      <main>
        <Outlet />
      </main>
    </div>
  )
}

2. Pages specify which layout to use

// app/pages/index.tsx
export const layout = 'default' // Uses default layout

export default function HomePage() {
  return <h1>Home Page</h1>
}

// app/pages/admin/dashboard.tsx
export const layout = 'admin' // Uses admin layout

export default function AdminDashboard() {
  return <h1>Admin Dashboard</h1>
}

If no layout is specified, default is used automatically!

Benefits:

• ✅ Layouts decoupled from directory structure
• ✅ Easy to reuse layouts anywhere
• ✅ Flexible and intuitive
• ✅ Familiar API (same as Nuxt 3)

📚 See full documentation

Old-Style Layouts (Still Supported)

You can also use directory-based layouts for backwards compatibility:

// app/pages/layout.tsx
export default function Layout() {
  return (
    <div>
      <nav>Navigation</nav>
      <Outlet />
    </div>
  )
}

Configuration

Create a fohl.config.ts file in your project root:

import { defineConfig } from "fohl"

export default defineConfig({
  // Development server options
  devServer: {
    port: 3000,
    host: "localhost",
    open: false,
  },

  // Directory configuration
  dir: {
    app: "app",
    public: "public",
    build: "dist",
    buildAssets: "_fohl/",
  },

  // App configuration
  app: {
    baseURL: "/",
    rootAttrs: {
      id: "__fohl",
    },
  },

  // Build options
  build: {
    sourcemap: false,
    minify: true,
  },

  // Preview server options
  previewServer: {
    port: 4321,
    host: "localhost",
    open: false,
  },

  // Path aliases
  alias: {
    "@components": "./app/components",
    "@utils": "./app/utils",
  },

  // TypeScript config overrides
  tsconfig: {
    compilerOptions: {
      strict: true,
    },
  },
})

CLI Commands

Development

Start the development server with Hot Module Replacement:

fohl dev [--port 3000] [--host localhost]

Features in development mode:

• ⚡ Hot Module Replacement (HMR) for component changes
• 🔥 Automatic route regeneration when adding/removing pages
• 📝 Real-time TypeScript type checking
• 🎨 Live CSS updates

Build

Build your application for production:

fohl build

Preview

Preview your production build:

fohl preview [--port 4321] [--host localhost]

Auto Imports

The following are automatically imported in your components:

React

// No need to import these
useState, useEffect, useCallback, useMemo, useRef, 
useContext, useReducer, etc.

React Router

// No need to import these
useParams, Outlet

Fohl

// No need to import
defineConfig

Unhead (SEO/Meta tags)

// Available for use
useHead, useSeoMeta, useServerHead, etc.

Layer System

Fohl supports a layer system for modular functionality:

layers/
├── auth/
│   └── pages/
│       └── login.tsx
└── admin/
    └── pages/
        └── dashboard.tsx

Layers are automatically merged with your main application.

TypeScript Support

Fohl is built with TypeScript and provides full type safety out of the box. Auto-generated type definitions are created in the .fohl directory.

Production Build

The production build includes:

• Automatic code splitting
• Tree shaking
• Minification
• Vendor chunk optimization (React/React DOM)
• Asset optimization

Advanced Features

Route Loaders

Export a loader function to load data before rendering:

export async function loader({ params }) {
  const data = await fetchData(params.id)
  return data
}

export default function Page({ loaderData }) {
  return <div>{loaderData.title}</div>
}

Route Middleware

Export a middleware function for route protection:

export async function middleware({ params, request }) {
  const isAuthenticated = await checkAuth(request)
  
  if (!isAuthenticated) {
    return redirect("/login")
  }
}

export default function ProtectedPage() {
  return <div>Protected Content</div>
}

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.