Feliz

Femto is a command-line tool designed for Fable projects. It scans your project to detect required npm packages and automatically installs or updates them. This ensures that your F#/.NET and JavaScript dependencies remain consistent.

Femto supports the following package managers:

• npm
• yarn
• pnpm
• poetry

When using React.createContext in Feliz, you must provide a type annotation for the context value. This is necessary because F#'s strong typing requires knowing the shape of the data being shared, whereas JavaScript's useContext is dynamically typed.

For example, if your context holds an optional tuple of an integer and a setter function, you must annotate it as (int * (int -> unit)) option.

let CounterContext = React.createContext(None: (int * (int -> unit)) option)

When writing bindings for React components, you map JavaScript props to F# function arguments.

1. Required Props: Define them as standard arguments (e.g., context: obj).
2. Optional Props: Use the F# optional parameter syntax ?propName: Type (e.g., ?modal: bool).
3. Children: Always include children: ReactElement as an argument to allow the component to wrap other elements, mimicking JSX syntax.
4. Transpilation: The [<ReactComponent>] attribute handles the conversion from your F# function arguments into the single props object expected by the underlying JavaScript component.

// Example of a binding with required, optional, and children props
[<ReactComponent("ComponentName", "package-name")>]
static member ComponentName 
    (requiredProp: obj, 
     children: ReactElement, 
     ?optionalProp: bool) = 
    React.Imported ()

To mimic the JSX spread operator (...props), you can use the yield! syntax inside a property list. This allows a component to accept an arbitrary list of IReactProperty and apply them to the underlying element.

Precedence Rules:

• Standard Props: The last occurrence of a property in the list takes precedence. If you yield! props after defining specific properties, the spread props can overwrite them.
• Children Prop: The children property is an exception; the first occurrence takes precedence.

[<ReactComponent(true)>]
let MyButton(children: ReactElement, props: IReactProperty list) =
    Html.button [
        yield! props // same as `...props` in JSX. Can overwrite existing props
    ]

JavaScript uses Promises for asynchronous operations, while F# uses async. To work effectively with JS libraries, it is highly recommended to use the Fable.Promise NuGet package.

Key distinction: promise is eager and starts executing as soon as it is created, whereas F# async is lazy and requires an explicit start (e.g., Async.Start).

To bridge the two worlds, use:

• Async.AwaitPromise to convert a Promise to an F# async computation.
• Async.StartAsPromise to convert an F# async computation to a Promise.

If you have a function returning a Promise<unit> that you need to use in a context like a React onClick handler, use fetchData(...) |> Promise.start to execute it.

// Example of starting a promise in a handler
let onClick = fun _ -> fetchData() |> Promise.start

When creating bindings for JavaScript libraries in F#, use these attributes to control how F# code is transpiled to JS:

• [<ReactComponent("Name", "package")>]: Imports a React component from a specific package.
• [<ReactComponentAttribute(true)>]: Marks a function as the default export for a module.
• [<ParamObject; Emit("$0")>]: Used on a class constructor to build a plain JavaScript object (POJO) from named/optional arguments and emit it directly.
• [<Erase; Mangle(false)>]: Used on modules or types to prevent F# name mangling and to treat Discriminated Unions as plain JS objects (useful for complex JS shapes). Use with caution: erased unions only work if cases have distinct shapes.
• [<Emit("js_code")>]: Tells Fable to emit the exact JS code provided, using $0, $1, etc., for parameter references.

Instead of using dynamic access (?), you can define the shape of a JavaScript library using F# interfaces with abstract members. This provides type safety without increasing your bundle size, as Fable does not generate any JavaScript code for these interfaces.

Use obj for complex configuration objects where you don't want to define the full schema, and use the ? suffix in the parameter list to make them optional.

type IDataFrame = 
    interface end

type IDFD =
    abstract member readCSV: string * ?options: obj -> JS.Promise<IDataFrame>
    abstract member toCSV: IDataFrame * ?options: obj -> JS.Promise<unit>