Implement GraphQL Subscription in Angular/NativeScript Angular Applications

GraphQL subscriptions allow an application to receive real-time updates from a GraphQL server.

Unlike queries and mutations, where the client sends a request and waits for a response, subscriptions allow the server to push new data to the client whenever an event occurs.

In this article, we’ll see how to implement GraphQL subscriptions in a NativeScript + Angular application using Apollo Client and graphql-ws.

1. Install graphql-ws

npm intstall graphql-ws
or
yarn add graphql-ws

graphql-ws provides the WebSocket-based transport required for GraphQL subscriptions.

HTTP vs WebSocket

Before looking at the implementation, it’s important to understand why WebSockets are required for subscriptions.

HTTP — Standard Web Requests

With a normal HTTP request:

• The front-end sends a request to the server.
• The server processes the request.
• The server sends a respnse.
• The HTTP request is completed.

WebSockets

With WebSockets, the client and server establish a persistent connection. Once the connection is established, both sides can send messages at any time. This makes WebSockets a good fit for real-time features such as:

• GraphQL subscriptions
• Live notifications
• Chat applications
• Real-time dashboards
• Live status updates

2. Configure Apollo Client

Let’s look at how to add support for this transport to Apollo Client.

We need two different links in Apollo Client:

• An HTTP link for queries and mutations
• A WebSocket link for subscriptions

provideApollo(() => {
      // Create an http link:
      const httpLink = inject(HttpLink).create({
        uri: "http://graphql-server/graphql"
      });

      // Create a WebSocket link:
      const wsLink = new GraphQLWsLink(
        createClient({
          url: "ws://graphql-server/graphql",
          lazy: true,
          retryAttempts: Infinity
        })
      );

      const link = split(
        ({ query }) => {
          const definition = getMainDefinition(query);

          return (
            definition.kind === Kind.OPERATION_DEFINITION &&
            definition.operation === OperationTypeNode.SUBSCRIPTION
          );
        },
        wsLink,
        httpLink
      );

      return {
        link: link,
        cache: new InMemoryCache({})
      };
    })

What does split do?

Apollo’s split() has essentially this structure:

split(condition, trueLink, falseLink)

If the condition returns true, Apollo uses wsLink. If it returns false, Apollo uses httpLink.

Understanding getMainDefinition(query)

const definition = getMainDefinition(query);

Extracts the main operation definition from the GraphQL AST.

Get Beyond Coding’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

We then check:

definition.kind === Kind.OPERATION_DEFINITION

This verifies that the definition represents a GraphQL operation.

Next, we check:

definition.operation === OperationTypeNode.SUBSCRIPTION

This determines whether the operation is a subscription.

Therefore:

• Query → httpLink
• Mutation → httpLink
• Subscription → wsLink

4. Why does this work in Angular Web applications but fail in NativeScript?

Because graphql-ws does this internally:

createClient({
  url: 'ws://...'
})

In a normal browser, graphql-ws can use the browser's global WebSocket. But in your NativeScript + Angular environment, there isn’t a browser-style global WebSocket available to graphql-ws.

Add WebSocket support to NativeScript

To provide WebSocket functionality in NativeScript, install:

npm install @valor/nativescript-websockets
or
yarn add @valor/nativescript-websockets

Then import the package in main.ts.

import '@valor/nativescript-websockets';

5. Android: ReferenceError: okhttp3 is not defined

After adding the NativeScript WebSocket implementation, you may encounter another error on Android:

ReferenceError: okhttp3 is not defined

The NativeScript WebSocket implementation uses Android’s native networking stack through OkHttp. If the required OkHttp classes are not available in the Android application’s classpath, the NativeScript JavaScript layer may fail when it tries to access classes from the okhttp3 package.

In that situation, you need to add the OkHttp dependency to your Android application.

Add below in app.gradle file.

dependencies {
    implementation "com.squareup.okhttp3:okhttp:4.9.3"
}

Then rebuild the Android application.

What is OkHttp?

OkHttp is an HTTP and networking library for Android/JVM applications.

It provides functionality such as:

• HTTP requests
• HTTPS
• WebSocket connections
• Connection pooling
• TLS support
• Network connection management

In this setup, OkHttp provides the native Android networking implementation required by the NativeScript WebSocket plugin.

With these pieces in place, Apollo Client can use HTTP for queries and mutations and WebSockets for GraphQL subscriptions in a NativeScript Angular application.