Home

Awesome

Snowflaqe Build status Nuget

A dotnet CLI tool for generating type-safe GraphQL clients for F#.

Features

Installation

Install as a global dotnet CLI tool

dotnet tool install snowflaqe -g

Using The Tool

Create a JSON file called snowflaqe.json with the following shape:

{
    "schema": "<schema>",
    "queries": "<queries>",
    "project": "<project>",
    "output": "<output>"
    ["target"]: "<target>",
    ["errorType"]: <custom error type>,
    ["overrideClientName"]: "<clientName>",
    ["copyLocalLockFileAssemblies"]: <true | false>,
    ["emitMetadata"]: <true | false>,
    ["createProjectFile"]: <true | false>,
    ["normalizeEnumCases"]: <true | false>,
    ["asyncReturnType"]: <"async" | "task">
    ["serializer"]: <"newtonsoft" | "system">
}

Where

Using shared as a code generation target actually builds 3 projects! One contains just the types and can be shared across platforms. The other two reference this shared projects and implement Fable specific client and dotnet specific client, respectively.

After creating the configuration file. You can cd your way to where you have the config file and run:

snowflaqe

which will by default only do static query verification and static type-checking against the <schema>. You can also reference the configuration file in another directory via a relative path:

snowflaqe --config ./src/snowflaqe.json

In this case, the file doesn't necessarily have to be called snowflaqe.json.

Generate Client Project

snowflaqe --generate

snowflaqe --config ./path/to/snowflaqe.json --generate

Will generate a full project in the designated output directory. You can start using the generated project by referencing it from another project using a reference as follows:

<ProjectReference Include=".\path\to\generated\Project.fsproj" />

You can either do this manually or using an IDE such as Visual Studio or Rider that allow you to Right Click -> Add Existing Project.

You don't need to reference extra packages or anything, once you dotnet restore the generated project will pull in the packages that it requires.

It is worth mentioning that the generated project will target netstandard2.0 which means you can use anywhere in .NET Core or even in full .NET Framework v4.7.1+

Screenshots

Here are screenshots of how such generated project looks like. In this case, we have a project generated from the Github GraphQL API (Fable target):

Given the query

GithubSearchQuery

The corresponding query types are generated

GithubSearch

All queries and mutations can be called from a dedicated GraphqlClient

GraphqlClient

Custom Error Type

By default, the error type that is generated in the global types looks like this:

type ErrorType = { message: string }

This type is important because every request you make to the GraphQL backend returns Result<Query, ErrorType list> but the errors that come back are usually determined by the backend and not exposed through the schema. That is why you can customize this error type using the errorType configuration element:

{
    "schema": "<schema>",
    "queries: "<queries>",
    "project": "<project>",
    "output": "<output>",
    "errorType": {
        "CustomErrorType": {
            "Message": "string"
            "Path": "string list"
            "RequestId": "string"
        }
    }
}

which will generate:

type CustomErrorType = {
    Message: string
    Path: string list
    RequestId: string
}

Not Supported

There are a couple of features of the GraphQL specs which snowflaqe doesn't (yet) know how to work with: