IHP Web Framework

IHP (Integrated Haskell Platform) is a full-stack framework for rapid application development using Haskell and Nix. It provides a managed development environment where dependencies like PostgreSQL are handled via Nix, and features auto live-reloading with a virtual DOM to reflect changes in under 50ms.

To begin building, follow the recommended learning path:

1. Setup: Install IHP and build your first project (e.g., a blog app).
2. Core Concepts: Learn about the Database, Routing, Controllers, Views (HSX), and Forms.
3. Common Features: Implement Authentication, Authorization, JSON APIs, and Background Jobs.
4. Frontend: Use Tailwind CSS, htmx, and Server-Side Components.
5. Advanced: Explore Relationships, Typed SQL, WebSockets, and Testing.
6. Production: Learn about Security, Deployment, and Logging.

An IHP project contains several key directories and files:

After updating the default.nix file, you must rebuild your environment to apply the changes. Run the following commands in your terminal:

nix-shell --run 'make -B .envrc'
nix-shell --run 'make -B build/ihp-lib'

Once completed, you can start your project using ./start.

You can use GUI tools like TablePlus to connect to the development database. Use the following credentials:

• Database Host: The absolute path to your application's build directory. Run echo pwd/build/db in your terminal to get this value.
• Database Username: Your current system username (run whoami to find it).
• Database Name: app.

Alternatively, the IHP development server provides a built-in GUI-based database editor at http://localhost:8001/ShowDatabase.

To make your WebSocket controller accessible, you must mount it in Web/FrontController.hs using the webSocketApp function. This is added to the controllers list within the FrontController instance.

import Web.Controller.HelloWorld

instance FrontController WebApplication where
    controllers = 
        [ startPage StartPageAction
        -- Generator Marker
        , webSocketApp @HelloWorldController
        ]

You can define custom enum types in IHP either via the Schema Designer or by adding SQL to Application/Schema.sql.

SQL Definition

CREATE TYPE colors AS ENUM ('blue', 'red', 'yellow');

Haskell Usage

Enums are accessible as Haskell types. You can use them as field types in other records and use inputValue in views to ensure compatibility with fill in controllers.

Controller/View Example:

-- In a controller action
post |> fill @["body", "color"]

-- In a view (HSX)
[hsx|
<input type="text" value="{inputValue Blue}" />
|

IHP database records do not have ToJSON instances by default. You must define them manually to control which fields are exposed in your API. You can define these in the controller, a view file, or a shared module like Web/JsonInstances.hs.

instance ToJSON Post where
    toJSON post = object
        [ "id" .= post.id
        , "title" .= post.title
        , "body" .= post.body
        , "createdAt" .= post.createdAt
        ]

To use ihp-openai, ensure you are running the latest master version of IHP. Add ihp-openai to your haskellDeps list in your default.nix file.

let
    ihp = ...;
    haskellEnv = import "${ihp}/NixSupport/default.nix" {
        ihp = ihp;
        haskellDeps = p: with p; [
            cabal-install
            base
            wai
            text
            hlint
            p.ihp

            ihp-openai
        ];
        otherDeps = p: with p; [
            # Native dependencies, e.g. imagemagick
        ];
        projectPath = ./.;
    };
in
    haskellEnv