npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

graphql-tag-persistent

v1.0.5

Published

A JavaScript template literal tag that parses GraphQL queries, and supports persistent queries by adding a query hash to the document

Downloads

9

Readme

graphql-tag-persistent

THIS is a fork of graphql-tag. A PR was submitted for graphql-tag to provide out-of-the-box support for query hashing and persistent queries. Whilst that PR is pending, this package will exist in order to support our use case and potentially others' use case as well. Most of the README.md is based on graphql-tag's.

npm version Build Status Get on Slack

Helpful utilities for parsing GraphQL queries. Includes:

  • gql A JavaScript template literal tag that parses GraphQL query strings into the standard GraphQL AST.
  • /loader A webpack loader to preprocess queries

graphql-tag uses the reference graphql library under the hood as a peer dependency, so in addition to installing this module, you'll also have to install graphql-js.

gql

This is a template literal tag you can use to concisely write a GraphQL query that is parsed into the standard GraphQL AST:

import gql from 'graphql-tag';

const query = gql`
  {
    user(id: 5) {
      firstName
      lastName
    }
  }
`

// query is now a GraphQL syntax tree object
console.log(query);

// {
//   "kind": "Document",
//   "definitions": [
//     {
//       "kind": "OperationDefinition",
//       "operation": "query",
//       "name": null,
//       "variableDefinitions": null,
//       "directives": [],
//       "selectionSet": {
//         "kind": "SelectionSet",
//         "selections": [
//           {
//             "kind": "Field",
//             "alias": null,
//             "name": {
//               "kind": "Name",
//               "value": "user",
//               ...

You can easily explore GraphQL ASTs on astexplorer.net.

This package is the way to pass queries into Apollo Client. If you're building a GraphQL client, you can use it too!

Why use this?

GraphQL strings are the right way to write queries in your code, because they can be statically analyzed using tools like eslint-plugin-graphql. However, strings are inconvenient to manipulate, if you are trying to do things like add extra fields, merge multiple queries together, or other interesting stuff.

That's where this package comes in - it lets you write your queries with ES2015 template literals and compile them into an AST with the gql tag.

Caching parse results

This package only has one feature - it caches previous parse results in a simple dictionary. This means that if you call the tag on the same query multiple times, it doesn't waste time parsing it again. It also means you can use === to compare queries to check if they are identical.

Babel preprocessing

GraphQL queries can be compiled at build time using babel-plugin-graphql-tag. Pre-compiling queries decreases the script initialization time and reduces the bundle size by potentially removing the need for graphql-tag at runtime.

TypeScript

Try this custom transformer to pre-compile your GraphQL queries in TypeScript: ts-transform-graphql-tag.

React Native, Next.js

Additionally, in certain situations, preprocessing queries via the webpack loader is not possible. babel-plugin-inline-import-graphql-ast will allow one to import graphql files directly into your JavaScript by preprocessing GraphQL queries into ASTs at compile-time.

E.g.:

import myImportedQuery from './productsQuery.graphql'

class ProductsPage extends React.Component {
  ...
}

Create-React-App

[email protected] will support the ability to preprocess queries using graphql-tag/loader without the need to eject.

If you're using an older version of create-react-app, check out react-app-rewire-inline-import-graphql-ast to preprocess queries without needing to eject.

Webpack preprocessing with graphql-tag/loader

This package also includes a webpack loader. There are many benefits over this approach, which saves GraphQL ASTs processing time on client-side and enable queries to be separated from script over .graphql files.

loaders: [
  {
    test: /\.(graphql|gql)$/,
    exclude: /node_modules/,
    loader: 'graphql-tag/loader'
  }
]

then:

import query from './query.graphql';

console.log(query);
// {
//   "kind": "Document",
// ...

graphql-tag/loader also supports hashing of queries, to provide support for persisted queries out-of-the-box.

loaders: [
  {
    test: /\.(graphql|gql)$/,
    exclude: /node_modules/,
    use: [
      {
        loader: 'graphql-tag/loader',
        options: {
          // Attach queryId to document (default: true)
          hashQueries: true,

          // Generate a map file for the server (if you don't want to use auto persisted queries).
          // See https://dev-blog.apollodata.com/persisted-graphql-queries-with-apollo-client-119fd7e6bba5
          // and https://www.apollographql.com/docs/engine/auto-persisted-queries.html
          generateHashMap: true,

          // If you want to seed the queryMap with an existing query map file (default: undefined)
          queryMapPath: '',
        },
      },
    ],
  }
]

Testing environments that don't support Webpack require additional configuration. For Jest use jest-transform-graphql.

Support for multiple operations

With the webpack loader, you can also import operations by name:

In a file called query.gql:

query MyQuery1 {
  ...
}

query MyQuery2 {
  ...
}

And in your JavaScript:

import { MyQuery1, MyQuery2 } from 'query.gql'

Warnings

This package will emit a warning if you have multiple fragments of the same name. You can disable this with:

import { disableFragmentWarnings } from 'graphql-tag';

disableFragmentWarnings()

Experimental Fragment Variables

This package exports an experimentalFragmentVariables flag that allows you to use experimental support for parameterized fragments.

You can enable / disable this with:

import { enableExperimentalFragmentVariables, disableExperimentalFragmentVariables } from 'graphql-tag';

Enabling this feature allows you declare documents of the form

fragment SomeFragment ($arg: String!) on SomeType {
  someField
}