README.md

ContentaJS GraphQL

ContentaJS GraphQL is a repository that contains a set of helpers to build your GraphQL project on top of Contenta JS.

This project provides a simple Apollo server instance that you can use in your Contenta JS application. It ships wit a very convenient GraphQL directive that will fetch data from your Contenta CMS back-end using JSON API. The result of that data fetch will be parsed and prepared so it can be resolved by GraphQL without additional work.

You can see this is action in the graphql-example-code branch. If you prefer, you can see the diff. That will show the necessary code to add GraphQL to your Contenta project.

• Benefits of GraphQL in node.js
• Installation
• The @fromJsonApi(…) directive
  • Examples
• Videos
• Contributors
• License

Benefits of GraphQL in node.js

The most obvious benefit of having GraphQL in node.js is that you can aggregate different APIs under a single GraphQL back-end in a non-blocking I/O runtime. This will improve performance dramatically.

Another obvious benefit is that by using the Apollo Server you get many features for free (like mocking, persited queries, cache hint directives, and many additional packages). And even more if your consumers use the Apollo Client.

Another outstanding benefit is that by using GraphQL.js you are depending on the reference implementation of GraphQL. That means that it is supported by the official GraphQL team. It also means that it has extensive support and a wide community.

Installation

You can see an example of this in this demo code.

1. Inside of your Contenta JS project add the necessary dependencies

npm install --save @contentacms/contentajs-graphql graphql graphql-tools

2. Create a server instance with the Contena CMS URL and add it to express.

3. Write your GraphQL types.

4. If they follow the structure of your JSON API resources they’ll get automatically resolved. See this example of an Article type.

5. If there are any additional fields, you can resolve them the GraphQL way. This example creates an extra field called random. In order to resolve the value of random you will need a resolver like this one.

6. THAT’S IT.

The @fromJsonApi(…) directive

The @fromJsonApi(…) is the biggest motivator of this repository. Since JSON API allows you to get the information you need and only the information you need, in a single request, it is the perfect data fetcher for your GraphQL.js project.

This directive will intelligently turn the response from JSON API into the hierarchical format that GraphQL expects. This includes all the nested relationships at all levels. This leaves everything ready for the user to start selecting fields for the response.

Examples

Imagine you have these top level fields in your GraphQL query.

type Query {
  lastRecipe: Recipe
    @fromJsonApi(query: "/recipes?page[limit]=1&sort=createdAt&include=author")
  recipesByAuthor(authorName: String!): [Recipe]
    @fromJsonApi(
      query: "/recipes?filter[author.name]={authorName}&include=author"
    )
  articlesByAuthor(authorName: String!): [Article]
    @fromJsonApi(
      query: "/articles?filter[owner.name]={authorName}&include=owner"
    )
}

Note how you can specify a templated URL with variables. The replacement value for these variables will be specified in the query. For instance see how the {authorName} value is provided when the front-end is querying the GraphQL server like:

curl -X GET \
  'http://localhost:3000/graphql?query={recipesByAuthor(authorName:"Umami"){title,id,random,author{name}}}'

Videos

Take a look at the video series for the ContentaJS GraphQL introduction.

Contributors

Contributors

Mateu Aguiló Bosch

License

@contentacms/contentajs-graphql is MIT licensed.