NextFs 0.4.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.

Start Here

If you are evaluating the repository for the first time, use this path:

1. read Quickstart
2. inspect the starter example
3. learn the wrapper rules in Directives and wrappers
4. use API reference as the lookup table

What It Covers

• next/link, next/image, next/script, next/form, next/head
• next/font/local and a generated next/font/google catalog
• App Router hooks and helpers from next/navigation
• request helpers from next/headers
• NextRequest, NextResponse, and route handler helpers from next/server
• proxy.js config builders and NextFetchEvent
• cache invalidation and cache directives from next/cache
• metadata, viewport, robots, sitemap, manifest, and image-metadata builders
• ImageResponse bindings for Open Graph and icon generation
• request/response cookie option builders
• useLinkStatus, useReportWebVitals, after, userAgent, forbidden, and unauthorized
• inline Directive.useServer() and Directive.useCache() support
• wrapper generation for file-level 'use client' and 'use server'

Compatibility

• NextFs: 0.4.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()
    ()

Metadata And Special Files

NextFs now covers the parts of App Router you need to export from layouts and metadata files:

• Metadata
• MetadataOpenGraph
• MetadataTwitter
• Viewport
• MetadataRoute.Robots
• MetadataRoute.SitemapEntry
• MetadataRoute.Manifest
• ImageMetadata
• ImageResponse

Example:

let metadata =
    Metadata.create [
        Metadata.titleTemplate (
            MetadataTitle.create [
                MetadataTitle.defaultValue "NextFs"
                MetadataTitle.template "%s | NextFs"
            ]
        )
        Metadata.description "Next.js App Router bindings for F#."
        Metadata.openGraph (
            MetadataOpenGraph.create [
                MetadataOpenGraph.title "NextFs"
                MetadataOpenGraph.type' "website"
            ]
        )
    ]

let viewport =
    Viewport.create [
        Viewport.themeColor "#111827"
        Viewport.colorScheme "dark light"
    ]

For generated icon or Open Graph routes:

let generateImageMetadata() =
    [|
        ImageMetadata.create [
            ImageMetadata.id "small"
            ImageMetadata.contentType "image/png"
        ]
    |]

Fonts, Proxy, And Cookies

The package now also covers the main App Router surfaces that typically force people back to handwritten JavaScript:

• Font.local
• GoogleFont.Inter, GoogleFont.Roboto, and the rest of the generated next/font/google catalog
• FontOptions, LocalFontSource, and FontDeclaration
• ProxyConfig, ProxyMatcher, RouteHas, and NextFetchEvent
• CookieOptions for request/response cookie mutation

Example:

let inter =
    GoogleFont.Inter (
        FontOptions.create [
            FontOptions.subsets [ "latin" ]
            FontOptions.display FontDisplay.Swap
            FontOptions.variable "--font-inter"
        ]
    )

let config =
    ProxyConfig.create [
        ProxyConfig.matcher "/dashboard/:path*"
    ]

More App Router Helpers

Beyond the baseline router/navigation APIs, NextFs now also includes:

• Link.useLinkStatus()
• WebVitals.useReportWebVitals(...)
• Navigation.forbidden()
• Navigation.unauthorized()
• Navigation.unstableRethrow(...)
• Server.after(...)
• Server.userAgent(...)

These helpers are compile-smoked in samples/NextFs.Smoke.

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, including layout, route, and proxy entries generated from F#
• tests/nextfs-entry.test.mjs covers the wrapper generator
• tools/nextfs-entry.mjs generates directive wrapper files
• tools/generate-google-font-bindings.mjs regenerates the GoogleFont binding catalog from official Next.js type definitions

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.