DEV Community: Uri Goldshtein

GraphQL Modules — Feature based GraphQL Modules at scale

Uri Goldshtein — Wed, 18 Mar 2020 19:41:18 +0000

GraphQL Modules — Feature based GraphQL Modules at scale

Today we are happy to announce that we are open sourcing a framework we’ve been using for the past couple of months in production — GraphQL Modules!

Yet another framework? well, kind of.. GraphQL Modules is a set of extra libraries, structures and guidelines around the amazing Apollo Server 2.0.

You can and should use them as completely separate packages, each one is good for different use cases, but all together they represent our current philosophy of building large scale GraphQL servers.

We would love to get feedback from the Apollo team and if they wish to use those ideas and integrate them into Apollo Server we would love to contribute. That’s why we’ve developed it as a set of independent tools under a single monorepo.

The basic concept behind GraphQL Modules is to separate your GraphQL server into smaller, reusable, feature based parts.

A basic and initial implementation of a GraphQL server usually includes:

A more advanced implementation will usually use a context to inject things like data models, data sources, fetchers, etc, like Apollo Server 2.0 provides us with:

Usually, for simple use cases, the example above will do.

But as applications grow, their code and schematic relationships becomes bigger and more complex, which can make schema maintenance a hard and agonizing thing to work with.

Some of the more old school, MVC frameworks adds few more layers after the resolvers layer, but most of them just implement separation based technical layers: controllers, models, etc.

We argue that there is a better approach of writing your GraphQL Schema and implementation.

We believe you should separates your GraphQL schema by modules, or features, and includes anything related to a specific part of the app under a “module” — which is just a simple directory. Each one of the GraphQL Modules libraries would help you in the gradual process of doing that.

The modules are being defined by their GraphQL schema — so we’ve taken the “GraphQL First” approach lead by Apollo and combined it together with classic modularization tooling to create new ways of writing GraphQL servers!

The GraphQL Modules toolset has tools to help with:

Schema Separation — declare your GraphQL schema in smaller pieces, which you can later move and reuse.
Tools designed to create independent modules — each module is completely independent and testable, and can be shared with other applications or even open sourced if needed
Resolvers Composition — with GraphQL Modules you can write your resolver as you wish, and let the app that hosts the module to wrap the resolvers and extend them. It’s implemented with a basic middleware API, but with more flexibility. That means that you can, for example, implement your entire module without knowing about the app authentication process, and assume that currentUser will be injected for you by the app.
A clear, gradual path from a very simple and fast, single-file modules, to scalable multi-file, multi-teams, multi-repo, multi-server modules.
A scalable structure for your GraphQL servers — managing multiple teams and features, multiple microservices and servers

and more advanced tools, which you can choose to include when your schema gets into massive scale:

Communication Bridge — We also let you send custom messages with payload between modules — that means you can even run modules in different microservices and easily interact between them.
Dependency Injection — Implement your resolvers, and later, only when you see fit, improve their implementation by gradually introducing dependency injection. It also includes richer toolset around testing and mocking.

A Basic Example

In the following example, you can see a basic implementation for GraphQL Modules server, with 2 modules: User and Chat. Each module declares only the part that is relevant to it, and extends previously declared GraphQL types.

So when User module is loaded, the type User is created, and when Chat module is loaded, the type User being extended with more fields.

import { GraphQLModule } from '@graphql-modules/core';
import { UserModule } from './user-module';
import { ChatModule } from './chat-module';

export const appModule = new GraphQLModule({
  imports: [
    UserModule,
    ChatModule,
  ],
});

import { GraphQLModule } from '@graphql-modules/core';
import gql from 'graphql-tag';

export const ChatModule = new GraphQLModule({
  typeDefs: gql`
    # Query declared again, adding only the part of the schema that relevant
    type Query {
      myChats: [Chat]
    }

    # User declared again- extends any other `User` type that loaded into the appModule
    type User {
      chats: [Chat]
    }

    type Chat {
      id: ID!
      users: [User]
      messages: [ChatMessage]
    }

    type ChatMessage {
      id: ID!
      content: String!
      user: User!
    }
  `,
  resolvers: {
    Query: {
       myChats: (root, args, { getChats, currentUser }) => getChats(currentUser),  
    },
    User: {
      // This module implements only the part of `User` it adds
      chats: (user, args, { getChats }) => getChats(user), 
    },
  },
});

import { appModule } from './modules/app';
import { ApolloServer } from 'apollo-server';

const { schema, context } = appModule;

const server = new ApolloServer({ 
  schema,
  context,
  introspection: true,
});

server.listen();

import { GraphQLModule } from '@graphql-modules/core';
import gql from 'graphql-tag';

export const UserModule = new GraphQLModule({
  typeDefs: gql`
    type Query {
      me: User
    }

    # This is a basic User, with just the basics of a user object
    type User {
      id: ID!
      username: String!
      email: String!
    }
  `,
  resolvers: {
    Query: {
       me: (root, args, { currentUser ) => currentUser,  
    },
    User: {
      id: user => user._id,
      username: user => user.username,
      email: user => user.email.address, 
    }, 
  },
});

You can and should adopt GraphQL Modules part by part, and you can try it now with your existing GraphQL server.

What does a “module” contain?

Schema (types declaration) — each module can define its own Schema, and can extend other schema types (without explicitly providing them).
Thin resolvers implementation — each module can implement its own resolvers, resulting in thin resolvers instead of giant files.
Providers — each module can have its own Providers, which are just classes/values/functions that you can use from your resolvers. Modules can load and use providers from other modules.
Configuration — each module can declare a strongly-typed config object, which the consuming app can provide it with.
Dependencies — modules can be dependent on other modules (by its name or its GraphQLModule instance, so you can easily create an ambiguous dependency that later could be changed).

GraphQL Modules libraries

GraphQL Modules is built as a toolkit, with the following tools, which you should individually and gradually adopt:

@graphql-modules/epoxy

That will probably be the first tool you want to introduce into your server. The first step into organizing your server in a feature based structure
Epoxy is a small util that manages the schema merging. it allow you to merge everything in your schema, starting from types to enums, unions, directives and so on.
This is an important feature of GraphQL Modules — you can use it to separate your GraphQL types to smaller pieces and later on combine them into a single type.
We took the inspiration from merge-graphql-schemas, and added some features on top of it to allow custom merging rules to make it easier to separate your schema.

@graphql-modules/core

Resolvers Composition — manages the app’s resolvers wrapping
Context building — each module can inject custom properties to the schema, and other modules can use it (for example, auth module can inject the current user, and other modules can use it)
Dependency injection and module dependencies management — when you start, there is no need of using DI is your server. but when your server gets big enough with a large number of modules which depends on each other, only then, DI becomes a very help thing that actually simplifies your code a lot. USE ONLY WHEN NECESSARY ;)

You can find more tooling at your disposal like:

@graphql-modules/sonar — a small util that helps you to find GraphQL schema and resolvers files, and include them.

@graphql-modules/logger — a small logger, based on winston 3, which you can easily use in your app.

Get Started

First thing, don’t go full in! Start by simply moving your code into feature based folders and structures with your existing tools.

Then head over to https://graphql-modules.com/ and check out our tools and use them only when you see that they solve a real problem for you! (for us it has)

Also check out the repo’s README and a number of example apps.

You probably have many questions — How does this compare to other tools, how to use those libraries with X and so on.

We will publish a series of blog posts in the coming weeks that will dive deep into each of the design decisions made here, so we want to hear your thoughts and questions, please comment here or on the Github repository!

Going to GraphQL Summit? I will be there and would love to get your questions and feedback on behalf of our team.

All those tools were built by a passionate group of individual open source developers, otherwise known as The Guild.

Below there is a section of more deep dive thoughts that we will publish separate posts about in the coming weeks:

Core Concepts and deep dive

Modularizing a schema

Everyone is talking about schema stitching and GraphQL Bindings. Where does that fit into the picture?

Schema stitching is an amazing ability and concept, which helps you merge separated GraphQL servers into a single endpoint and opens up a lot of exciting use cases.

But, with all the excitement, we’ve missed something much more basic than that — sometimes we still want to work on a single logical server, but we just want to separate the code according to features.

We want to be able to do most of the merging work at build time, and only if really necessary, do the rest of the merging at runtime as a last resort.

We want to split the code into separate teams and even create reusable modules which define their external APIs by a GraphQL Schema.

Those modules can be npm modules, microservices or just separate folders inside a single server.

Separating your schema to smaller parts is easier when you are dealing with typeDefs and resolvers— it’s more readable and easy to understand.

We also wanted to allow developers to extend only specific types, without creating the entire schema. With GraphQL schema, you have to specify at least one field under Query type, which is something that we did not want to enforce on our users.

We see our approach as complementary to Schema Stitching and works together with it.

Feature-based implementation

One of the most important things in GraphQL Module’s approach is the feature-based implementation.

Nowadays, most frameworks are separating the layers based on the role of the layer — such as controllers, data-access and so on.

GraphQL Modules has a different approach — separate to modules based on your server’s features, and allow it to manage its own layers within each module implementation.

It’s easier to think about apps in a modular way, for example:

Your awesome app needs a basic authentication, users management, user profiles, user galleries and a chat.

Each one of these could be a module, and implement its own GraphQL schema and its own logic, and it could depend on other modules to provide some of the logic.

Here’s a simple example for a GraphQL Schema as we described:

But if we think of apps in terms of features and then separate the schema by module, the modules separation will look like so:

This way, each module can declare only the part of the schema that it contributes, and the complete schema is a representation of all merged type definitions. Module can also depend, import and extend and customize the contents on other modules (for example, User module, comes with Auth inside it)

The result of course, will be the same, because we are merging the schema into a single one, but the codebase will be much more organized and each module will have its own logic.

Reusability of backend modules

So now that we understood the power of feature-based implementation, it’s easier to grasp the idea behind code reusability.

If we could implement the schema and the core of Auth and User module as “plug-and-play” — we will be able later to import it in other projects, with very minor changes (using configuration, dependency injection, or module composition).

How could we reuse complete modules that hold part of a schema?

For example, let’s take a User type.

Most of User type schemas will contain id, email and username fields. The Mutation type will have login and the Query will have user field to query for a specific user.

We can re-use this type declaration.

The actual implementation might differ between apps, according to the authentication provider, database and so on, but we can still implement the business logic in a simple resolver, and use dependency injector and ask the app that’s using the module to provide the actual authentication function (of course, with a complete TypeScript interface so we’ll know that we need to provide it ;) ).

Let’s take it one step further. If we would like to add a profile picture to a user, we can add a new module named UserProfile and re-declare the User and Mutation types again:

type User {
  profilePicture: String
}

type Mutation {
  uploadProfilePicture(image: File!): User
}

This way, GraphQL Modules will merge the fields from this User type into the complete User type, and this module will only extend the User type and Mutation type with the required actions.

So let’s say that we have the schema — how can we make this module generic and re-use it?

This is how you declare this module:

import { GraphQLModule } from '@graphql-modules/core';
import gql from 'graphql-tag';
import { UserModule } from '../user';
import { Users } from '../user/users.provider';

export interface IUserProfileModuleConfig {
  profilePictureFields ?: string;
  uploadProfilePicture: (stream: Readable) => Promise<string>;
}

export const UserProfileModule = new GraphQLModule<IUserProfileModuleConfig>({
  imports: [
    UserModule,
  ],
  typeDefs: gql`
    type User {
      profilePicture: String
    }
    type Mutation {
      uploadProfilePicture(image: File!): User
    }
  `,
  resolvers: config => ({
    User: {
      profilePicture: (user: User, args: never, context: ModuleContext) => {
        const fieldName = config.profilePictureField || 'profilePic';

        return user[fieldName] || null;
      },
    },
    Mutation: {
      uploadProfilePicture: async (root: never, { image }: { image: any }, { injector, currentUser }: ModuleContext) => {
        // using https://www.apollographql.com/docs/guides/file-uploads.html
        const { stream } = await image;

        // Get the external method for uploading files, this is provided by the app as config
        const imageUrl = config.uploadProfilePicture(stream);

        // Get the field name
        const fieldName = config.profilePictureField || 'profilePic';

        // Ask the injector for "Users" token, we are assuming that `user` module exposes it for us,
        // then, update the user with the uploaded url.
        injector.get(Users).updateUser(currentUser, { [fieldName]: imageUrl });

        // Return the current user, we can assume that `currentUser` will be in the context because
        // of resolvers composition - we will explain it later.
        return currentUser;
      },
    },
  }),
});

We declare a config object, and the app will provide it for us, so we can later replace it with a different logic for uploading.

Scaling the codebase

Now that we broke our app into individual modules, once our codebase grows, we can scale each module individually.

What do I mean by scaling a codebase?

Let’s say we start to have code parts we want to share between different modules.

The current way of doing it in the existing GraphQL world is through a GraphQL context.

This approach has proven itself to work, but at some point it becomes a big hassle to maintain, because GraphQL context is an object, which any part of the app can modify, edit and extend, and it can become really big pretty quickly.

GraphQL modules let each module extend and inject fields to the context\ object, but this is something that you should use with caution, because I recommend the context\ to contain the actual context\ — which contains data such as global configuration, environment, the current user and so on.

GraphQL modules only adds one field under the context, called injector which is the bridge that lets you access your GraphQLApp and the application Injector, and it lets you fetch your module’s config and providers.

Modules can be a simple directory in a project or in a monorepo, or it could be a published NPM module — you have the power to choose how to manage your codebase according to your needs and preferences.

Dependency Injection

GraphQL Modules’ dependency injection is inspired by .NET and Java’s dependency injection which has proven itself to work pretty well over the years. With that being said, there were some issues with .NET and Java’s APIs, which we’ve tried to list and go through. We ran into some pretty interesting conclusions.

We’ve learn that it’s not something that should be forced. Dependency injection makes sense in some specific use cases and you should need to use it only when it’s necessary and when it helps you move faster. So this concept should come more and more in handy as we scale up, we can simplify things, maintain our code with ease and manage our teams’ contributions!

Having GraphQL Modules deployed across all of our Enterprise customers while also being used on our smaller applications, lead us to believe that we’ve found the optimal point of where you should use the concept of dependency injection, and when not.

We’ve also came with the optimal API for dependency injection. It’s extremely easy to understand, and use.

After a long research of the existing dependency injection solutions for JavaScript, we’ve decided to implement a simple Injector, that supports the needs of GraphQL-Modules ecosystem, and support circular dependencies and more.

We’ve simplified the Dependency Injection API and exposed to you only the important parts, that we believe that are necessary for a GraphQL server development.

Authentication

Check out the related blog post we wrote about it: https://medium.com/the-guild/authentication-and-authorization-in-graphql-and-how-graphql-modules-can-help-fadc1ee5b0c2

Testing and mocking

On our Enterprise applications, when we started using dependency injection, we no longer had to manage instances and bridge them together.

We gained an abstraction that allowed us to test things easier and mock all http requests.

Yes, mocking. DI really shines here.

Thanks to mocking we can simulate many scenarios and check the backend against them.

And when your codebase grows, you need to start thinking about managing dependencies between modules and how to avoid things like circular dependencies — unless you use DI which solves that problem for you.

With the power of dependency injection, you can easily create a loose connection between modules, and base this connection on a token and on a TypeScript interface.

It also means that testing is much easier — you can take your class/function and test it as an independent unit, and mock its dependencies easily.

Summary

We see GraphQL Modules as the framework that finally being built from the ground up on the new and exciting capabilities of GraphQL and Apollo, while combining it in the right way with good old software best practices for scale like modularizations, strong typings and dependency injection.

Now go and try it out — https://graphql-modules.com/

All posts about GraphQL Modules

Follow us on GitHub and Medium, we are planning to release many more posts in the next couple of weeks about what we’ve learned using GraphQL in recent years.

New release of GraphQL Subscriptions for Javascript

Uri Goldshtein — Wed, 18 Mar 2020 19:41:16 +0000

Lifecycle events, async configuration, MQTT/Redis integrations and feedback from the community

GraphQL subscriptions are a way to add realtime data streaming to your GraphQL API. Yesterday, we wrote about an exciting new development for the community: the new RFC to add GraphQL subscriptions to the spec. Today, we’ll talk about the new versions we recently released for our GraphQL subscriptions implementation, and the work we’ve done to get to this exciting place.

Where subscriptions started

On the Apollo team, we’ve been passionate about realtime data in GraphQL, and subscriptions in particular, for a long time. We released the first version of our GraphQL subscriptions library, which was the start of our exploration, almost 6 months ago in September.

While we initially launched this as a feature for Apollo Client, we quickly realized there was a lot of demand for this across the community, so we put together a proposal for a subscriptions architecture that could work with any client or server.

Since then, we’ve been hard at work improving the implementation libraries, using GraphQL subscriptions internally and getting feedback from the community.

The new releases

In this post I want to talk about the latest releases:

graphql-subscriptions 0.3.0
subscriptions-transport-ws 0.5.0

These releases included lots of merged PRs and issues fixed from community members who use GraphQL subscriptions in production. We put most of the effort into areas where we had received a lot of feedback from the community:

Improvements for authorization flows
More lifecycle hooks for the client, giving more control and expression with the connection
Improved websockets implementation
Integration with the MQTT protocol in addition to Redis

The goal was to make a flexible implementation while keeping the app-specific code easier. On top of that, we wanted to create smaller and more modular package by splitting the subscriptions client and subscriptions server into separate bundles.

Client and server lifecycle events

One of the features most requested by the community was more lifecycle events to track both the state of a subscription and the state of the connection overall. Many of the issues we closed in the last few weeks were related to this missing feature — and now it’s finally here.

With the new version of subscriptions-transport-ws you can subscribe for client lifecycle events: connect, disconnect, and reconnect.

This gives client developers the ability to respond to those network changes. For example, you can let the user know the app is offline, clear state after logout, disconnect the websocket, or initiate a retry after the connection has reconnected.

The new version also adds server lifecycle events: connect, disconnect, subscribe, and unsubscribe.

This gives the server developer easier control over authentication logic and the ability to clean up state on the client if the server decides to terminate the connection.

New INIT transport message

In addition to independent life cycle events, in the new version of subscriptions-transport-ws, we added a new type of WebSocket message, called INIT , which gives developers the ability to pass custom arguments from the client to the server. You can think of this as a way to pass information would have been a header in HTTP.

Using this new type of message, you can create an authorized WebSocket by passing your authorization data in the initial request and writing code that accepts or rejects the connection before accepting subscriptions from the client using the onConnect callback.

The following example creates a GraphQL subscriptions client and server, using the new initialization feature and lifecycle events:

client.js

import { SubscriptionClient } from ‘subscriptions-transport-ws’;

const getAuthToken = () => {
  // Implement your logic to get the client’s auth details
  return ‘DUMMY_TOKEN’;
};

const wsClient = new SubscriptionClient(`SERVER_URL_HERE`, {
  reconnect: true,
  connectionParams: {
    authToken: getAuthToken()
  }
});

wsClient.subscribe({ query: `...` }, (errors, result) => {
  console.log(errors, result);
});

// If you're using apollo, you can use `addGraphQLSubscriptions` to
// attach this client to your network interface

server.js

import { SubscriptionManager, PubSub } from ‘graphql-subscriptions’;
import { SubscriptionServer } from ‘subscriptions-transport-ws’;
import schema from ‘./schema’;

const pubsub = new PubSub();
const subscriptionManager = new SubscriptionManager({
  schema,
  pubsub
});

const server = createServer(); // create new connect/express server

const subscriptionServer = new SubscriptionServer({
  subscriptionManager,
  onConnect: async ({ authToken }) => {
    const user = await validateUser(authToken);
    if (!user) {
      throw new Error(‘Unauthorized!’);
    } else { 
      // The returned value will be part of the `context`
      // for the filter functions and resolvers
      return {
        user
      };
    }
  },
}, {
  server // or use existing server with different path
});

Refactor and dependency improvements

We also did some code refactor and made the API more flexible. For example, you can now use a Promise for lifecycle events, setupFunctions, setting up the pub/sub engine, and more.

Also, there is now a addGraphQLSubscriptions method in the client side bundle of subscriptions-transport-ws so that developers using Apollo Client no longer need to write this code every time. This method allows you to extend your Apollo network interface to execute GraphQL subscriptions over the WebSocket transport, while using the regular network interface for queries and mutations.

We updated our implementation to use the ws package for the server side websocket implementation. This means you can also use the client if your subscriptions client is in a server-side NodeJS environment (in browser environment, it’s better to use the native implementation of your browser).

The new ws dependency is much faster than our previous websocket library. It’s also smaller library and adds less overhead over the websocket standard, which means it’s easier to abstract out and change the implementation if you need to.

MQTT and Redis support

graphql-subscriptions package exports a default in-process pub/sub implementation, but for the best result in production it’s better to use an external pub/sub product, such as Redis or an MQTT service.

We worked with David Yahalomi to create the graphql-redis-subscriptions and graphql-mqtt-subscriptions packages, which can be easily dropped in as a replacement for the default PubSub object without making any changes to the rest of your code. Using an external pub/sub system gives you more publication features — such as persistence, caching, delivery guarantees and other optimizations.

What’s next

Though we’ve been working on subscriptions for a while, there’s still a lot to be done. In the near future, we’re going to be making the experience of using GraphQL subscriptions a lot better:

GraphQL subscriptions specification. Sashko Stubailo has been working closely with the GraphQL team from Facebook to add subscriptions to the official spec. We’re incorporating the lessons we learned from using subscriptions in production and the feedback we hear from the community.
Documentation. We are working on adding more documentation to our official docs site about how to add subscriptions to your app. In the meantime, the best place to read and learn about setting up GraphQL subscriptions are the readme files of the libraries and the GitHunt example apps. Update: check out our new docs for Subscriptions with React and Subscriptions with GraphQL Server
Making it easier to use subscriptions with Apollo Client. We plan to improve updateQuery\ and updateQueries\ and expose a simpler, yet flexible, API for updating the store when data arrives from subscriptions.
Real-life case studies. Many of the improvements described in this post came from working on our internal apps that use these libraries, while also getting feedback from developers in the community who are using subscriptions in production. We’re going to tell that story in more detail soon.

We’re going to write many more blog posts about those experiences and lessons we learned from using GraphQL subscriptions in production. Make sure to follow our publication so you won’t miss it!

We also want to hear more from you! Try out GraphQL subscriptions with our libraries and tell us what we should do next, and where we can best improve! And if you are really interested in GraphQL subscriptions and real-time features, did you know we’re hiring?

GraphQL CLI is back! Your Swiss Army Knife for the GraphQL ecosystem

Uri Goldshtein — Wed, 18 Mar 2020 19:41:15 +0000

GraphQL CLI is back! Your Swiss Army Knife for the GraphQL ecosystem

Production-ready GraphQL app in seconds

TL;DR;

GraphQL CLI is a popular command-line tool providing various tools for creating and maintaining GraphQL based applications
Prisma recently transferred the project to The Guild — and we completely rewrote it and closed over 100 issues
We’ve already fixed and added many commands but we are looking to learn and integrate with tools and companies across the ecosystem!
You can now generate a full stack working app, from a GraphQL schema model, in 2 minutes using the init+generate commands!
This is an alpha phase — we want your feedback, as a user and as a tool creator — Please create an issue and join our Discord channel

https://youtu.be/NDrPeQB1v5w

Overview

The GraphQL CLI provides:

Helpful commands to improve your daily workflows, from starting a project to maintaining it for the long run
Rich ecosystem and compatibility with libraries, editors and IDEs based on a unified graphql-config
A powerful plugin system to extend GraphQL CLI with custom commands — supported by the community and The Guild

The main target of the GraphQL CLI is to provide a default entry point for the community to use proven techniques for building and deploying GraphQL enabled applications while being vendor agnostic.

Advanced developers and tool creators can extend graphql-cli to provide additional capabilities while still benefiting from a robust set of default commands for daily use — We want to use the CLI to encourage open collaborations between different tool creators.

History

Over the years the GraphQL ecosystem flourished and evolved towards more production-ready use cases with a large number of active community packages available.

GraphQL evolved thanks to the large community and the many supporting libraries it has created.

The GraphQL CLI has become a place for the community to share ideas and best practices across different solutions and libraries thanks to the push from Prisma.

The Guild took over GraphQL CLI to continue on that promise:

Making it as easy as possible create and deploy GraphQL based applications
Making it easier to maintain production-grade, scalable GraphQL applications

All of that while:

Keeping the CLI updated with the latest solutions and practices
Making it extensible and configurable without any solution bias — any approach and architecture could easily integrate and benefit from the CLI
Keeping the industry leading, long term open source library maintenance standard that The Guild is known for

Try it out today

We’ve already refactored most of the code, created a new structure, closed and fixed all the known issues and released a new alpha version.

Install new version (follow the latest alpha in the releases page):

$ npm install graphql-cli@canary

Create a new project with GraphQL CLI by running:

$ graphql init

GraphQL CLI will guide you and after only few seconds, your project will be ready to use!

End-to-end type safety

Code generation + end-to-end type safety is a hot topic nowadays. Thanks to tools like GraphQL Code Generator we’re able to produce flexible code for both backend and frontend, just from GraphQL Schema and Operations with Fragments.

In GraphQL CLI, you get it out of the box by running:

$ graphql codegen

Discover what can be generator on GraphQL Codegen website.

Production ready GraphQL Backend

Thanks to integration with GraphBack, you’re able to produce an entire Data Base, GraphQL schema with operations and strongly typed resolvers.

$ graphql generate

Take a look at GraphBack website to learn more.

Bulletproof your GraphQL API

GraphQL CLI comes with most of the features of GraphQL Inspector.

With just few simple commands you’re able to:

detect breaking or dangerous changes
validate Operations and Fragments at build time
analyze the usage of GraphQL Schema (unused types and fields)
find duplicates and similar GraphQL Types
serve faked GraphQL schema

$ graphql diff
$ graphql similar
$ graphql validate
$ graphql coverage
$ graphql serve

Visit GraphQL Inspector docs.

This is just the start!

The GraphQL CLI has been rewritten in order to make it extremely customizable and extensible.

Our goal is to make sure that any tool can work and benefit from this setup.

The CLI offers freedom for anyone to create any command that will extend their workflows by creating separate library. Alternatively you can open a conversation about new command that can be included into our supported set of commands.

If you prefer to use all of the Apollo toolings and products, AppSync’s solutions, Prisma, OneGraph, Hasura, Postgraphile or any other tool — we want to make the GraphQL CLI the best supporting tool for your stack.

We won’t impose any choices on the users. We want the community to lead and have template generators for any technology.

This project is completely open and free from any bias and we are open to any feedback and collaboration with anyone from the community. Please reach out!

Example use cases of GraphQL CLI

The CLI gives you the ability to build a base template with your favorite stack and tools.

Templates can be based on graphql.js, Apollo, Nexus, TypeGraphQL or anything other framework. Creating a custom template may help to enforce a specific structure that fits your product and company.

The CLI comes with two default templates that provide a seamless starting point for both backend and frontend, both could be pushed to production in a short time period.

Additionally, for existing applications, the CLI will support migrating existing databases or REST API to GraphQL.

Production-ready GraphQL app in seconds

Or “Making GraphQL easy — From nothing to a full production-ready app in 2 minutes — with any stack!”

There are many great GraphQL boilerplate repositories on available Github.

But when using those, it is often hard to adjust those to real business cases.

As an alternative to sample apps, developers can rely on frameworks that provide a high level of abstraction.

But technologies that offer rapid application development might often come at the cost of the maintenance and flexibility that can seriously limit the extensibility of your application server.

$ graphql init

We believe that making it easy to start with GraphQL is extremely important, but without sacrificing other factors like extensibility, scalability and wider control.

Simple shouldn’t equal bad architecture.

GraphQL CLI addresses this very important problem in the core by utilizing two main concepts: code generation and rich ecosystem of base templates.

The graphql init command is trying to address three simple questions:

Can we build an application template that can offer production-ready capabilities and yet is simple enough to work without extensive learning?
Can we provide our data model as input to the GraphQL engine and benefit from autogenerated data access methods?
Can we use the same techniques for an existing application and generate partial models?

You can think of it as a smarter create-react-app, that works on a full-stack and understands your data model.

We are calling leading boilerplate creators and frameworks to collaborate with us. We can help you expose your boilerplates also as templates for the init command.

We would also love feedback from internal infrastructure teams from companies who wish to create their own best practices and guidelines.

For more information please refer to https://github.com/aerogear/graphback

One config to rule them all — GraphQL Config

At the heart of a project created using GraphQL CLI is the GraphQL Config file. It lets the CLI know where all of the GraphQL parts are.

Config is essential for CLI templates and for the command creators that can utilize its extensibility to save additional metadata. Thanks to graphql-config, the CLI can provide seamless support for every extension and streamline development experience on top of the GraphQL CLI generated projects and corresponding templates.

For more information about GraphQL Config, you can click here to learn more.

Migration from 3.x.x to 4.x.x

We have provided a complete migration document for existing users who wish to update to the latest version of the CLI. Please keep in mind that CLI is still in the alpha phase and we are looking for the feedback before officially releasing a final version of the CLI.

Please follow https://github.com/Urigo/graphql-cli/blob/master/MIGRATION.md migration guide.

Help us to shape the GraphQL ecosystem

Start using the GraphQL CLI today!

Even though we are in an alpha phase, the CLI is fully usable and ready for the community to adopt it.

Our team is open to any suggestions and ideas for new commands.

We will support and answer all your questions on Github and on our Discord channel.

The Guild is taking over maintenance of merge-graphql-schemas, so let’s talk about GraphQL Schema management

Uri Goldshtein — Wed, 18 Mar 2020 19:41:14 +0000

How stitching, federation and modules all fit together?

TL;DR

After many years of supporting the community, the OK-Grow! Team is transferring ownership and maintenance of merge-graphql-schemas to The Guild
merge-graphql-schemas will be added to the existing Schema management tools already created by The Guild (GraphQL-Toolkit, GraphQL Modules, GraphQL Inspector and graphql-code-generator)
This is a continuation of making order in the schema management tools across the ecosystem
If you are at GraphQL-Conf this week, come say hi

merge-graphql-schemas is a popular library in the GraphQL Ecosystem.

It’s one of the first tools people encounter once they went through their first GraphQL implementation and start to wonder how to organize their GraphQL server code.

The OK-Grow! Team has been maintaining that library for years, filling a needed gap in the ecosystem.

At the same time, The Guild has been working on similar tools around GraphQL schema and module management.

Today we are happy to announce that we are joining forces and merging our efforts to create open source, easy and scalable solutions for GraphQL servers.

In a couple of days of work we’ve refactored the underlying implementation of merge-graphql-schemas to use GraphQL-Toolkit under the hood, we can close around 90% of the open issues on the library while making sure all existing tests are passing!

We are happy to announce a new beta release (1.6.0-beta) is out!

If you are a user of merge-graphql-schemas please give the new version a try before we make a full release.

yarn add merge-graphql-schemas@next

What’s next?

The Guild has been busy for a while creating scalable GraphQL solutions around schema and modules management for large teams.

The main issue we see today in the ecosystem is that there is no clear overview of which tools solve which problem area.

In order to make sure we solve the right issues in the right place, we need clear boundaries between the different libraries and solutions.

Let’s try to break down the different areas of solutions needed when splitting GraphQL schemas:

Building and executing GraphQL according to spec — The Engine
Structuring multiple building blocks of the same server into a single executable schema — GraphQL Tools and Frameworks
Structuring multiple servers instances into a single executable schema — Federation

Now we can gather all use cases from the community, put them as tests on the right library and make sure we solve each one of them.

The Engine

The Engine (in the Javascript world the most popular one is graphql.js) should be responsible of taking a ready schema and resolvers, validate the objects, introspecting them and executing documents against them at runtime.

That GraphQLSchema input must be strictly valid according to the GraphQL Spec.

That’s why manipulating a ready GraphQLSchema object can be hard. GraphQLSchema object should be the final object to input the engine.

The Engine should not care or help you create that final schema or resolvers.

GraphQL Management Tooling

We can think of the Engine like a Web Browser — It is responsible of taking a spec (Javascript and HTML) and execute it in a consistent way.

But the browser doesn’t care about how you create that Javascript and HTML bundle.

That means that like we use babel, Typescript or frameworks for manipulating code to generate spec-compliant output, we can do the same for GraphQL with graphql.js as our target “browser”.

Those tools should help you organize and manage your code in your preferred way, without needing to be bound by what graphql.js expects.

One of the main things that those tools can provide us is an easy way to split the code and the schema into small chunks and later merge them with different merging strategies.

Just like Javascript frameworks, using those tools can get you very far and make it easy to handle huge codebases with many different teams.

Federation

In some scenarios you would want to run completely different servers and merge them somehow into a single GraphQL gateway.

Schema stitching and schema federation are attempts to make that work less manual.

There are some use cases where you might want those types of solutions, but they also add a lot of complexity so it’s important to understand very well why you really can’t handle your use case in a build-tool type of solution, and to know if Federation is an end goal or a stepping point to get you further.

Breaking it all down

After years of working with GraphQL, from small applications to managing schemas across huge corporations, creating open source tools and best practices around those, we want to share it all with the community.

In the next few weeks we will publish articles about each solution type, the tools around and when you should use what.

Things like why you should split your schemas, why not, what are the existing solutions out there and when to use each one.

We will also add examples of all those use cases into our main tutorial.

We need you to send us your questions, use cases and ideas — we want to make sure we cover as many use cases as possible across our libraries and other libraries we contribute too as well (some things might fit into graphql.js or Apollo for example).

You can comment here or submit issues into any of our repositories.

Thank you OK-Grow!

I want to personally thank the OK-Grow! Team and specifically Paul for being a very early adopter and supporter of the GraphQL community.

The work you have done so far has been amazing and valuable and we are dedicated to continue to support our community in the best way possible.

Sofa — The best way to REST (is GraphQL)

Uri Goldshtein — Wed, 18 Mar 2020 19:41:14 +0000

Ending the REST vs GraphQL debate once and for all

TL;DR

Don’t choose between REST and GraphQL — create a fully RESTful API automatically from your GraphQL implementation (with a library and a single line of code)
Get most of the benefits of GraphQL on the backend and frontend, while using and exposing REST
Support all your existing clients with REST while improving your backend stack with GraphQL
Create custom, perfectly client-aligned REST endpoints for your frontend simply by naming a route and attaching a query
Stop arguing about REST vs GraphQL. Use GraphQL, generate REST and get the best from both
In the other way around (REST to GraphQL) you won’t get the best of both world but less powerful, harder to maintain server implementation with some of the benefits of GraphQL. It is a good and fast start for a migration though..

Wait, WHAT!?

Many articles have been written about the pros and cons of GraphQL and REST APIs and how to decide which one to use. I’m not going to repeat those here..

A lot of time and energy spent by smart consultants to write those articles, read those articles, while most of them are finished with the “it depends on your use case” summary, without actually specifying those use cases!

I’ve been working with REST, GraphQL and SOAP APIs for many years. So I thought, why not come up with a list of those use cases and for each one of those to check — what can’t you do in GraphQL that you can do with REST and what you wouldn’t want to do with GraphQL and you would prefer REST.

After creating that list, I suddenly had a thought — what if there was another option — what if my powerful GraphQL server could just generate a REST API for me?

Then I could get the best of both worlds!

The more I dived into the idea and implementation then more I realized it’s not only that we can have both types of APIs created for us, but even if we just want to expose REST APIs, and none of our clients use GraphQL, GraphQL is the best way the create REST APIs!

How does the above sentence even make sense?!

Usually when we (The Guild) help companies and organizations to modernize their APIs, the first to understand the benefits of GraphQL are the frontend developers, for obvious reasons. But as soon as the backend developers “Get it”, they become the biggest advocates of the technology. But they still need to support existing clients and 3rd party partners.

That’s why those newly generated REST APIs get a lot of the features and benefits from the internal GraphQL implementation that make backend developers happy:

Fully generated documentation that is always up-to-date (Swagger, OpenAPI and GraphiQL)
Truly RESTful API out of the box
GraphQL Subscriptions as Webhooks
Runtime validation of data — be 100% sure that fetched data matches schema’s and query’s structure. You send exactly what I want to send, string is a string, an object has exactly the same properties.
Creating a custom endpoint is now a matter of choose a route name and attaching a query to it. done. No more manual work of creating and maintaining client specific endpoints!
Use GraphQL’s philosophy of evolving APIs through schemas — no more painful V1 — V2 API migrations.
Use modern technology that is easier to hire people to. Companies like Facebook, Airbnb and others have moved to GraphQL. None of them has gone back.
The power of GraphQL resolvers to create your API implementation, instead of manually written controllers from MVC

What I get from having resolvers?

Easier to transform data so it matches the response (GraphQL Schema). That’s because every entity has its own resolvers, so the mapping is moved into smaller pieces and reused across an entire app.
GraphQL allows you to easily share data across every resolver, we call it Context.
Forces you to define and resolve data in an opinionated way that actually helps building an API. It runs functions in parallel (functions that are nested at the same level), handles async and at the end, it is responsible of merging all of that into a single object, so you don’t have to think about it.

Sofa — Use GraphQL to create RESTful APIs

So we created Sofa (pun intended), an open source library you install on your GraphQL server to create a fully RESTful and configurable API gateway. Use GraphQL to REST.

“How to” tutorial

Let’s create a short step by step tutorial on how to create a RESTful API.

Step 1: npm install the [sofa-api](https://www.npmjs.com/package/sofa-api)\ package and add the following line of code:

import sofa from 'sofa-api';
import express from 'express';

const app = express();

app.use(
  sofa({ schema })
);

Step 2: Go REST on a Sofa, you’re done.

Kamil Kisiela added Sofa to the SpaceX GraphQL API implementation by Carlos Rufo, in a single commit.

Check out the fully generated REST endpoints, the Swagger live documentation, GraphiQL editor and the GraphiQL-Explorer!

By the way, what you see here is a REST API, generated on top of a GraphQL API, created on top of another REST API….

Why did you do that for!?!?

Gradually migrating from old REST implementations

This is actually a good direction to go. In many of the companies we work with, they’ve created REST API layers using old technology on top of their original web-services.

But those REST implementations are problematic (for all the obvious reasons people choose to move to GraphQL).

So our way to go is to create GraphQL implementations on top of those REST layers, migrate the clients to those implementations and then gradually remove the old RESTful layer and call the services directly.

Using Sofa made those transitions much faster because we can offer all the existing clients to migrate to our GraphQL implementation without actually using GraphQL themselves. We simply expose the same REST endpoints on top of GraphQL and they are moving to our layer happily because we can accommodate all of their requests and custom REST endpoints much faster than the original, old REST implementations.

Give me more details

Sofa uses Express by default but you can use any other server framework. Sofa is also GraphQL server implementation agnostic.

Head over to the Sofa website for documentation and to the Github repository for reporting issues and helping out.

How Sofa works?

Under the hood, Sofa turns each field of Query and Mutation types into routes. First group of routes is available only through GET method, mutations on the other hand get POST.

Sofa uses GraphQL’s AST to create an operation with all possible variables (even those deeply nested) and knows exactly what to fetch. Later on it converts the request’s body into operation’s variables and execute it against the Schema. It happens locally, but it’s also possible to use an external GraphQL Server or even Apollo Link.

Right now Sofa has a built-in support for Express but it’s totally possible to use a different framework. The main concept stays exactly the same so only the way we handle the request differs across different server implementations.

GraphQL Subscriptions as Webhooks?

The way it works is simply, you start a subscription by calling a special route and you get a unique ID that later on might be used to update or even stop the subscription. Subscriptions are Webhooks. Sofa knows exactly when there’s an even happening on your API and notifies you through the endpoint you’ve assigned a subscription to.

Models / Resources?

In some cases you don’t want to expose an entire object but just its id. How you’re able to do that with Sofa? You need to have two queries. First one has to return a single entity based just on its id (which would be an argument) and the second one should resolve a list of those. Also the names should match, for example a resource called User should have two queries: user(id: ID): User and users: [User]. Pretty much the same thing you would do with REST.

type Query {
  user(id: ID!): User
  users: [User]
}

Before Sofa creates the routes, it looks for those Models and registers them so when the operations are built you don’t fetch everything but only an id.

But what if you want to fetch an entire object but only in few places?

There’s an option called ignore that allows you to do that. You simply pass a path in which you want to overwrite the default behavior.

Given the schema below, you would get just author’s id.

type Book {
  id: ID
  title: String!
  author: User!
}

extend type Query {
  book(id: ID!): Book
  books: [Book]
}

With ignore: ['Book.author']you end up with an entire User object.

sofa({
  ...,
  ignore: ['Book.author'],
})

Swagger and OpenAPI

Thanks to GraphQL’s type system Sofa is able to generate always up-to-date documentation for your REST API. Right now we support Swagger and its OpenAPI specification but it’s really easy to adopt different specs.

import sofa, { OpenAPI } from 'sofa-api';

const openApi = OpenAPI({
  schema,
  info: {
    title: 'Example API',
    version: '3.0.0',
  },
});

app.use(
  sofa({
    schema,
    onRoute(info) {
      openApi.addRoute(info, {
        basePath: '',
      });
    },
  })
);

openApi.save('./swagger.json');

Summary

sofa-api makes it extremely easy to create a RESTful API with all the best practices of REST from a GraphQL server using all its power.

Stop wasting your life arguing about REST vs GraphQL — Be productive, get the benefits of both worlds and move into the future of API development.

I hope this would become the last REST vs. GraphQL article out there…. if you think it won’t, comment with a use case and let’s try it out!

Thanks to Kamil Kisiela for working with me on this and making this library a reality!

Follow us on GitHub and Medium, we are planning to release many more posts in the next couple of weeks about what we’ve learned using GraphQL in recent years.

Rewriting angular-meteor.com in Angular Universal

Uri Goldshtein — Wed, 18 Mar 2020 19:41:13 +0000

We recently finished re-writing and deploying our new angular-meteor.com website with completely new tooling using Angular Universal and our new tutorial infrastructure.

In this post, I’ll share our experience using Angular Universal, and introduce the tools that we created on top of it. We’ll write about (and open source) our new tutorial infrastructure in a following post, so stay tuned!

TL;DR

Our former website was a dynamic app. We wanted to rewrite it into a static website because:

It needed a server and hosting.
We needed a lot of tooling in order to make it SEO compatible.
It loaded slowly.

We’re happy to say… The transition was successful! Check it out and take a look at the new tutorials here.

Here are the improvements this made possible:

The page loads much faster
No need for servers anymore, we use GitHub Pages

To accomplish this, we created a tool that takes various content types and renders it to any format we want:

Input sources — A unique markdown format for our tutorials and a JSDoc format.
Render targets — Our angular-meteor.com website, your own website or doc format, or a Medium post API.

Converting input sources to render outputs

Our new tooling is capable of getting input sources from various content types and generating output in any format we like. Currently, we published it as a package, which includes:

Accepting Markdown + Git patch from our tutorial infrastructure.
Accepting JSDoc.
Angular 2 Components and Directives, and some utils functions that relate to Angular 2, including tutorial -> route.
Static website generator — think about this as a NgModule to HTML files converter.

Tutorial as input

As part of the rewrite, we created a new tutorial infrastructure that we’ll talk about in a future post when we release a few more features. You can see it in action here — https://angular-meteor.com/tutorials/whatsapp2/ionic/setup

For the purpose of this post, the important thing to know about the infrastructure is that the code examples are being generated from a real app using real commits (inspired by Sashko Stubailo’s work on the Meteor tutorial).

The infrastructure renders markdown files with links to the git commits, and we need to turn those into a diff-box components with the actual code that changed in the commit, like here for example.

JSDoc as input

Let’s start again with the result of this section, so it will be simpler to understand: https://angular-meteor.com/api/angular2-meteor/latest/Meteor-RxJS

We want to use the JSDoc standard over our code (example), take this JSDoc definition, convert it into a standard markdown file, display it in our website, and finally expose it directly inside the repository of the package (example).

We wanted versioning because our API might change over time — that’s where Git comes to our aid. We also have a Git revision (commit id or tag) for each version of the package. That way, we can take a specific version of the file with it’s documentation from GitHub and generate the API reference for all of versions of the package and API docs.

Components, Directives, and utils

The Angular 2 components and directives are meant to display results of the markdown docs together with the special Git patch handlers. This means it’s using a regular markdown parser with the small addition of DiffBox, a Component we wrote that displays the changes in each commit in a diff format (just like a diff view in GitHub).

Also, we have directives that are useful for: navigation, creating links, displaying a list of steps of the tutorial, links to download those steps (based on git commit) and more.

We also have a route generator for the tutorial, which means that, based on your tutorial definition, this util will generate your routes for the Angular router with all the required resolve phase that the infrastructure needs (load files from GitHub, format, convert and so on).

Static HTML Generator

Our main output is our angular-meteor.com website. The utils wrap the sources with a beautiful design, custom pages and stylesheet, and then uses the last part of the infrastructure — the static page generator.

Using your application’s route definition (the generated tutorial routes, along with the custom pages you need), this tool loads the entire page (generated on the server side as we’re running in an Angular Universal environment) and saves it into a single HTML file that has no dependencies at all. The whole page is inside a single HTML file — no JS and no external CSS files!

Our next step is the deployment of this website, which is easy, because we are using an autonomous HTML files that every single HTTP server can serve. We chose GitHub Pages to host our website, so we don’t need any external server or hosting.

The Result

We managed to accomplish all of our goals for the new website:

We met our own needs:

It’s easy to maintain because it uses the same GitHub repository that stores the actual tutorial code.
It’s super fast and because it loads only static HTML files.
Its hosting is simple (GitHub Pages) and it has no server-side at all.

We created something that might be useful for others:

Extensions to Angular Universal that can accept your own inputs and outputs.
Tools for rendering markdown from remote source with Angular Universal.

Check out the website and code! Maybe you can find some utils for generating routes of API docs, or expose Components and Directives that you can use later to enrich your own website.

We saw that the Angular team has started working on a new angular.io implementation and would love to help with our tools and experiences from doing very similar work on our own website.

Most importantly — enjoy the new angular-meteor.com :)

Next steps for Angular-Meteor

In recent months, both Meteor and Angular have made huge leaps, so we have a lot of goodies to catch up on.

Our vision for the next version of Angular Meteor includes the following features:

Support for Angular CLI with Meteor Client Bundler (already works).
The easiest way to do lazy load in Angular with Meteor 1.5 (code splitting and dynamic imports without configuration).
AOT out of the box.

But we want your help! If you’re interested in helping us tackle these exciting features, contact us directly!

How to Use Subscriptions in GraphiQL

Uri Goldshtein — Wed, 18 Mar 2020 19:41:13 +0000

Easily test GraphQL subscriptions from your browser

There has been a lot of buzz about GraphQL Subscriptions in the community recently, and a lot of people are excited about the subscriptions RFC opened by Rob Zhu from Facebook.

If you haven’t tried GraphQL subscriptions yet, check out our docs to learn how to add subscriptions to your existing Node.js GraphQL server. You can also easily try building a React app with them by following Graphcool’s tutorial.

Today, I want to tell you about something else that’s really cool: Did you know that Graph_i_QL already supports subscriptions today? Don’t believe me? Here’s a demo so you can see for yourself:

https://www.youtube.com/watch?v=aAwZrBgmnho

Check out the working example of GitHunt with Graph*i*QL here (and the React frontend here).

How it works

The standard GraphiQL library already supports passing in a fetcher that returns an observable or promise. That means that anyone can configure it with their own transport, even if it supports multiple results. We’ve already done that for you, using a newgraphql-subscriptions-fetcher, so you don’t have to.

The following steps are all you need to do. (We’re using graphql-server-express for the example.)

First, make sure you have the latest graphql-server-express package:

npm install —-save graphql-server-express

Now, all you need to do is to set a new field we added to graphqlExpress config, called subscriptionsEndpoint, with the Websocket URL subscriptions endpoint (this is the same endpoint you use in your SubscriptionClient). For example:

app.use(‘/graphiql’, graphiqlExpress({
  endpointURL: ‘/graphql’,
  subscriptionsEndpoint: `ws://localhost:3000/subscriptions`,
}));

That’s it! Finally, all you have to do is start your server, open your browser in http://localhost:3000/graph_i_ql, write a GraphQL subscriptions query inside, and the published data from the server will be pushed into your Graph_i_QL client and displayed in the result screen of Graph_i_QL.

This example uses GraphQL server with express — but it also works with graphql-server-hapi, Koa, Restify and Lambda. Just add the _subscriptionsEndpoint_ field to your GraphiQL configuration and you are good to go! You can also check out the live GitHunt example here.

What if you don’t use graphql-server?

We added the new Graph_i_QL subscriptions support to graphql-server by default, but in case you’re not using it, it’s still very easy to add that support to your own server.

Graph_i_QL is usually served as static HTML (here’s how we do it in graphql-server), so first you need to load subscriptions-transport-ws and graphql-subscriptions-fetcher inside the tag. We’ve published the transport client so that it’s easy to use in a script tag from Unpkg:

<script src=”//unpkg.com/subscriptions-transport-ws@0.5.4/browser/client.js”></script>

<script src="//unpkg.com/graphiql-subscriptions-fetcher@0.0.2/browser/client.js"></script>

Next, you need to create a SubscriptionClient with your subscriptions endpoint:

var subscriptionsClient = new window.SubscriptionsTransportWs.SubscriptionClient(‘YOUR_SUBSCRIPTIONS_ENDPOINT_HERE’, { reconnect: true });

var subscriptionsFetcher = window.SubscriptionsTransportWs.graphQLFetcher(subscriptionsClient, graphQLFetcher);

Finally, replace the regular graphqlFetcher you use in Graph_i_QL with the one that uses the fetcher from graphql-subscriptions-fetcher when creating your Graph_i_QL instance:

ReactDOM.render(
  React.createElement(GraphiQL, {
    fetcher: subscriptionsFetcher,
    onEditQuery: onEditQuery,
    onEditVariables: onEditVariables,
    onEditOperationName: onEditOperationName,
    query: ${safeSerialize(queryString)},
    response: ${safeSerialize(resultString)},
    variables: ${safeSerialize(variablesString)},
    operationName: ${safeSerialize(operationName)},
}), document.body);

Here is a complete example of how it should look.

What’s happening behind the scenes?

subscriptions-transport-wsis a GraphQL subscriptions network transport. Loading it into Graph_i_QL client and replacing the graphQLFetcher function with graphql-subscriptions-fetcher’s fetcher will give you a plug-and-play solution for live-stream subscriptions into your app’s Graph_i_QL editor!

Note that we are still using the original _graphQLFetcher_ inside the new fetcher. We fall back to the original for GraphQL operations that aren’t subscriptions (queries and mutations).

Try it today!

Even though GraphQL subscriptions are still at the RFC stage, it is already being used by many companies in production, and the libraries and tools have been evolving to support a wide range of use cases. So try GraphQL subscriptions in order to add real time ability to your apps today!

Leverage the power of Meteor with any client-side framework

Uri Goldshtein — Wed, 18 Mar 2020 19:41:12 +0000

Introduction to Meteor-Client-Bundler

Meteor was first released back in 2011, and since then it’s been one of the most powerful platforms for web developers. It brought many new concepts to the table — one of the more powerful ones is where the client, server and the database can share code, almost the same API and code snippets, which really accelerated the development process.

This has been a very big advantage that’s proven itself to be worthy, but has also created a misconception that Meteor is a monolith that can’t be broken down to smaller parts. But in fact, when you build a Meteor app for deployment to Galaxy or any other hosting platform, Meteor essentially generates a stand-alone Node application that you can run anywhere Node is installed. This built application can be easily consumed by a wide variety other tools that work with Node and Javascript apps.

In this post, I will show how you can use your existing React, Angular, or WebPack front-end app (or break up your existing Meteor front-end app away from the Meteor CLI) while still using Meteor’s benefits like Meteor Collections, Minimongo, real time updates and DDP, accounts packages and more…

Introducing Meteor Client Bundler

Two example scenarios could be: a) We want to use React Native’s CLI to build our client, since it provides us with native mobile components, and a configurable bundler; or b) We want to use WebPack and the great create-react-app.

Because we’re using Meteor, you might think we’re obligated to use the Meteor CLI, leaving WebPack’s great tools impractical to use. We can therefore ask the following question: “Is there a way to use WebPack, or any other similar tool, to create our client, and Meteor as our backend?” Well folks, the answer is — YES!

I present you — Meteor Client Bundler (it’s a long name, so we’re gonna refer it as MCB).

MCB, as we can infer, is a module-bundler which will take a bunch of Meteor packages and bundle them into a single script, based on a specified configuration. This means we can load Meteor’s core client-script, along with other desired packages, like mys:accounts-phone, jalik:ufs, matb33:collection-hooks etc into any front-end app!

This will give us the ability to create two separate projects: one is made with WebPack CLI (the client) and other is made with Meteor’s CLI (the server). Furthermore, with a little help from bundling tools like Webpack, we can even achieve the effect of shared code snippets between the two apps, which will be shown further in this article.

Some of the advantages of such a strategy are:

Applications which are not based on Meteor can use the DDP client to fetch data from a Meteor-service
We can gradually migrate outdated front-end applications into Meteor
We can use other CLI tools besides Meteor’s like WebPack, Angular and Ionic CLIs and more and not be locked in on a single CLI
Use Meteor when and where it excels and where it fits your needs

I believe that through practical example you can get the hang of it and understand exactly what I’m talking about, by simply fulfilling the scenario described in the second paragraph.

How it works

Let’s dive in! We will begin with creating our client using create-react-app, by running the following command:

$ create-react-app my-frontend-app

Then, we will create a web API service using Meteor’s CLI by typing the following command:

$ meteor create api

Now that they are both created, Let’s connect them to each other, so the React client will know how to use Meteor collections and retrieve data from them using MCB.

First, you’ll need to install MCB globally using NPM using the following command:

$ npm install -g meteor-client-bundler

This will make MCB available globally as a CLI under the name meteor-client:

$ meteor-client — help

Thanks to MCB, we can create a Meteor client with all the necessary dependencies in it using the bundle command. The bundle command takes a configuration file and can be operated differently. The easiest and fastest solution would be providing it the path where the Meteor server is at, using the -s, — source option:

$ meteor-client bundle — source=api

This will create a new file called meteor-client.js under the directory node_modules, which can easily be loaded anywhere in the project like so:

import “meteor-client”;

If you want, you can change the output destination by providing a -d, — destination option:

$ meteor-client bundle — destination=dist/meteor-client.bundle.js

Moreover, you don’t necessarily have to have the client and server on the same machine. The server can be hosted on a completely different computer, yet we can generate its appropriate client. This can be achieved by providing the -c, — config option:

$ meteor-client bundle — config=meteor-client.config.json

Here’s an example config:

{
  “runtime”: {
    “DDP_DEFAULT_CONNECTION_URL”: “http://127.0.0.1:8100”
  },
  “import”: [
    “meteor-base@1.0.4”,
    “mongo@1.1.14”,
    “reactive-var@1.0.11”,
    “jquery@1.11.10”,
    “tracker@1.1.1”,
    “standard-minifier-css@1.3.2”,
    “standard-minifier-js@1.2.1”,
    “es5-shim@4.6.15”,
    “ecmascript@0.6.1”,
    “shell-server@0.2.1”
  ]
}

Each field in the configuration file represents the following:

runtime — Meteor’s runtime config. Most commonly used to set the URL of the Meteor server we would like to interface with.
import — A list of packages we would like to include in our bundle. The bundle will also take care of loading them in the right order and with the required dependencies

You can also specify the server’s URL explicitly using the — url option:

$ meteor-client bundle — url=http://127.0.0.1:8100

How MCB works under the hood

Basically, MCB takes a list of Meteor packages we would like to load in our client. Based on these, it builds a temporary Meteor application and composes a unified file from the fetched packages, with a focus in their chronological loading order.

Still sharing Client and Server code

If you’re using any sort of a configurable module bundler like Webpack, you can recreate one of Meteor’s greatest behaviors where we can load the same script on both client and server with a single definition. This will require you to add an alias for the server’s directory path, and define a special handler for imported Meteor packages. In the case of Webpack, the config extension should look like so:

module.exports = {
  // …
  resolve: {
    alias: [
      api: “path/to/meteor/server”
    ]
  },
  externals: function (context, request, callback) {
    var match = request.match(/^meteor\/(.+)$/);
    var pack = match && match[1];
    if (pack) {
      callback(null, ‘Package[“‘ + pack + ‘“]’);
    }
  }
  // …
};

This should achieve the following result on the client:

Import { FooCollection, BarCollection } from “api/collections”;
Import { Accounts } from “meteor/accounts-base”;

And at the same time, we can use almost identical importations on the server:

Import { FooCollection, BarCollection } from “./collections”;
Import { Accounts } from “meteor/accounts-base”;

In conclusion

These were the key-concepts of Meteor Client Bundler. If you want to build an app while using the Meteor platform for all your stack, or you want to interact with a Meteor server and use any other front-end library or setup, MCB got everything you need, and will get you on the right track.

For a simple example of using MBC, check out this React-Meteor Todo app remake and for a more full-scale app check out the Ionic CLI WhatsApp clone project.

More information regards MCB can be found in its official Github repository over here: https://github.com/Urigo/meteor-client-bundler

I want to thank Eytan Manor for helping me make this library!

Build a WhatsApp Clone with Ionic 2, Angular 2, and Meteor!

Uri Goldshtein — Wed, 18 Mar 2020 19:41:12 +0000

A version of this post was originally published on the Ionic Blog.

Now, a year has passed and a lot has happened: Angular 2.0 is now stable, including astonishing amount of new features for the platform. Ionic 2.0 entered RC stage and is very close to being final. Finally, Meteor reached version 1.4.2, with many improvements the community asked for (fast build times, full npm and yarn support, Node 4.6.1 and MongoDB 3 by default, etc..).

New Ionic/Meteor Whatsapp Tutorials

Today, I’m happy to announce we are releasing two new versions of the Ionic/Meteor Whatsapp tutorial, this time with Angular 2.0 and Ionic 2.0, one using the Ionic CLI and one using the Meteor CLI.

In these tutorials, we’ll create a full WhatsApp clone using Angular 2 and Ionic 2. We’ll use Meteor’s realtime collections for the chat and Meteor’s simple Authentication packages for SMS-based authentication.

It’s great to see the power of these two solutions working together, keeping the platforms up-to-date with the latest improvements in the Javascript ecosystem!

Angular2-Meteor

By the way, if you noticed that the Angular-Meteor.com website is much faster, it’s because we’ve completely re-written it using Angular 2 and universal rendering to generate it as a static website. On top of that, more features are coming to Angular2-Meteor very soon, including lazy loading of modules and support for the AOT compiler.

If you’re thinking about migrating from Blaze to Angular2, or using them side by side, check out our migration tutorial here.

Angular Meteor 1.2.0 Released

Uri Goldshtein — Wed, 18 Mar 2020 19:26:14 +0000

We are happy to announce the release of the new angular 1.2.0 package, which takes advantage of the new build process introduced in Meteor 1.2 to make Angular developers feel even more comfortable and productive.

The main difference between older versions is that now, we use Angular to process regular HTML and JS files instead of .ng.html and .ng.js.

We worked hard to make migrating an existing Angular app to Meteor easier. You can migrate by simply moving your entire existing project into Meteor, or also by using your own tools and connecting to a Meteor server, like we demonstrated with Ionic.

For existing users, as the HTML parsing is now happening by the angular package, we should rename all .ng.html files to .html and remove the blaze-html-templates package to reduce load time on the client.

Also, the new angular package processes JS files with Babel for Ecmascript 2015 support and ng-annotate out of the box.

It also adds the decorators syntax from Babel so it will be easier to use the pbastowski:angular2-now package. This lets you write Angular 2.0 syntax in your Angular 1.x application, which we recommend as a best practice.

That means we should rename all .ng.js files to .js and remove the default ecmascript Meteor core package from our projects.

The new package also uses the Meteor 1.2 caching compilers to make the build process faster.

If you are using the accounts-ui package, we now have dotansimha:accounts-ui-angular package instead.

If you still want to continue using the old build process and combine Blaze and Angular templates, you can use the angular-with-blaze package instead of the angular\ package and keep using the same ng.html and ng.js file extensions and the urigo:angular-blaze-template package to include Blaze templates inside your Angular templates.

Going forward to version 1.3, we will start changing our API to be directed into the best practices we’ve recommended:

Making the data API as similar as possible to the current and the future native Meteor API
Removing the autobind feature to get better performance out of the box

To get ready, you can start using your $meteor services without autobind (sending false to that parameter).

Thanks for all the help we got from the community on this release!

Idan Wender, Chris Antoine, Eytan Manor, Caleb Cox, barbatus, Uri Goldshtein, Joseph Kimberger, Birk Skyum, Tally Barak, Dotan Simha, Netanel Gilad, dinesh36, DumpOfTheVar, Karim Abuzaid, marvinmarnold, David Carter, Eyal Ronel, MarkPhillips7, Nick Benes, Shawn Mckay, Erdou, Sompop Suksawat, Miloš Stanić, BEAUDRU Manuel, BrainCrumbz, David Yahalomi

Please let me know what you think in the comments below.

GraphQL as a best practice for modern Angular apps?

Uri Goldshtein — Wed, 18 Mar 2020 19:26:14 +0000

Angular, meet GraphQL

In this post, I’ll make the case for why Angular needs a best practice for communicating with the server, and why GraphQL should be that best practice.

Best practices

The Angular community is establishing best practices so that we all can benefit from making our apps more performant, easier to maintain, and more modern.

Some of the current best practices include composing everything into Components, using one-way data binding, lazy loading, having an immutable global state management (Redux & ng-rx), and more…

That is all great, and means that if we will follow those best practices our apps will behave better and will look more modern…

…until we get to data fetching from the server.

Data fetching

Today, whether we are developing in a large company, consulting, or writing our own app, when we fetch data from the server we are often left with old practices that don’t address the needs of a modern app.

Also, we are kind of powerless and unable to decide how the data will be supplied to our apps by the server, even though the way we fetch the data to our app is at least as meaningful to the way our app behaves as how we present it.

We should come up with best practices for data fetching that is more in line with the modern way we write our apps. These should take into consideration the following needs: data documentation, network latency, server side rendering and faster initial loading, real time communication patterns, latency compensation, and optimistic UI.

REST

REST is the current protocol we go around when we talking about app data fetching. REST has its benefits, but it was evolved in a time where the web was very different from today, when everything was about static HTML and forms and not about apps.

Here are the areas where REST is currently lacking:

self documentation — when you send a request to a REST endpoint, there is nothing in the protocol that tells you what you are going to get (and not everyone has the resources to create a nice, updated documentation like Twitter)
REST doesn’t support real time data fetching
tough choices when designing your REST endpoint, which I’ll elaborate on below

Over-fetching — When one endpoint serves all the data, each Component calls it again and again. This means it serves more fields than the component needed and we call it many times, creating more load on the server

Under-fetching — When many endpoints serve multiple resources and fields. This creates many round trips for one Component as well as complex joins on the client.

Rethinking data fetching

So it looks like we need to rethink data fetching, just like we rethought web apps.

Luckily, Facebook ran into the same problem in 2012 when they needed to rethink the way they fetch data as they wrote their mobile apps on top of their existing stack.

They developed a solution, and open sourced it as GraphQL.

GraphQL

GraphQL is the new data communication protocol for modern apps.

The server communicates what data it can provide and the client specifies what data it needs in a simple, graph-like structure, in one round trip, no matter how deep, how complex, or how many resources the data contains.

This means: one request to get exactly the information the app needs, when it needs it. No over-fetching and under-fetching.

With that, each component needs to specify its data dependencies and a client library will merge them into one request. There’s no need for a shared service with prepared fetching functions.

GraphQL is also not a storage engine! You can connect it to an existing REST endpoint or SQL and NoSql databases.

Shared best practices between frameworks

For all the reasons above, GraphQL is already the best practice for fetching data with React. Also, all the Facebook apps and clients use GraphQL.

If the Angular community embraces GraphQL as a best practice, it would open the door to sharing more tools and knowledge with the React community.

To start learning about GraphQL, take a look at these sources:

https://www.youtube.com/watch?v=qpGnPbpkcZM

Join the fastest-growing GraphQL community on Apollo Slack or subscribe to this publication for more articles like this and get involved!

Data management and AJAX server fetching for Angular Component based apps

Uri Goldshtein — Wed, 18 Mar 2020 19:26:13 +0000

One of the most powerful concepts introduced by Angular 2 is the move to a Component based architecture.

Components are pieces of UI and logic bound together into reusable and self contained units.

There are two important benefits about Components:

We can reuse Components throughout our apps
When something changes in the inner logic and UI of a Component, it shouldn’t affect the other Components outside of it

Those are great benefits, but are they still valid when we start interacting with the server?

I’ll argue in this article that the current way of calling the server with REST API through central Angular services is not a good fit and that co-locating queries with view logic is the natural extension to the component based architecture.

Calling the server with REST API through central services

Currently in Angular apps, in order to fetch data from the server, we usually import a service that handle the fetching logic for us:

var app = angular.module('myApp', ['ngResource']);

app.factory("Friend", function($resource) {
  return $resource("/api/friend/:id");
});

app.controller("FriendListItemCtrl", function($scope, Friend) {
  Friend.get({ id: 1 }, function(data) {
    $scope.friend = data;
  });
});

When we moved to Component based architecture, we switched the Controller to the Component class, but in most examples out there, the way we fetch data hasn’t really changed.

...
import { Headers, Http } from '@angular/http';
import 'rxjs/add/operator/toPromise';

import { Friend } from ‘./friend’;

@Injectable()
export class FriendService {
  constructor(private http: Http) { }

  getFriend(id: string): Promise<Friend[]> {
    return this.http.get(`/api/friend/${id}`)
                    .toPromise()
                    .then(res => res.json().data as Friend[]);
  }
}

........................

import { Component } from ‘@angular/core’;
import { FriendService } from ‘./friend.service’;

...

@Component({
  selector: ‘friend’,
  templateUrl: ......
})
export class FriendComponent implements OnInit {
  friend: Friend;

  constructor(private friendService: FriendService){
    this.friendService.getFriend(id)
                      .then(friend => this.friend = friend);
  }
}

And that introduces an issue — What happens if now we need to get different data from the server?

Let’s look at an example of the issue, we’ll use this Component tree as an example:

and let’s say the we call a service on the parent FriendsList\ Component that fetches all the data for the Component tree.

Now let’s ask two simple questions:

What happens when we need to change Component to display new fields?
How do we reuse Component in a different place in our app and still fetch the data it needs?

For the first question, we will need to change the server endpoint to either:

Change the existing one to fetch the new data (might change other Components who use the same endpoint and service)

Add a new endpoint with the new data structure we want and change the service to support the new endpoint

In either of those solutions — Our Components are no longer self contained

As for the second question, we would need to create or change the service to support the new Component tree that in under, making it not reusable!

Needed solution

So what do we need that is missing with current solutions:

Each Component could specify its own data dependencies without knowing a central service or another parent Component in the current render tree
When we render a tree of Components, we will fetch exactly the information that this Component tree needs which is a combination of the requirements of each Component
We would do that in one single request
We need an API layer that will bring us new fields without changing existing and exposing new endpoint

Solution — GraphQL Client

With GraphQL, we can co-locate the server data requirements for each Component, and then use a GraphQL Client like angular2-apollo to handle the merging of those needs into one single request that gets exactly what we need.

Let’s have a look:

import { Component } from '@angular/core';
import { Angular2Apollo } from 'angular2-apollo';
import gql from 'graphql-tag';

const FriendsQuery = gql`
  query getFriends {
    friends {
      id
    }
  }
`;

@Component({
  selector: 'friends-list',
  template: `
    <div *ngFor="let friend of friends">
      <friends-list-item [friendId]="friend.id"></friends-list-item>
    </div>
  `
})
export class FriendsListComponent {
  friends: FriendId[];

  constructor(private apollo: Angular2Apollo) {
    this.friends = this.apollo.watchQuery({
      query: FriendsQuery
    });
  }
}

import { Component, Input } from '@angular/core';
import { Angular2Apollo } from 'angular2-apollo';
import gql from 'graphql-tag';

const FriendItemQuery = gql`
  query getFriendItem($id: Int!) {
    Friend(id: $id) {
      id
      is_viewer_friend
      profilePicture {
        url      
      }
    }
  }
`;

@Component({
  selector: 'friends-list-item',
  template: `
    <div>
      <img src="friend.profilePicture.url"/>
      <friend-info [friendId]="friend.id"></friend-info>
      {{friend.is_viewer_friend}}       
    </div>
  `
})
export class FriendListItemComponent {
  @Input() friendId: number;
  friend: FriendListItem;

constructor(private  apollo: Angular2Apollo) {
    this.friend = this.apollo.watchQuery({
      query: FriendItemQuery,
      variables: {id: this.friendId}
    });
  }  
}

import { Component, Input } from '@angular/core';
import { Angular2Apollo } from 'angular2-apollo';
import gql from 'graphql-tag';

const FriendInfoQuery = gql`
  query getFriendInfo($id: Int!) {
    Friend(id: $id) {
      id
      name
      mutual_friends {
        count      
      }
    }
  }
`;

@Component({
  selector: 'friends-info',
  template: `
    <div>
      <p>{{friend.name}}</p>
      <p>{{friend.mutual_friends.count}} mutual friends</p>
    </div>
  `
})
export class FriendInfoComponent {
  @Input() friendId: number;
  friend: FriendInfo;

  constructor(private  apollo: Angular2Apollo) {
    this.friend = this.apollo.watchQuery({
      query: FriendInfoQuery,
      variables: {id: this.friendId}
    });
  }  
}

this is of course not a full working app, I’ll add links to full implementation at the end

Now let’s get back to our original questions:

What happens when we need to change Component to display new fields?
How do we reuse Component in a different place in our app and still fetch the data it needs?

The answer now, is that you only need to change <FriendInfo> Component itself and that’s it:

const FriendInfoQuery = gql`
  query getFriendInfo($id: Int!) {
    Friend(id: $id) {
      id
      name
      mutual_friends {
        count      
      }
      age
    }
  }
`;
...
  template: `
    <div>
      <p>{{friend.name}}</p>
      <p>{{friend.mutual_friends.count}} mutual friends</p>
      <p>{{friend.age}} years old</p>
    </div>
  `
})
export class FriendInfoComponent {
...  
}

That’s it!

We don’t need to change any of its parent Components
We don’t need to change the API endpoint
We can move it around and reuse it in any Component tree

It is now a true reusable, self contained Component.

Summary

In this article I’ve tried to make the point that we should adjust our way of fetching data from the server to the new paradigms Angular 2.0 introduced.

It’s Important to note that those concepts and solutions are also true and valid in an Angular 1.x app that is Component based (and Apollo Client work with it as well).

Also, an important point is that you can use this solution alongside your regular REST services and not instead of them, add it where it fits and make sense to you.

There are many more benefits for this type of architecture and more details about how we manage those queries and app state which I’ll touch on later posts

Here are few notable talks and resources about those techniques, some are for React but the concepts are still the same:

To learn more about how Angular works with GraphQL, hear directly from Angular core team member Jeff Cross at the upcoming GraphQL Summit in San Francisco on October 26th!

DEV Community: Uri Goldshtein

GraphQL Modules — Feature based GraphQL Modules at scale

GraphQL Modules — Feature based GraphQL Modules at scale

A Basic Example

GraphQL Modules libraries

Get Started

Core Concepts and deep dive

Modularizing a schema

Feature-based implementation

Reusability of backend modules

Scaling the codebase

Dependency Injection

Authentication

Testing and mocking

Summary

All posts about GraphQL Modules

New release of GraphQL Subscriptions for Javascript

Lifecycle events, async configuration, MQTT/Redis integrations and feedback from the community

Where subscriptions started

The new releases

Client and server lifecycle events

New INIT transport message

client.js

server.js

Refactor and dependency improvements

MQTT and Redis support

What’s next

GraphQL CLI is back! Your Swiss Army Knife for the GraphQL ecosystem

GraphQL CLI is back! Your Swiss Army Knife for the GraphQL ecosystem

Production-ready GraphQL app in seconds

TL;DR;

Overview

The main target of the GraphQL CLI is to provide a default entry point for the community to use proven techniques for building and deploying GraphQL enabled applications while being vendor agnostic.

History

Try it out today

End-to-end type safety

Production ready GraphQL Backend

Bulletproof your GraphQL API

This is just the start!

We won’t impose any choices on the users. We want the community to lead and have template generators for any technology.

Example use cases of GraphQL CLI

Production-ready GraphQL app in seconds

You can think of it as a smarter create-react-app, that works on a full-stack and understands your data model.

One config to rule them all — GraphQL Config

Migration from 3.x.x to 4.x.x

Help us to shape the GraphQL ecosystem

The Guild is taking over maintenance of merge-graphql-schemas, so let’s talk about GraphQL Schema management

TL;DR

What’s next?

The Engine

GraphQL Management Tooling

Federation

Breaking it all down

Thank you OK-Grow!

Sofa — The best way to REST (is GraphQL)

Ending the REST vs GraphQL debate once and for all

TL;DR

Wait, WHAT!?

Then I could get the best of both worlds!

How does the above sentence even make sense?!

Sofa — Use GraphQL to create RESTful APIs

“How to” tutorial

Why did you do that for!?!?

Gradually migrating from old REST implementations

Give me more details

How Sofa works?

GraphQL Subscriptions as Webhooks?

Models / Resources?

Swagger and OpenAPI

Summary

Rewriting angular-meteor.com in Angular Universal

TL;DR

Converting input sources to render outputs

Tutorial as input

JSDoc as input

Components, Directives, and utils

Static HTML Generator

The Result

Next steps for Angular-Meteor

How to Use Subscriptions in GraphiQL

You can think of it as a smarter `create-react-app`, that works on a full-stack and understands your data model.