@teamnovu/vite-plugin-vue-gql-statamic

A Vite plugin to write GraphQL queries for Statamic inside Vue components.

Note Although this plugin is meant to be used with nuxt-graphql-client and Statamic, it does not depend on either of them.

Why?

Writing GraphQL queries from scratch in separate files is a pain. This plugin allows you to write GraphQL queries directly inside your Vue components, while preserving proper syntax highlighting.

Additionally, it allows you to couple the individual types from your GraphQL schema with their respective Vue component.

For more detailed information on the idea behind this plugin, please read through teamnovu's use case.

Installation

Install the plugin using your package manager of choice:

pnpm i -D @teamnovu/vite-plugin-vue-gql-statamic

Register the plugin in your vite.config.ts:

import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import VueGqlStatamic from '@teamnovu/vite-plugin-vue-gql-statamic'

export default defineConfig({
  plugins: [
    Vue(), 
    VueGqlStatamic(),
  ],
})

With Nuxt

Instead of registering the plugin in your vite.config.ts, you need to register it in your nuxt.config.ts:

import VueGqlStatamic from '@teamnovu/vite-plugin-vue-gql-statamic'

export default defineNuxtConfig({
  vite: {
    plugins: [
      VueGqlStatamic(),
    ],
  },
})

Options

VueGqlStatamic({
    /**
     * Path to write the generated .gql-files to.
     * @type {string}
     */
    generateTo: 'queries/generated',

    /**
     * Set to true if you do not want any .gql-files to be generated.
     * @type {boolean}
     */
    disableGqlFileGeneration: false,

    /**
     * Path to import global fragments from.
     * These fragments with be prepended to every generated .gql-file.
     * @type {string|false}
     */
    importFragmentsFrom: 'queries/fragments',

    /**
     * GraphQL host to fetch the schema from.
     * @type {string}
     */
    gqlHost: 'http://localhost/graphql',

    /**
     * Enables debug logging.
     * @type {boolean}
     */
    debug: false,

    /**
     * Generates a human readable output.
     * @type {boolean}
     */
    pretty: true,
})

Usage

A GraphQL query can be written inside a Vue component by using the gql tag:

<template><!-- ... --></template>

<gql lang="gql">
query MyQuery($uri: String!) {
  entry(uri: $uri) {
    id
    title
  }
}
</gql>

<script><!-- ... --></script>

For every gql tag with the query attribute (defaults to query if no attribute is provided), a file will be generated output directory.

By default, the file generated will be named after the component's filename, but you can specify a custom name:

<gql lang="gql" query="my-query">
<!-- ... -->
</gql>

Teamnovu's Use Case

In our case, the plugin is meant to be used in conjunction with nuxt-graphql-client. The plugin will write the GraphQL queries to files, which are then picked up by the GraphQL client.

Usually, we would use the plugin in a project which consumes the GraphQL API provided by Statamic. There, we would have various blueprints which include a components field of type replicator, bard or grid. The sets of this components replicator would all relate to a specific Vue component. This allows our editors to create highly dynamic pages by adding and removing isolated components.

In order to not have to write a gigantic GraphQL query, we added support for blueprints and components to this plugin. This means, we would create a Vue components for every blueprint with a <gql blueprint> tag and a Vue component for every component with a <gql component> tag. Based on our GraphQL-API's schema, this generates fragments for the respective types, which can then be used in the main query.

If you are interested in more details on how we use this plugin, feel free to contact us at [e-mail].

Contributing

Note Please make sure to read the Contributing Guide before making a pull request.

Roadmap

Small Stuff

• [x] Allow query definition in the page's Vue component.
• [x] Allow the component-loader's field name to be customized.
• [x] Support multiple component-loaders in various blueprints.
• [x] Cleanup debug output.
• [x] Default to query if no attribute is specified.
• [x] Add default collection name for blueprint based on the schema.
• [x] Add (optional) case converting from snake_case to camelCase using GraphQL aliases.
• [x] Support bard component-loaders.
• [x] Sort output for .gql-file to prevent it showing up in git as newly changed all the time.
• [x] Add disableGqlFileGeneration-flag to be able to disable .gql-file generation while still having the plugin remove all gql tags.
• [x] Import a .gql-file with "global" fragments to the top of every query.
• [x] Import "global" fragments from .gql-files in a directory to the top of every query.
• [x] Fix package.json according to this tweet.
• [x] Bypass throttled file writing function for blueprints.
  • [ ] Fix issue where nuxt-graphql-client fails, if no .gql-files are present (e.g. generate dummy query initially). => https://github.com/Diizzayy/nuxt-graphql-client/issues/315
  • [ ] Possibly validate query (e.g. attempt request) before writing to file to prevent nuxt-graphql-client from failing.
• [ ] Hot-reloading fails, when pnpm run dev is started with an already invalid .gql-file. This is an issue of the nuxt-graphql-client-module. Perhaps, this can be fixed, if errors for invalid properties are thrown by this plugin. => https://github.com/Diizzayy/nuxt-graphql-client/issues/315
• [ ] Text component should not require a string component attribute component="BardText".
• [ ] Log errors including their position in the file. (e.g. "no collection provided"-error, invalid property errors)
• [ ] (Possibly) use Vue SFC parser to extract the query.
• [x] Minify query (remove whitespace & unnecessary chars) (https://www.npmjs.com/package/gqlmin)

Big Stuff

• [x] Publish on npm.
• [ ] Generate Vue components for the GraphQL types defined in the schema.
  • Could be part of a npx command
• [x] Support multiple gql tags in a single component.
  • [ ] Handle similar names within the same component. (Should probably throw an error)
• [ ] Make schema comparison optional, so it can be used without a connection to a GraphQL server.