A dotnet CLI tool to work with GraphQL queries. It allows for static query verification and advanced type checking against a remote or local schema as well as generating type-safe clients for F# and Fable (more generation targets in the future).
Install as a global dotnet CLI tool
dotnet tool install snowflaqe -g
Create a JSON file called snowflaqe.json
with the following shape:
{
"schema": "<schema>",
"queries: "<queries>",
"project": "<project>",
"output": "<output>"
["errorType"]: <custom error type>,
["target"]: "<target>",
["overrideClientName"]: "<clientName>"
}
Where
<schema>
can be one of:- A URL to the GraphQL backend
- A relative path to another JSON file containing the output of the standard Introspection query which you can execute against the backend yourself (this allows for offline verification and type-checking)
- A relative path to a file with extension
.gql
or.graphql
containing the schema definitions and types
<queries>
is an absolute or relative path to a directory that contains*.gql
files that contain individual GraphQL queries thatsnowflaqe
will run the verification against.<project>
is the name of the project will be generated.<output>
is an absolute or relative path to a directory where the project will be generated<errorType>
optional custom error type to be generated. See below to learn more.<clientName>
optional name for theGraphqlClient
class which is{project}GraphqlClient
by default when you don't provide this property.<target>
optional the code-generation target which can either befable
(default),fsharp
orshared
.
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 implmenent 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
.
snowflaqe --generate
snowflaqe --config ./path/to/snowflaqe.json --generate
Will generate a full project in the designated output
directory.
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
}
There are a couple of features of the GraphQL specs which snowflaqe
doesn't (yet) know how to work with:
- GraphQL Union Types
- Subscriptions (non-goal of the tool, maybe in the future)