Miss any of our Open RFC calls?Watch the recordings here! »

piral-urql

0.12.4 • Public • Published

Piral Logo

Piral URQL · GitHub License npm version tested with jest Gitter Chat

This is a plugin that only has a peer dependency to piral-core. What piral-urql brings to the table is a set of Pilet API extensions that is used by piral.

The set represents a powerful GraphQL integration using the open-source library URQL.

By default, these API extensions are not integrated in piral, so you'd need to add them to your Piral instance.

Documentation

The following functions are brought to the Pilet API.

query()

Executes a GraphQL query against the server specified in the app shell.

mutate()

Runs a GraphQL mutation against the server specified in the app shell.

subscribe()

Establishes a GraphQL subscription via the subscription host defined in the app shell.

Usage

::: summary: For pilet authors

You can use the query function from the Pilet API to execute a GraphQL query against the defined GraphQL server.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  const gql = `query {
    myResource(id: "example") {
      name
      age
      whatever
    }
  }`;
  const promise = piral.query(gql).then(({ name, age, whatever }) => {});
}

You can use the mutate function from the Pilet API to run a GraphQL mutation against the defined GraphQL server.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  const gql = `mutation {
    changeMyResource(id: "example", name: "foo") {
      name
      age
      whatever
    }
  }`;
  const promise = piral.mutate(gql).then(({ name, age, whatever }) => {});
}

You can use the subscribe function from the Pilet API to create a GraphQL subscription to the defined GraphQL server.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  const gql = `subscription {
    onMyResourceChange(id: "example") {
      name
      age
      whatever
    }
  }`;
  const unsubscribe = piral.subscribe(gql, ({ name, age, whatever }) => {});
}

:::

::: summary: For Piral instance developers

For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import createGqlApi from the piral-urql package.

import { createGqlApi } from 'piral-urql';

The integration looks like:

const instance = createInstance({
  // important part
  plugins: [createGqlApi()],
  // ...
});

Via the options the correct client can be set up. Setting the subscriptionUrl to false will prevent using a subscription.

For example:

const client = setupGqlClient({
  url: 'https://example.com/graphql',
  subscriptionUrl: false,
  lazy: true,
});
 
const instance = createInstance({
  // important part
  plugins: [createGqlApi(client)],
  // ...
});

Note: piral-urql plays nicely together with authentication providers such as piral-adal. As such authentication tokens are automatically inserted on queries, mutations, and when establishing subscriptions.

:::

License

Piral is released using the MIT license. For more information see the license file.

Install

npm i piral-urql

DownloadsWeekly Downloads

1,000

Version

0.12.4

License

MIT

Unpacked Size

36.6 kB

Total Files

30

Homepage

piral.io

Last publish

Collaborators

  • avatar
  • avatar