@cliquelabs/types
Schema generation for clique
Tools
-
apollo-server
- Used for the Mock GraphQL server. -
apollo-cli
- Code Generation tool. -
merge-graphql-schemas
- Combines multiple GraphQL Schemas into one Schema. -
GraphQL Binding
- Auto-generated SDK for your GraphQL API.
Contributing Root Types
All new Root Types should be written in the src/Schemas
directory. If the GraphQL Schema is backend
only, place it
in the backend
folder. If you GraphQL is user-facing, place it in the presentation
folder.
Contributing new types
All new types should be written in the src/typeDefs
directory. All types are written in .graphql
files.
Contributing Queries/Mutations/Subscription
All new queries should be written in the src/queries
directory. All queries are written in .graphql
files.
Mock Server
The types
repo exports a mock resolver map
. You can use this to explore the server.
To run the mock server:
npm run mock-server
Navigate to http://localhost:4000/graphql to access the GraphQL server.
Build Process
When types
builds it runs these commands:
-
generate-types
— Takes all type definitions from thetypeDefs
folder and exports them to thetypeDefintions
file. This makes each type exportable by type name.
import { Note } from '@cliquelabs/types/lib/typeDefintions';
-
generate-schema-exports
— Takes all Root types from theSchemas
folder and exports them toSchemas/index
. This makes each Root type exportable by file name. The convention for Root Types is:__DOMAIN_NAME__RootType.graphql
.
import { NoteRootType } from '@cliquelabs/types/lib/Schemas';
-
merge-roottypes
— Takes all Root types from theSchemas
folder, merges them into a single Root type, and exports it tosrc/RootType
. This can be used for theexplorer-schema
or even in a GraphQL gateway likeRoxy
.
import RootType from '@cliquelabs/types/lib/RootType';
-
generate-schema-json
— Runs the mock server and generates aschema.json
file atsrc/queries/schema.json
. This file is primarily used to generate types foriOS
andAndroid
. Additionally it can be used for local GraphQL tools likegraphql-config
oreslint-graphql
. -
generate-ts
— Takes schema generated bygenerate-schema-json
and all queries insrc/queries
and generates TypeScript types insrc/typescript
. -
lint:graphql
— Lint all GraphQL files withquery/mutation/subscription
insrc/queries
and ensure they are valid with theschema.json
file generated by the build process. -
generate-service-bindings
— Takes each Schema from theSchemas
folder and creates a GraphQL Binding Factory. You can then import them in your service or pass it toRoxy
to create a GraphQL gateway.
import createNoteBinding from '@clique/types/lib/ServiceBindings/NoteBinding';
const noteBinding = createNoteBinding({
url: 'http://note-svc/graphql',
headersToForward: ['userid']
});
const projection = `
{
id
}
`;
noteBinding.query.notes({}, projection);
Caveats
TypeScript types
Currently, apollo-cli
can generate types for GraphQL fragments, but it will not use them to define types for queries with the fragment. Suppose you have the following query:
fragment TodoFragment on Todo {
_id
content
status
}
mutation addTodo($content: String!) {
addTodo(content: $content) {
...TodoFragment
}
}
apollo-cli
will generate the following types:
import { TodoStatus } from "./globalTypes";
export interface TodoFragment {
__typename: "Todo";
_id: string;
content: string;
status: TodoStatus | null;
}
export interface addTodo_addTodo {
__typename: "Todo";
_id: string;
content: string;
status: TodoStatus | null;
}
export interface addTodo {
addTodo: addTodo_addTodo | null;
}
export interface addTodoVariables {
content: string;
}
As you can see, TodoFragment
is successfully generated, but it is not used by addTodo_addTodo
interface.