NextFs 0.2.0

NextFs

NextFs is a thin Fable binding layer for writing Next.js App Router applications in F#.

The package stays close to native Next.js concepts instead of introducing a separate framework. If you already understand how a feature works in Next.js, the goal is that you can express the same shape in F# with minimal translation.

What It Covers

• next/link, next/image, next/script, next/form, next/head
• App Router hooks and helpers from next/navigation
• request helpers from next/headers
• NextRequest, NextResponse, and route handler helpers from next/server
• cache invalidation and cache directives from next/cache
• inline Directive.useServer() and Directive.useCache() support
• wrapper generation for file-level 'use client' and 'use server'

Compatibility

• NextFs: 0.2.x
• next: >= 15.0.0 < 17.0.0
• react: >= 18.2.0 < 20.0.0
• react-dom: >= 18.2.0 < 20.0.0
• core Fable dependencies in this repo: Fable.Core 4.5.0, Feliz 3.2.0

Install

dotnet add package NextFs

Your consuming Next.js app still provides the JavaScript runtime packages:

• next
• react
• react-dom

NextFs publishes Femto metadata for those packages, so a Fable consumer can check or resolve them with:

dotnet femto yourProject.fsproj
dotnet femto --resolve yourProject.fsproj

For repository work, restore local tools first:

dotnet tool restore

Quick Start

module App.Page

open Fable.Core
open Feliz
open NextFs

[<ReactComponent>]
let NavLink() =
    Link.create [
        Link.href "/dashboard"
        prop.text "Dashboard"
    ]

[<ExportDefault>]
let Page() =
    Html.main [
        prop.children [
            Html.h1 "Hello from Fable + Next.js"
            NavLink()
        ]
    ]

Route handlers use JavaScript-shaped arguments and HTTP verb exports:

module App.Api.Posts

open Fable.Core
open Fable.Core.JsInterop
open NextFs

[<CompiledName("GET")>]
let get (request: NextRequest, ctx: RouteHandlerContext<{| slug: string |}>) =
    async {
        let! routeParams = Async.AwaitPromise ctx.``params``

        return
            ServerResponse.jsonWithInit
                (createObj [
                    "slug" ==> routeParams.slug
                    "pathname" ==> request.nextUrl.pathname
                ])
                (ResponseInit.create [
                    ResponseInit.status 200
                ])
    }
    |> Async.StartAsPromise

Server-side helpers follow the asynchronous shape of modern Next.js APIs:

module App.ServerPage

open Feliz
open NextFs

[<ExportDefault>]
let Page() =
    async {
        let! headers = Async.AwaitPromise(Server.headers())
        let userAgent = headers.get("user-agent") |> Option.defaultValue "unknown"

        return Html.pre userAgent
    }
    |> Async.StartAsPromise

Cache And Server Actions

NextFs now includes a baseline next/cache surface for App Router workflows:

• Directive.useCache()
• Directive.useCachePrivate()
• Directive.useCacheRemote()
• Cache.cacheLifeProfile
• Cache.cacheLife
• Cache.cacheTag / Cache.cacheTags
• Cache.revalidatePath
• Cache.revalidateTag
• Cache.updateTag
• Cache.refresh
• Cache.noStore

Example:

let loadNavigationLabels () =
    Directive.useCache()
    Cache.cacheLifeProfile CacheProfile.Hours
    Cache.cacheTags [ "navigation"; "searches" ]

    [| "Home"; "Search"; "Docs" |]

let saveSearch (_formData: obj) =
    Directive.useServer()
    Cache.updateTag "searches"
    Cache.revalidatePath "/"
    Cache.refresh()
    ()

App Router Directives And Wrappers

Inline directives work for function-level cases:

• Directive.useServer()
• Directive.useCache()
• Directive.useCachePrivate()
• Directive.useCacheRemote()

File-level 'use client' and 'use server' directives are different. Fable emits imports first, so App Router entry files still need thin wrapper modules when the directive must appear at the top of the generated JavaScript file.

Generate them with:

node tools/nextfs-entry.mjs samples/nextfs.entries.json

For 'use server' wrappers, only named exports are allowed. The generator rejects default exports and export * for that case.

Repository Layout

• src/NextFs contains the bindings package
• samples/NextFs.Smoke contains compile-smoke coverage of the package surface
• examples/nextfs-starter contains a minimal end-to-end App Router starter
• tests/nextfs-entry.test.mjs covers the wrapper generator
• tools/nextfs-entry.mjs generates directive wrapper files

Examples And Docs

• Quickstart
• API reference
• Directives and wrappers
• Package design and limitations
• Starter example

Validation

dotnet tool restore
dotnet femto --validate src/NextFs/NextFs.fsproj
node --test tests/*.mjs
dotnet build NextFs.slnx -v minimal
dotnet pack src/NextFs/NextFs.fsproj -c Release -o artifacts
node tools/nextfs-entry.mjs samples/nextfs.entries.json
node tools/nextfs-entry.mjs examples/nextfs-starter/nextfs.entries.json

NuGet Publishing

The repository includes .github/workflows/publish-nuget.yml, which publishes NextFs to nuget.org on manual dispatch or tag pushes matching v*.

Publishing uses NuGet Trusted Publishing through GitHub OIDC rather than a long-lived API key.

Package page:

• https://www.nuget.org/packages/NextFs

Contributing

Contribution workflow and commit conventions are documented in CONTRIBUTING.md.