DEV Community: Natalia Tepluhina

Six tips to improve your code review skills

Natalia Tepluhina — Mon, 01 Mar 2021 14:23:22 +0000

In my opinion, code review is one of the most effective tools for improving the code base and aligning your team's coding skills. But, as with any tool, it can be used in the wrong way: it can hurt people, it can lead to conflicts and it can slow down delivering new features. As one of GitLab's frontend maintainers and a maintainer of Vue.js documentation, I am reviewing pull/merge requests daily (and I've done lots of mistakes when I was learning to review code effectively!). In this article, I'll try to share a few techniques that helped me make my reviews better without giving up the quality of the code.

Test the changes locally

Seriously, do it. Whenever you have a pull request to review, try to check out the branch and look at the changes. Not only this helps with smoke testing but it also makes you review deeper. Sometimes code changes look perfectly legit until you read an issue, test the implementation and realize that they are good on the _ low-level_ - but architecture could and should be improved.

Ask questions, don't make statements

Whenever you see something that seems obviously bad to you and you are ready to type something like This is a bad practice and we should not use it - stop for a second. There are chances that your colleague is well aware he is doing something not perfectly, and they might have a good reason for it. Before making conclusions, try to ask some questions to understand the context.

Bad:

Better:

Don't hesitate to praise

This one was extremely hard to learn for me. For some reason, I believed that making a code review is equal to catching all the possible mistakes. Because when someone is doing their job good (in this case, writing the code) good, they should do it by default, right?

No. Not right.

Praising is an important part of code review. As well as we should discourage bad practices in the code, we should encourage good practices. If you see something written nicely, state it openly. An important moment here is being honest and specific: don't praise if you don't see anything worth appraisal, and don't just say "good job!". "I like the way you structure your unit tests! It's very easy to follow" works better.

Label your comments

This point I've learned from my colleague Paul Slaughter. The idea is to prefix a comment with a certain label, clearly stating the point of the comment:

question: I've noticed we are using querySelector here. Is there a reason why we need to access a real DOM?

suggestion: We could simplify this calculation by using a ternary operator here.

nitpick: When checking primitives, we could use toBe instead of toEqual.

This helps the code author to understand the reviewer's intention better and prevent misunderstandings. You can read more about this convention on the Conventional Comments website

Separate blocking from non-blocking

One more additional point about labeling comments is also clearly stating if your concern is blocking. Do we absolutely need to make this change before merging pull request to master? Or is it something minor that can be handled in the follow-up issue or ignored altogether as it's a matter of preference? I prefer to mark blocking comments as issue and non-blocking with nitpick but it's completely up to you how to express your point. Separating blocking comments from non-blocking helps with keeping the code clean while not sacrificing team performance during endless back-and-forth review rounds.

Make an extra step

One more thing to improve the time-to-merge metric is making an extra effort as a reviewer to prevent additional rounds of review. Write explanatory comments - this will help the author to understand the need to change the code and will prevent additional questions. There is something that requires a really long explanation and needs multiple changes? Create a code patch and add it to your comment with a short description of what this patch is doing. This will speed up the process significantly.

Do you have your favorite code review suggestions? Share them in the comments and let's learn from each other!

Testing Vue+Apollo: 2020 edition

Natalia Tepluhina — Thu, 25 Jun 2020 12:53:28 +0000

Almost two years ago I started my dev.to journey with the article about unit testing Vue + Apollo combination. During this time I had multiple requests about mocking an Apollo client and including it to the equation - just like React does with @apollo/react-testing library. This would allow us to test queries and mutations hooks as well as cache updates. There were many attempts from my side to mock a client and finally I am ready to share some examples.

Tests in this article are rather integration that unit tests because we test component and Apollo Client in combination

This article assumes some prior knowledge of Vue.js, Apollo Client and unit testing with Jest and Vue Test Utils

What we're going to test

I decided to go with the same project I was testing in the scope of the previous article. Here, we have a single huge App.vue component that contains logic to fetch a list of people from Vue community, add a new member there or delete an existing one.

In this component, we have one query:

// Here we're fetching a list of people to render

apollo: {
  allHeroes: {
    query: allHeroesQuery,
    error(e) {
      this.queryError = true
    },
  },
},

And two mutations (one to add a new hero and one to delete an existing one). Their tests are pretty similar, that's why we will cover only 'adding a new hero' case in the article. However, if you want to check the test for deleting hero, here is the source code

// This is a mutation to add a new hero to the list
// and update the Apollo cache on a successful response

this.$apollo
  .mutate({
    mutation: addHeroMutation,
    variables: {
      hero,
    },
    update(store, { data: { addHero } }) {
      const data = store.readQuery({ query: allHeroesQuery });
      data.allHeroes.push(addHero);
      store.writeQuery({ query: allHeroesQuery, data });
    },
  })
  .finally(() => {
    this.isSaving = false;
  });

We would need to check that

the component renders a loading state correctly when the query for Vue heroes is in progress;
the component renders a response correctly when the query is resolved (an 'empty state' with 0 heroes should be tested too);
the component renders an error message if we had an error on the query;
the component sends addHero mutation with correct variables, updates a cache correctly on successful response and re-renders a list of heroes;

Let's start our journey!

Setting up a unit test with `createComponent` factory

Honestly, this section is not specific to Apollo testing, it's rather a useful technique to prevent repeating yourself when you mount a component. Let's start with creating an App.spec.js file, importing some methods from vue-test-utils and adding a factory for mounting a component

// App.spec.js

import { shallowMount } from '@vue/test-utils'
import AppComponent from '@/App.vue'

describe('App component', () => {
  let wrapper

  const createComponent = () => {
    wrapper = shallowMount(AppComponent, {})
  };

  // We want to destroy mounted component after every test case
  afterEach(() => {
    wrapper.destroy()
  })
})

Now we can just call a createComponent method in our tests! In the next section, we will extend it with more functionality and arguments.

Mocking Apollo client with handlers

First of all, we need to mock an Apollo Client so we'd be able to specify handlers for queries and mutations. We will use mock-apollo-client library for this:

npm --save-dev mock-apollo-client
## OR
yarn add -D mock-apollo-client

Also, we would need to add vue-apollo global plugin to our mocked component. To do so, we need to create a local Vue instance and call use() method to add VueApollo to it:

// App.spec.js
import { shallowMount, createLocalVue } from '@vue/test-utils'
import AppComponent from '@/App.vue'
import VueApollo from 'vue-apollo'

const localVue = createLocalVue()
localVue.use(VueApollo)

...

const createComponent = () => {
  wrapper = shallowMount(AppComponent, {
    localVue
  });
};

Now we need to create a mock client and provide it to the mocked component:

...
import { createMockClient } from 'mock-apollo-client'
...

describe('App component', () => {
  let wrapper
  // We define these variables here to clean them up on afterEach
  let mockClient
  let apolloProvider

  const createComponent = () => {
    mockClient = createMockClient()
    apolloProvider = new VueApollo({
      defaultClient: mockClient,
    })

    wrapper = shallowMount(AppComponent, {
      localVue,
      apolloProvider,
    })
  }

  afterEach(() => {
    wrapper.destroy()
    mockClient = null
    apolloProvider = null
  })
})

Now we have $apollo property in our mounted component and we can write the first test just to ensure we didn't fail anywhere:

it('renders a Vue component', () => {
  createComponent()

  expect(wrapper.exists()).toBe(true)
  expect(wrapper.vm.$apollo.queries.allHeroes).toBeTruthy()
});

Great! Let's add the first handler to our mocked client to test the allHeroes query

Testing successful query response

To test a query, we would need to define a query response that we'll have when the query is resolved. We can do this with the setRequestHandler method of mock-apollo-client. To make our tests more flexible in the future, we will define an object containing default request handlers plus any additional handlers we want to pass to createComponent factory:

let wrapper
let mockClient
let apolloProvider
let requestHandlers

const createComponent = (handlers) => {
  mockClient = createMockClient()
  apolloProvider = new VueApollo({
    defaultClient: mockClient,
  })

  requestHandlers = {
    ...handlers,
  }
  ...
}

Let's also add a new constant at the top of the test file with the mocked query response:

// imports are here
const heroListMock = {
  data: {
    allHeroes: [
      {
        github: 'test-github',
        id: '-1',
        image: 'image-link',
        name: 'Anonymous Vue Hero',
        twitter: 'some-twitter',
      },
      {
        github: 'test-github2',
        id: '-2',
        image: 'image-link2',
        name: 'another Vue Hero',
        twitter: 'some-twitter2',
      },
    ],
  },
};

It's very important to mock here exactly the same structure you expect to get from your GraphQL API (including root data property)! Otherwise your test will fail miserably 😅

Now we can define a handler for allHeroes query:

requestHandlers = {
  allHeroesQueryHandler: jest.fn().mockResolvedValue(heroListMock),
  ...handlers,
};

...and add this handler to our mocked client

import allHeroesQuery from '@/graphql/allHeroes.query.gql'
...

mockClient = createMockClient()
apolloProvider = new VueApollo({
  defaultClient: mockClient,
})

requestHandlers = {
  allHeroesQueryHandler: jest.fn().mockResolvedValue(heroListMock),
  ...handlers,
}

mockClient.setRequestHandler(
  allHeroesQuery,
  requestHandlers.allHeroesQueryHandler
)

Now, when the mounted component in the test will try to fetch allHeroes, it will get the heroListMock as a response - i.e. when the query is resolved. Until then, the component will show us a loading state.

In our App.vue component we have this code:

<h2 v-if="queryError" class="test-error">
  Something went wrong. Please try again in a minute
</h2>
<div v-else-if="$apollo.queries.allHeroes.loading" class="test-loading">
  Loading...
</div>

Let's check if test-loading block is rendered:

it('renders a loading block when query is in progress', () => {
  createComponent()

  expect(wrapper.find('.test-loading').exists()).toBe(true)
  expect(wrapper.html()).toMatchSnapshot()
})

Great! Loading state is covered, now it's a good time to see what happens when the query is resolved. In Vue tests this means we need to wait for the next tick:

import VueHero from '@/components/VueHero'
...

it('renders a list of two heroes when query is resolved', async () => {
  createComponent()
  // Waiting for promise to resolve here
  await wrapper.vm.$nextTick()

  expect(wrapper.find('.test-loading').exists()).toBe(false)
  expect(wrapper.html()).toMatchSnapshot()
  expect(wrapper.findAllComponents(VueHero)).toHaveLength(2)
})

Changing a handler to test an empty list

On our App.vue code we also have a special block to render when heroes list is empty:

<h3 class="test-empty-list" v-if="allHeroes.length === 0">
  No heroes found 😭
</h3>

Let's add a new test for this and let's now pass a handler to override a default one:

it('renders a message about no heroes when heroes list is empty', async () => {
  createComponent({
    // We pass a new handler here
    allHeroesQueryHandler: jest
      .fn()
      .mockResolvedValue({ data: { allHeroes: [] } }),
  })

  await wrapper.vm.$nextTick()

  expect(wrapper.find('.test-empty-list').exists()).toBe(true);
});

As you can see, our mocked handlers are flexible - we can change them on different tests. There is some space for further optimization here: we could change requestHandlers to have queries as keys and iterate over them to add handlers, but for the sake of simplicity I won't do this in the article.

Testing query error

Our application also renders an error in the case of failed query:

apollo: {
  allHeroes: {
    query: allHeroesQuery,
    error(e) {
      this.queryError = true
    },
  },
},

<h2 v-if="queryError" class="test-error">
  Something went wrong. Please try again in a minute
</h2>

Let's create a test for the error case. We would need to replace mocked resolved value with the rejected one:

it('renders error if query fails', async () => {
  createComponent({
    allHeroesQueryHandler: jest
      .fn()
      .mockRejectedValue(new Error('GraphQL error')),
  })

  // For some reason, when we reject the promise, it requires +1 tick to render an error
  await wrapper.vm.$nextTick()
  await wrapper.vm.$nextTick()

  expect(wrapper.find('.test-error').exists()).toBe(true)
})

Testing a mutation to add a new hero

Queries are covered! What about mutations, are we capable to test them properly as well? The answer is YES! First, let's take a look at our mutation code:

const hero = {
  name: this.name,
  image: this.image,
  twitter: this.twitter,
  github: this.github,
};
...
this.$apollo
  .mutate({
    mutation: addHeroMutation,
    variables: {
      hero,
    },
    update(store, { data: { addHero } }) {
      const data = store.readQuery({ query: allHeroesQuery });
      data.allHeroes.push(addHero);
      store.writeQuery({ query: allHeroesQuery, data });
    },
  })

Let's add two new constants to our mocks: the first one for the hero variable passed as a mutation parameter, and a second one - for the successful mutation response

...
import allHeroesQuery from '@/graphql/allHeroes.query.gql'
import addHeroMutation from '@/graphql/addHero.mutation.gql'

const heroListMock = {...}

const heroInputMock = {
  name: 'New Hero',
  github: '1000-contributions-a-day',
  twitter: 'new-hero',
  image: 'img.jpg',
}

const newHeroMockResponse = {
  data: {
    addHero: {
      __typename: 'Hero',
      id: '123',
      ...heroInputMock,
    },
  },
}

Again, be very careful about mocking a response! You would need to use a correct typename to match the GraphQL schema. Also, your response shape should be the same as a real GraphQL API response - otherwise, you will get a hiccup on tests

Now, we add a mutation handler to our handlers:

requestHandlers = {
  allHeroesQueryHandler: jest.fn().mockResolvedValue(heroListMock),
  addHeroMutationHandler: jest.fn().mockResolvedValue(newHeroMockResponse),
  ...handlers,
};

mockClient.setRequestHandler(
  addHeroMutation,
  requestHandlers.addHeroMutationHandler
);

It's time to start writing a mutation test! We will skip testing loading state here and we will check the successful response right away. First, we would need to modify our createComponent factory slightly to make it able to set component data (we need this to 'fill the form' to have correct variables sent to the API with the mutation):

const createComponent = (handlers, data) => {
  ...
  wrapper = shallowMount(AppComponent, {
    localVue,
    apolloProvider,
    data() {
      return {
        ...data,
      };
    },
  });
};

Now we can start creating a mutation test. Let's check if the mutation is actually called:

it('adds a new hero to cache on addHero mutation', async () => {
  // Open the dialog form and fill it with data
  createComponent({}, { ...heroInputMock, dialog: true })

  // Waiting for query promise to resolve and populate heroes list
  await wrapper.vm.$nextTick()

  // Submit the form to call the mutation
  wrapper.find('.test-submit').vm.$emit("click")

  expect(requestHandlers.addHeroMutationHandler).toHaveBeenCalledWith({
    hero: {
      ...heroInputMock,
    },
  });
});

Next step is to wait until mutation is resolved and check if it updated Apollo Client cache correctly:

it('adds a new hero to cache on addHero mutation', async () => {
  ...
  expect(requestHandlers.addHeroMutationHandler).toHaveBeenCalledWith({
    hero: {
      ...heroInputMock,
    },
  });

  // We wait for mutation promise to resolve and then we check if a new hero is added to the cache
  await wrapper.vm.$nextTick()

  expect(
    mockClient.cache.readQuery({ query: allHeroesQuery }).allHeroes
  ).toHaveLength(3)
});

Finally, we can wait for one more tick so Vue could re-render the template and we will check the actual rendered result:

it('adds a new hero to cache on addHero mutation', async () => {
  createComponent({}, { ...heroInputMock, dialog: true });

  await wrapper.vm.$nextTick()

  wrapper.find('.test-submit').vm.$emit("click")

  expect(requestHandlers.addHeroMutationHandler).toHaveBeenCalledWith({
    hero: {
      ...heroInputMock,
    },
  })

  await wrapper.vm.$nextTick();

  expect(
    mockClient.cache.readQuery({ query: allHeroesQuery }).allHeroes
  ).toHaveLength(3);

  // We wait for one more tick for component to re-render updated cache data
  await wrapper.vm.$nextTick()

  expect(wrapper.html()).toMatchSnapshot();
  expect(wrapper.findAllComponents(VueHero)).toHaveLength(3);
});

That's it! We also can mock mutation error the same way as we did for the query error but I believe this article is already long and boring enough 😅

You can find the full source code for the test here

Three awesome tools for GraphQL developer experience

Natalia Tepluhina — Mon, 06 Apr 2020 11:50:48 +0000

The thing I really like about GraphQL and Apollo Client is a developer experience they provide for me as a frontend engineer. In this article, we will take a look at some useful tools that make your everyday work easier!

Please note this article assumes you already have some experience with GraphQL

GraphQL explorer/playground

Usually, when we start working with the new API, the first thing we do is reading API documentation. In the days of good old REST API, I was really happy if I had descriptive documentation for every endpoint so things like Swagger were a real blessing. How things are going on the GraphQL side?

Let's check the documentation for Rick and Morty APIs

As you can see, the GraphQL part is documented very briefly comparing to REST... but there is a link to the playground there!

So, what is this? Basically, it's a playground where you can run GraphQL queries and mutations and check the result. Try to paste this query on the left side of the explorer and click the Run button:

query Characters {
  characters {
    results {
      id
      name
    }
  }
}

If you wonder about other queries this particular GraphQL endpoint has, please don't hesitate to click on the Docs tab on the right side! There you can find all the information about what parameters query expects, what fields you can specify to have in the response etc.

Also, if you try to write a different query, you'll notice that the playground also has a linting and autocompletion:

A playground shown on these screenshots is Prisma Playground. Other popular option is GraphiQL - for example, we're using it at GitLab as our GraphQL Explorer

Linting and autocomplete with IDE plugin

It's really nice to have a playground with all the bells and whistles but we still write the code in our IDEs/editors. Are there any tools to help us with this? Let's take a look at two popular IDEs: VS Code and WebStorm to see how they work with GraphQL.

VS Code

If your IDE of choice is VS Code, you would be probably interested in Apollo GraphQL extension by Apollo. It provides a lot of goodness: syntax highlighting, linting, autocomplete, navigating to fragments, etc.

After installing a plugin, you need to configure it properly. To do so, create an apollo.config.js file in your project root. Projects are configured through a top-level client key in this file:

// apollo.config.js

module.exports = {
  client: { ... },
};

Now we need to provide a schema for the plugin to operate. In the case of Rick and Morty API, we deal with the remote schema so we need to set the correct schema URL in the service property of the client:

// apollo.config.js

module.exports = {
  client: {
    service: {
      name: 'Rick and Morty',
      url: 'https://rickandmortyapi.com/graphql',
    },
  },
};

We can check how does it work for linting and autocompletion. Let's create a JS file and write a query using graphql-tag

import gql from 'graphql-tag';

const charactersQuery = gql`
  query CharactersQuery {
    characters {
      results {
        id
        name
      }
    }
  }
`;

When we start adding a new field, we can see how autocompletion works:

Also, if we add a non-existent field, it will be highlighted as an error:

The same features will work for .graphql or .gql files placed under the /src folder. If you want to include files outside of it, you should set up your client correctly

If you want to define some GraphQL types locally to use for Apollo state management, a plugin will automatically stitch the local schema with the remote one - so your local queries and mutations will be validated properly!

WebStorm

For WebStorm IDE, we can use a JS GraphQL plugin by Jim Kynde Meyer. After the installation, we should configure it by defining the way to your GraphQL schema. To do so, right-click on your project base folder and choose New -> GraphQL Configuration File.

This will result in creating a .graphqlconfig file in the root of your project with the following content

// .graphqlconfig
{
  "name": "Untitled GraphQL Schema",
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "Default GraphQL Endpoint": {
        "url": "http://localhost:8080/graphql",
        "headers": {
          "user-agent": "JS GraphQL"
        },
        "introspect": false
      }
    }
  }
}

Let's give our schema some name like "Remote Rick-n-Morty Schema". pathName option will define a name for the file where schema will be stored, we won't change it. For Rick and Morty API, we need to download the schema from the endpoint. For the Default GraphQL endpoint, we change a link from localhost to https://rickandmortyapi.com/graphql. We don't need any headers for this endpoint so we can safely remove this section.

Also, it would be nice to update the local GraphQL schema every single time we open the project! To achieve this, let's set introspect to true.

Now your config file should look like this

// .graphqlconfig

{
  "name": "Remote Rick-n-Morty Schema",
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "Default GraphQL Endpoint": {
        "url": "https://rickandmortyapi.com/graphql",
        "introspect": true
      }
    }
  }
}

Click on the GraphQL tab on the bottom of the IDE. You will see the information about our GraphQL schema...but so far the schema is empty!

Double-click on the Default GraphQL Endpoint and select Get GraphQL Schema from Endpoint (introspection).

Now, after the schema is fetched, we can check how does it work for linting and autocompletion. Let's create a JS file and write a query using graphql-tag

import gql from 'graphql-tag';

const charactersQuery = gql`
  query CharactersQuery {
    characters {
      results {
        id
        name
      }
    }
  }
`;

If we try to add a new field to the query, the plugin will give us a list of suggestions:

And if we type it wrong, we'll have an error highlighted:

These features also work for .graphql files. Unfortunately, the plugin is not able to recognize files with a .gql extension like VS Code plugin does. Also, unlike VS Code plugin, Webstorm one is not stitching local GraphQL schema with the remote one.

Apollo DevTools

We just learned about how to improve our developer experience when dealing with API endpoint itself and when writing GraphQL-related code in the editor. But what about debugging a GraphQL API interaction in the browser?

If you use the Apollo Client as your GraphQL client, you will be able to leverage their awesome Apollo DevTools extension for Chrome or Firefox browsers.

What could you do with this extension? Let's take a glance on how does it look in the browser:

GraphQL tab: this is actually a local GraphQL playground, similar to what we've described in the first part of the article. You can read schema docs here, write and run queries, just like on Prisma or GraphiQL:

Queries: here you can see all queries your application has called at this moment, inspect them and run them on the playground if necessary

Mutations: same as the previous tab but for GraphQL mutations
Cache: in my opinion, this one is the most useful. Here you can always check what do you have right now in the Apollo Client cache as a result of all the previous queries and mutations. It really saved my life when I had complex update logic in mutations and was completely lost about how they affect my cache.

I hope all the mentioned tools will make your life a bit easier when working with GraphQL! Please let me know in comments if you have any questions about them

Wrapping REST API calls with Apollo Client: 'do-it-yourself' approach

Natalia Tepluhina — Mon, 24 Feb 2020 13:07:08 +0000

Sometimes, when your application is in the middle of the migration from REST to GraphQL API, you might find yourself in the situation where data your need is split between both APIs. Let's say when you were fetching data from REST API, you were storing it in your application global state - be it Redux, MobX or Vuex. But with the new shiny GraphQL API you don't even need to bother about creating a boilerplate for storing the response - Apollo Client will take care of this process for you! Does it mean with two APIs you need to stick to the old good boring solution and ditch Apollo Client cache? Not at all!

You can wrap your REST API calls with Apollo and store results in Apollo cache too. If you have a large application and have many of them, you can use an apollo-link-rest library for this. In this article, we will create a basic DIY approach to this task to understand better how Apollo resolvers work and how we can use them in our application for good.

What we're going to build?

As an example, we will use a Vue single-page application built on top of Rick and Morty API. The good thing about this API is it has both REST and GraphQL endpoints, so we can experiment with it a bit.

Let's imagine our application was using REST API exclusively. So, on the frontend side, we had a Vuex store and we called axios queries from Vuex actions to fetch characters and episodes from the API.

// Vuex state

state: {
  episodes: [],
  characters: [],
  favoriteCharacters: [],
  isLoading: false,
  error: null
},

// Vuex actions

actions: {
  getEpisodes({ commit }) {
    commit('toggleLoading', true);
    axios
      .get('/episode')
      .then(res => commit('setEpisodes', res.data.results))
      .catch(err => commit('setError', error))
      .finally(() => commit('toggleLoading', false));
  },
  getCharacters({ commit }) {
    commit('toggleLoading', true);
    axios
      .get('/character')
      .then(res => commit('setCharacters', res.data.results))
      .catch(err => commit('setError', err))
      .finally(() => commit('toggleLoading', false));
  },
  addToFavorites({ commit }, character) {
    commit('addToFavorites', character);
  },
  removeFromFavorites({ commit }, characterId) {
    commit('removeFromFavorites', characterId);
  }
}

I don't list Vuex mutations here as they're pretty much intuitive - we assign fetched characters to state.characters etc.

As you can see, we needed to handle the loading flag manually as well as storing an error if something went wrong.

Every single character in characters array is an object:

Now let's imagine our backend developers created a query for us to fetch episodes, but characters still need to be fetched via REST API. So, how we can handle this?

Step 1: extend GraphQL schema

In GraphQL, anything we can fetch from the endpoint, must have a type and be defined in GraphQL schema. Let's be consistent and add characters to schema too. 'But how?' - you might ask, 'schema is defined on the backend!'. That's true but we can extend this schema on the frontend too! This process is called schema stitching. While this step is completely optional, I would still recommend always define GraphQL type definitions for your entities even if they are local. It helps you if you use a code generation to create e.g. TypeScript types from the GraphQL schema and also it enables validation and auto-completion if you use an Apollo plugin in your IDE.

Let's create a new type for characters. We will be using graphql-tag to parse the string to GraphQL type:

// client.js

import gql from "graphql-tag";

const typeDefs = gql`
  type Character {
    id: ID!
    name: String
    location: String
    image: String
  }
`;

As you can see, here we don't use all the fields from the character object, only those we need.

Now we also need to extend a Query type with the GraphQL characters query:

// client.js

import gql from "graphql-tag";

const typeDefs = gql`
  type Character {
    id: ID!
    name: String
    location: String
    image: String
  }
  extend type Query {
    characters: [Character]
  }
`;

To stitch this part of the schema with the schema fetched from the GraphQL endpoint, we need to pass typeDefs to the GraphQL client options:

// client.js

import { ApolloClient } from "apollo-client";
import { createHttpLink } from "apollo-link-http";
import { InMemoryCache } from "apollo-cache-inmemory";
import gql from "graphql-tag";

const httpLink = createHttpLink({
  uri: "https://rickandmortyapi.com/graphql"
});

const cache = new InMemoryCache();

const typeDefs = gql`
  type Character {
    id: ID!
    name: String
    location: String
    image: String
  }
  extend type Query {
    characters: [Character]
  }
`;

export const apolloClient = new ApolloClient({
  link: httpLink,
  cache,
  typeDefs
});

Step 2: Writing a query and a resolver

We need to define a GraphQL query with a @client directive to be called when we want to fetch characters. @client directive tells Apollo Client not to fetch this data from the GraphQL endpoint but the local cache. Usually, I keep queries in .gql files and add a graphql-tag/loader to webpack configuration to be able to import them.

// characters.query.gql

query Characters {
  characters @client {
    id
    name
    location
    image
  }
}

But there is one issue: there are no characters in the local cache! How do we 'explain' to Apollo Client where it can get this data? For these purposes, we need to write a resolver. This resolver will be called every time we try to fetch characters to render them in our application.

Let's create a resolvers object and define a resolver for characters query

// client.js

const resolvers = {
  Query: {
    characters() {
      ...
    }
  }
};

What should we do here? Well, we need to perform the same axios call we did in Vuex action! We will map response fields to our GraphQL type fields to make a structure plainer:

// client.js

const resolvers = {
  Query: {
    characters() {
      return axios.get("/character").then(res =>
        res.data.results.map(char => ({
          __typename: "Character",
          id: char.id,
          name: char.name,
          location: char.location.name,
          image: char.image
        }))
      );
    }
  }
};

That's it! Now, when we call GraphQL characters query, our resolver will perform a REST API call and return a result for us. Bonus point: $apollo.queries.characters.loading property will change accordingly when the REST API call is in progress! Also, if some error happens on this call. the Apollo query error hook will be triggered.

Conclusion

As you can see, having a part of the API on the REST endpoint doesn't prevent you from using Apollo Client and its cache. Any REST API call could be wrapped with Apollo resolver and its result can be stored to the Apollo cache which can simplify the migration process.

Vue Apollo v4: the first look

Natalia Tepluhina — Fri, 03 Jan 2020 14:09:08 +0000

This post requires you to be already familiar with the basics of GraphQL, Apollo Client, and Vue. Shameless plug: I've tried to cover this in my talk on using Vue with Apollo. We will also use Vue Composition API. If you're not familiar with this concept, I'd highly recommend reading the Vue Composition API RFC

A few weeks ago, an alpha of version 4 of vue-apollo (the integration of Apollo client for Vue.js) was released, and I immediately decided to give it a try. What's so exciting in this version? In addition to the existing API, it has a composables option based on Vue Composition API. I've had extensive experience with vue-apollo in the past and decided to check how new API feels compared to the previous ones.

An example we're going to use

To explore the new API, I will use one of the examples already shown in my Vue+Apollo talk - I call it 'Vue Heroes'. It's a straightforward application that has one query for fetching all the heroes from the GraphQL API and two mutations: one for adding heroes and one for deleting them. The interface looks like this:

You can find the source code with the old Options API here. The GraphQL server is included; you need to run it to make the application work.

yarn apollo

Now let's start refactoring it to the new version.

Installation

As a first step, we can safely remove an old version of vue-apollo from the project:

yarn remove vue-apollo

And we need to install a new one. Starting from version 4, we can choose what API we're going to use and install the required package only. In our case, we want to try a new composables syntax:

yarn add @vue/apollo-composable

Composition API is a part of Vue 3, and it's still not released now. Luckily, we can use a standalone library to make it work with Vue 2 as well, so for now, we need to install it as well:

yarn add @vue/composition-api

Now, let's open the src/main.js file and make some changes there. First, we need to include Composition API plugin to our Vue application:

// main.js

import VueCompositionApi from "@vue/composition-api";

Vue.use(VueCompositionApi);

We need to set up an Apollo Client using the new apollo-composable library. Let's define a link to our GraphQL endpoint and create a cache to pass them later to the client constructor:

// main.js

import { createHttpLink } from "apollo-link-http";
import { InMemoryCache } from "apollo-cache-inmemory";

const httpLink = createHttpLink({
  uri: "http://localhost:4000/graphql"
});

const cache = new InMemoryCache();

Now, we can create an Apollo Client instance:

// main.js

import { createHttpLink } from "apollo-link-http";
import { InMemoryCache } from "apollo-cache-inmemory";
import { ApolloClient } from "apollo-client";

const httpLink = createHttpLink({
  uri: "http://localhost:4000/graphql"
});

const cache = new InMemoryCache();

const apolloClient = new ApolloClient({
  link: httpLink,
  cache
});

Creating a client wasn't really different from the previous version of Vue Apollo, and it actually has nothing to do with Vue so far - we're just setting up an Apollo Client itself. What is different is the fact we don't need to create an apolloProvider anymore! We simply do natively provide a client to Vue application without an ApolloProvider instance:

// main.js
import { provide } from "@vue/composition-api";
import { DefaultApolloClient } from "@vue/apollo-composable";

new Vue({
  setup() {
    provide(DefaultApolloClient, apolloClient);
  },
  render: h => h(App)
}).$mount("#app");

provide here is imported from the @vue/composition-api package, and it enables dependency injection similar to the 2.x provide/inject options. The first argument in provide is a key, second is a value

3.x	4.x composables syntax

Adding a query

To have a list of Vue heroes on the page, we need to create the allHeroes query:

// graphql/allHeroes.query.gql

query AllHeroes {
  allHeroes {
    id
    name
    twitter
    github
    image
  }
}

We're going to use it in our App.vue component so let's import it there:

// App.vue

import allHeroesQuery from "./graphql/allHeroes.query.gql";

With the Options API we used this query in the Vue component apollo property":

// App.vue

  name: "app",
  data() {...},
  apollo: {
    allHeroes: {
      query: allHeroesQuery,s
    }
  }

Now we will modify App.vue to make it work with Composition API. In fact, it will require to include one more option to an existing component - a setup:

// App.vue

export default {
  name: "app",
  setup() {},
  data() {...}

Here, within the setup function, we will work with vue-apollo composables, and we'll need to return the results to use them in the template. Our first step is to get a result of allHeroes query, so we need to import our first composable and pass our GraphQL query to it:

// App.vue

import allHeroesQuery from "./graphql/allHeroes.query.gql";
import { useQuery } from "@vue/apollo-composable";
export default {
  name: "app",
  setup() {
    const { result } = useQuery(allHeroesQuery);

    return { result }
  },
  data() {...}

useQuery can accept up to three parameters: first is GraphQL document containing the query, second is variables object, and the third is query options. In this case, we use default options, and we don't need to pass any variables to the query, so we're passing only the first one

What is the result here? It's exactly matching the name - it's a result of the GraphQL query, containing allHeroes array, but it's also a reactive object - so it's a Vue ref. That's why it wraps the resulting array in the value property:

As Vue makes an automatic unwrap for us in the template, we can simply iterate over result.allHeroes to render the list:

<template v-for="hero in result.allHeroes">

However, the initial value of this array is going to be undefined because the result is still loading from the API. We can add a check here to be sure we already have a result like result && result.allHeroes but v4 has a useful helper to do this for us - useResult. It's a great utility to help you shaping the result you fetched from the API, especially useful if you need to get some deeply nested data or a few different results from one query:

<template v-for="hero in allHeroes">

<script>
import { useQuery, useResult } from "@vue/apollo-composable";
export default {
  setup() {
    const { result } = useQuery(allHeroesQuery);
    const allHeroes = useResult(result, null, data => data.allHeroes)

    return { allHeroes }
  },
}
</script>

useResult takes three parameters: the result of GraphQL query, a default value (null in our case), and a picking function that returns data we want to retrieve from the result object. If the result contains the only one property (like allHeroes in our case), we can simplify it a bit:

// App.vue

setup() {
  const { result } = useQuery(allHeroesQuery);
  const allHeroes = useResult(result)

  return { allHeroes }
},

The only thing left is to display a loading status when we're actually fetching the data from he API. Aside from the result, useQuery can return a loading as well:

// App.vue
setup() {
  const { result, loading } = useQuery(allHeroesQuery);
  const allHeroes = useResult(result)

  return { allHeroes, loading }
},

And we can render it conditionally in out template:

<h2 v-if="loading">Loading...</h2>

Let's compare the code we had for v3 with the new one:

3.x	4.x composables syntax

While the new syntax is more verbose, it's also more customizable (to shape the response, we would need to add an update property to v3 syntax). I like we can expose loading properly for every single query instead of using it as a nested property of the global $apollo object.

Working with mutations

Now let's also refactor mutations we have to the new syntax as well. In this application, we have two mutations: one to add a new hero and one to delete an existing hero:

// graphql/addHero.mutation.gql

mutation AddHero($hero: HeroInput!) {
  addHero(hero: $hero) {
    id
    twitter
    name
    github
    image
  }
}

// graphql/deleteHero.mutation.gql

mutation DeleteHero($name: String!) {
  deleteHero(name: $name)
}

In the Options API syntax, we were calling mutation as a method of the Vue instance $apollo property:

this.$apollo.mutate({
  mutation: mutationName,
})

Let's start refactoring with the addHero one. Similarly to query, we need to import the mutation to the App.vue and pass it as a parameter to useMutation composable function:

// App.vue

import addHeroMutation from "./graphql/addHero.mutation.gql";
import { useQuery, useResult, useMutation } from "@vue/apollo-composable";

export default {
  setup() {
    const { result, loading } = useQuery(allHeroesQuery);
    const allHeroes = useResult(result)

    const { mutate } = useMutation(addHeroMutation)
  },
}

The mutate here is actually a method we need to call to send the mutation to our GraphQL API endpoint. However, in the case of addHero mutation, we also need to send a variable hero to define the hero we want to add to our list. The good thing is that we can return this method from the setup function and use it within the Options API method. Let's also rename the mutate function as we'll have 2 mutations, so giving it a more intuitive name is a good idea:

// App.vue

setup() {
  const { result, loading } = useQuery(allHeroesQuery);
  const allHeroes = useResult(result)

  const { mutate: addNewHero } = useMutation(addHeroMutation)

  return { allHeroes, loading, addNewHero }
},

Now we can call it in the addHero method already present in the component:

export default {
  setup() {...},
  methods: {
    addHero() {
      const hero = {
        name: this.name,
        image: this.image,
        twitter: this.twitter,
        github: this.github,
        github: this.github
      };

      this.addNewHero({ hero });
    }
  }
}

As you can see, we passed a variable at the moment mutation is called. There is an alternative way, we can also add variables to the options object and pass it to the useMutation function as a second parameter:

const { mutate: addNewHero } = useMutation(addHeroMutation, {
  variables: {
    hero: someHero
  }
})

Now our mutation will be successfully sent to the GraphQL server. Still, we also need to update the local Apollo cache on a successful response - otherwise, the list of heroes won't change until we reload the page. So, we also need to read the allHeroes query from Apollo cache, change the list adding a new hero and write it back. We will do this within the update function (we can pass it with the options parameter as we can do with variables):

// App.vue

setup() {
  const { result, loading } = useQuery(allHeroesQuery);
  const allHeroes = useResult(result)

  const { mutate: addNewHero } = useMutation(addHeroMutation, {
    update: (cache, { data: { addHero } }) => {
      const data = cache.readQuery({ query: allHeroesQuery });
      data.allHeroes = [...data.allHeroes, addHero];
      cache.writeQuery({ query: allHeroesQuery, data });
    }
  })

  return { allHeroes, loading, addNewHero }
},

Now, what's about loading state when we're adding a new hero? With v3 it was implemented with creating an external flag and changing it on finally:

// App.vue

export default {
  data() {
    return {
      isSaving: false
    };
  },
  methods: {
    addHero() {
      ...
      this.isSaving = true;
      this.$apollo
        .mutate({
          mutation: addHeroMutation,
          variables: {
            hero
          },
          update: (store, { data: { addHero } }) => {
            const data = store.readQuery({ query: allHeroesQuery });
            data.allHeroes.push(addHero);
            store.writeQuery({ query: allHeroesQuery, data });
          }
        })
        .finally(() => {
          this.isSaving = false;
        });
    }
  }
}

In v4 composition API we can simply return the loading state for a given mutation from the useMutation function:

setup() {
  ...
  const { mutate: addNewHero, loading: isSaving } = useMutation(
    addHeroMutation,
    {
      update: (cache, { data: { addHero } }) => {
        const data = cache.readQuery({ query: allHeroesQuery });
        data.allHeroes = [...data.allHeroes, addHero];
        cache.writeQuery({ query: allHeroesQuery, data });
      }
    }
  );

  return {
    ...
    addNewHero,
    isSaving
  };
}

Let's compare the code we had for v3 with v4 composition API:

3.x	4.x composables syntax

In my opinion, the composition API code became more structured, and it also doesn't require an external flag to keep the loading state.

deleteHero mutation could be refactored in a really similar way except one important point: in update function we need to delete a hero found by name and the name is only available in the template (because we're iterating through the heroes list with v-for directive and we can't get hero.name outside of the v-for loop). That's why we need to pass an update function in the options parameter directly where the mutation is called:

<vue-hero
  v-for="hero in allHeroes"
  :hero="hero"
  @deleteHero="
    deleteHero(
      { name: $event },
      {
        update: cache => updateHeroAfterDelete(cache, $event)
      }
    )
  "
  :key="hero.name"
></vue-hero>

<script>
  export default {
    setup() {
      ...

      const { mutate: deleteHero } = useMutation(deleteHeroMutation);
      const updateHeroAfterDelete = (cache, name) => {
        const data = cache.readQuery({ query: allHeroesQuery });
        data.allHeroes = data.allHeroes.filter(hero => hero.name !== name);
        cache.writeQuery({ query: allHeroesQuery, data });
      };
      return {
        ...
        deleteHero,
        updateHeroAfterDelete,
      };
    }
  }
</script>

Conclusions

I really like the code abstraction level provided with vue-apollo v4 composables. Without creating a provider and injecting an $apollo object to Vue instance, there will be easier to mock Apollo client in unit tests. The code also feels more structured and straightforward to me. I will be waiting for the release to try in on the real-world projects!

Data visualizations with Vue and D3: counting stars (part 2)

Natalia Tepluhina — Mon, 21 Oct 2019 13:51:43 +0000

You can find the first part of this article here.

If you skipped part 1, here is the code to start with 😉

What are we going to build?

In this article, we will improve our star example with D3 data scaling. Scale functions are JavaScript functions that:

take an input (usually a number, date or category) and
return a value (such as a coordinate, a color, a length or a radius).

They’re typically used to transform (or map) data values into visual variables (such as position, length, and color). This way, we can quickly 'draw' any set of initial data as SVG.

So, we will map our star 'visuals' to specific data values. At the end of the article, our star will look this way:

Scaling star radius

The first obvious question is: why do we need to scale the radius? Can't we use the value without scaling, as we did for rays in the previous article?

The reason is we want to limit our star outer radius while input data value can vary in a vast range. D3 will calculate the ratio and scale our star radius proportionally.

For the first iteration, let's say our input value will scale from 10 to 1000, but we want to display a star with a max radius of 250px. To perform the calculation, we're going to use D3 scaleLinear method.

scaleLinear constructs a new continuous scale with the specified domain and range. Each range value y can be expressed as a function of the domain value x: y = mx + b. (D3 Wiki)

First, let's remove our hardcoded outerRadius from data and let's create a new computed property to calculate it. Instead, we will add a radius property to data; it will serve as our input value.

data() {
  return {
    radius: 300,
    rays: 8,
  };
},
computed: {
  outerRadius() {
    return this.radius
  },
  ...
},

So, for now outerRadius just returns what we put in radius. Now, let's add some scaling to it! First, we need to import scaleLinear method from D3:

import { lineRadial } from 'd3-shape';
import { scaleLinear } from 'd3-scale';

We need to define a scaling function using scaleLinear method and then we need to call this function with our input radius as a parameter:

computed: {
  outerRadius() {
    const scale = scaleLinear()
      .domain([10, 1000])
      .range([5, 250]);

    return this.radius
  },
  ...
},

What's happening here? We provided a domain to scaleLinear, and it's the range in which our input value is going to change. As for range, it's what we have as an output: we expect our outerRadius to change in the range between 5px and 250px.

Now we can pass radius to the scale function:

computed: {
  outerRadius() {
  const scale = scaleLinear()
    .domain([10, 1000])
    .range([5, 250]);

  return scale(this.radius)
  },
  ...
},

As a result, we will have something like this:

Try to change the radius property to 500 or 1000, and you will see how the star grows in size.

Now, similarly to rays, let's add an input to change star radius dynamically. In our template, let's add

<div class="range-input">
  <label for="radius">Radius</label>
  <input name="radius" type="range" min="10" max="1000" v-model="radius" />
</div>

This way, we have bound our radius data property to the input field value.

Styling the app

Now we can change star radius and rays amount, but it still keeps this dull green color. What if we can improve it? If our star were a real star, it would change its color proportionally to its temperature, from red to blue. Can we create a scale that will do the same? With D3, the answer is obvious 😊.

But before we start working on it, let's style our application a bit. First, let's move sliders to the right side of our image. To do so, we need to change the template slightly:

<template>
  <section class="wrapper">
    <svg width="500" height="500">
      <path
        class="radial"
        :d="radialData"
        transform="translate(250, 250)"
        fill="green"
      ></path>
    </svg>
    <aside>
      <div class="range-input">
        <input name="rays" type="range" min="4" max="60" v-model="rays" />
        <label for="rays">Rays</label>
      </div>
      <div class="range-input">
        <input
          name="radius"
          type="range"
          min="10"
          max="1000"
          v-model="radius"
        />
        <label for="radius">Radius</label>
      </div>
    </aside>
  </section>
</template>

And let's add some styles to the style section:

<style lang="scss">
  .wrapper {
    display: flex;
    align-items: center;
  }
  aside {
    padding-left: 20px;

    .range-input {
      display: flex;
      align-items: center;
      margin-bottom: 10px;
      input {
        margin-right: 10px;
      }
    }
  }
</style>

Now our app looks more structured:

Also, we want our star to be lighter, like... well, like real stars! Let's give it a dark background with a deep blue rectangle and let's change star color to white for now.

<svg width="500" height="500">
  <rect width="100%" height="100%" fill="#0e0432" />
  <path
    class="radial"
    :d="radialData"
    transform="translate(250, 250)"
    fill="white"
  ></path>
</svg>

Now we can play with changing star color!

Creating a custom scale for star color

While D3 has built-in color interpolators, we want to build our simple one. We will take an input value from 0 to 100, and we will define a color for 0, 25, 50, 75 and 100 marks. D3 is smart enough to interpolate the color for in-between values.

As a first step, let's create a new data property - heat and set it to be 5:

data() {
  return {
    radius: 300,
    rays: 8,
    heat: 5,
  };
},

Next, let's create a new computed property for star color calculation:

starColor() {
  return this.heat
},

And finally we're ready to create a new scale:

starColor() {
  const myColor = scaleLinear()
    .domain([0, 25, 50, 75, 100])
    .range(['#ff7665', '#ffb469', '#ffe876', '#fff', '#99cdff']);
  return myColor(this.heat);
},

Now, we have a star color ready to be added to our SVG path fill property instead of static white color. Let's create a dynamic binding there:

<path
  class="radial"
  :d="radialData"
  transform="translate(250, 250)"
  :fill="starColor"
></path>

Our star has changed the color!

Let's try to change the heat data property to 90, and a star will become light blue. To make it look nicer, we can create a gradient from white to current star color:

<svg width="500" height="500">
  <defs>
    <radialGradient id="starGradient">
      <stop offset="2%" stop-color="white" />
      <stop offset="95%" :stop-color="starColor" />
    </radialGradient>
  </defs>
  ...
</svg>

And now we can fill our star with this gradient instead of solid color:

<svg width="500" height="500">
  <defs>
    <radialGradient id="starGradient">
      <stop offset="2%" stop-color="white" />
      <stop offset="95%" :stop-color="starColor" />
    </radialGradient>
  </defs>
  <rect width="100%" height="100%" fill="#0e0432" />
  <path
    class="radial"
    :d="radialData"
    transform="translate(250, 250)"
    fill="url(#starGradient)"
  ></path>
</svg>

Now our star is really nice-looking:

And the last thing left is to add the same input slider as we did previously for rays and radius:

<div class="range-input">
  <input name="heat" type="range" min="0" max="100" v-model="heat" />
  <label for="heat">Heat</label>
</div>

And we're ready to go! You can find the final code of the Chart component here.

What's next?

In part 3, we're going to create not a single star but the whole constellation! And we will visualize a real dataset of Vue repositories:

Apollo state management in Vue application

Natalia Tepluhina — Wed, 01 May 2019 09:32:42 +0000

This article assumes you already know what GraphQL and Apollo client are and you're able to build Vue applications with Vue CLI

🤔 Why do we need Apollo local state management?

Imagine a Vue application fetching some data from a REST API. Where do you usually store this data? Probably, the answer would be 'in the local component state' or, if application is big enough, 'in the Vuex store with the rest of data'. This answer makes sense, because we can have the single source of truth for our application.

Now imagine an application fetching data from a GraphQL endpoint with Apollo client. By default, Apollo will store this data to Apollo cache. But what if we have some local application state, stored in Vuex? If we copy data from Apollo cache to Vuex, we're doubling our data. If we leave data from the API in Apollo and local data in Vuex, there will be two sources of truth. What would be a good way to store local data?

Previously there was a library named apollo-link-state to manage local data. But since Apollo 2.5 release, we don't need it anymore because this functionality is now a part of Apollo core. So, we can simply manage our local state without adding any new dependencies 🎉

🏗️ What are we going to build

Let's try to create a simple to-do application with Vue and Apollo client.

I've started with a Vue CLI-powered to-do application with some custom styles. You can find its source code here.

🔧 Add Apollo to Vue application

First thing we need is to install Apollo client and integrate it to our Vue app. For integration, we will use vue-apollo plugin.

To install everything we need, type the following command in the terminal:

npm install --save vue-apollo graphql apollo-boost

yarn add vue-apollo graphql apollo-boost

Then open main.js file and add

// main.js

Vue.use(VueApollo);

This way we're adding the vue-apollo plugin to our Vue application.

Now we need to configure our Apollo client. First, let's add an import on the top of main.js file:

// main.js

import ApolloClient from 'apollo-boost';
// rest of imports

Vue.use(VueApollo);

Then, let's create a client:

// main.js

import ApolloClient from 'apollo-boost';
// rest of imports

Vue.use(VueApollo);

const apolloClient = new ApolloClient({});

Add a provider based on this newly created client and inject it to Vue application instance:

// main.js

const apolloProvider = new VueApollo({
  defaultClient: apolloClient,
});

new Vue({
  render: h => h(App),
  apolloProvider, //here goes your Apollo provider
}).$mount('#app');

Now we're ready to create an Apollo-powered store.

🗃️ Initializing an Apollo cache

We're going to initialize an Apollo cache where we will store our to-do items. Apollo has an InMemoryCache constructor to do this:

// main.js

import ApolloClient from 'apollo-boost';
import { InMemoryCache } from 'apollo-cache-inmemory';

// rest of imports

const cache = new InMemoryCache();

Now we need to add it to our client:

// main.js

const apolloClient = new ApolloClient({
  cache,
});

So far our cache is empty and we're going to add some data to it. But first let's create a local schema. This step could be optional, but just like how a schema is the first step toward defining our data model on the server, writing a local schema is the first step we take on the client.

📃 Creating a local schema

Let's think for a minute: what should our to-do item look like? It definitely needs to have some text but what else? Probably we need some property to define if it's already done or not and also an ID to distinguish one todo-item from another. So, it should be an object with three properties:

{
  id: 'uniqueId',
  text: 'some text',
  done: false
}

Now we're ready to add item type to GraphQL local schema.

Let's create a new file resolvers.js in the src folder and add the following code to it

import gql from 'graphql-tag';

export const typeDefs = gql`
  type Item {
    id: ID!
    text: String!
    done: Boolean!
  }
`;

gql here stands for the JavaScript template literal tag that parses GraphQL query strings.

Awesome! Let's import typeDefs and add them to our Apollo client:

// main.js

import ApolloClient from 'apollo-boost';
import { InMemoryCache } from 'apollo-cache-inmemory';
import { typeDefs } from './resolvers';
// rest of imports

const apolloClient = new ApolloClient({
  cache,
  typeDefs,
  resolvers: {},
});

Please note the empty resolvers object here: if we don't assign it to the Apollo client options, it won't recognize the queries to local state and will try to send a request to remote URL instead

Now we need to add some initial data to our cache. To directly write it here, we will use the writeData method:

// main.js

// apollo client code

cache.writeData({
  data: {
    todoItems: [
      {
        __typename: 'Item',
        id: 'dqdBHJGgjgjg',
        text: 'test',
        done: true,
      },
    ],
  },
});

// apollo provider code

We've just added an array of todoItems to our cache data and we are saying that every item has a type name of Item (specified in our local schema).

Now we're ready to query our local data from our Vue component!

🔦 Query local data

First, we need to build a GraphQL query to retrieve the data. Let's create a graphql folder, add a queries.js file to it and import graphql-tag there.

// queries.js

import gql from 'graphql-tag';

Now let's write a query:

// queries.js

import gql from 'graphql-tag';

export const todoItemsQuery = gql`
  {
    todoItems @client {
      id
      text
      done
    }
  }
`;

So, we defined the name of the query here (todoItems) and we specified that this query should not be executed against remote GraqhQL API. @client directive here tells Apollo client it should fetch results in the local data store.

Finally, we're ready to send the query from the Vue component. To do so, let's open our App.vue, import the query constant there:

<script>
import {
  todoItemsQuery,
} from "./graphql/queries.js";

export default {
// rest of App.vue

and create an Apollo query in the component:

// App.vue

export default {
  ...
  apollo: {
    todoItems: {
      query: todoItemsQuery
    }
  },
  ...

Can you believe it's enough to get everything we need? In fact, yes! This query will effectively fetch our local data and store it to App.vue's todoItems property.

✏️ Change local data

Now we need to find a way to change the data in store: add new item, delete item or toggle item's done property.

We already did change the local data when we were setting initial todoItems to the cache. This way is named direct cache write and is useful for initial setup or doing some very simple changes.

For more complicated changes in GraphQL we use mutations. So let's go back to our schema and define some mutations there!

// resolvers.js

export const typeDefs = gql`
  type Item {
    id: ID!
    text: String!
    done: Boolean!
  }

  type Mutation {
    changeItem(id: ID!): Boolean
    deleteItem(id: ID!): Boolean
    addItem(text: String!): Item
  }
`;

We've just added three mutations to perform different operations with our todoItems. Two of them (changeItem and deleteItem) take the item ID; addItem requires a text to create a new item and we're going to generate a unique ID for it.

Checking/unchecking a todo-item

We will start with changeItem mutation. First of all, let's add it to our queries.js file:

// queries.js
...
export const checkItemMutation = gql`
  mutation($id: ID!) {
    checkItem(id: $id) @client
  }
`;

We defined a local mutation (because we have a @client directive here) that will accept an ID. Now, we need a resolver: a function that resolves a value for a type or field in a schema.

In our case, resolver will define what changes do we want to make to our local Apollo cache when we have a certain mutation. Local resolvers have the same function signature as remote resolvers ((parent, args, context, info) => data). In fact, we will need only args (arguments passed to the mutation) and context (we will need its cache property to read and write data)

Let's start with adding resolvers const to our resolvers.js file.

// resolvers.js

export const resolvers = {
  Mutation: {
    checkItem: (_, { id }, { cache }) => {},
};

So, we created a resolver for checkItem and so far it doesn't do anything. We passed an id from mutation arguments and cache from context to it using ES6 object destructuring. Let's read our cache to retrieve current todoItems:

// resolvers.js

import { todoItemsQuery } from './graphql/queries';

export const resolvers = {
  Mutation: {
    checkItem: (_, { id }, { cache }) => {
      const data = cache.readQuery({ query: todoItemsQuery });
    },
};

As you can see, we imported our todoItemsQuery to tell our resolver what exactly we're reading from Apollo cache. Now let's add a logic to change done property value to an opposite:

// resolvers.js

import { todoItemsQuery } from './graphql/queries';

export const resolvers = {
  Mutation: {
    checkItem: (_, { id }, { cache }) => {
      const data = cache.readQuery({ query: todoItemsQuery });
      const currentItem = data.todoItems.find(item => item.id === id);
      currentItem.done = !currentItem.done;
    },
};

Finally, we need to write our changed data back to the cache and return the value of currentItem.done:

// resolvers.js

import { todoItemsQuery } from './graphql/queries';

export const resolvers = {
  Mutation: {
    checkItem: (_, { id }, { cache }) => {
      const data = cache.readQuery({ query: todoItemsQuery });
      const currentItem = data.todoItems.find(item => item.id === id);
      currentItem.done = !currentItem.done;
      cache.writeQuery({ query: todoItemsQuery, data });
      return currentItem.done;
    },
};

Now our resolver is ready and we're going to call our mutation from the Vue component. Let's go back to the App.vue, import the mutation there and change the checkItem method:

<script>
  import {
    todoItemsQuery,
    checkItemMutation,
  } from "./graphql/queries.js";

  export default {
    ...
    methods: {
      checkItem(id) {
        this.$apollo.mutate({
          mutation: checkItemMutation,
          variables: { id }
        });
      },
    }
  };
</script>

What's going on here? We call the $apollo.mutate method (provided with vue-apollo plugin) and we pass the mutation we created earlier in queries.js and an id variable (ID is passed from the template where we're checking the item):

<ListItem
  v-for="(item, index) in todoItems"
  :key="index"
  :content="item"
  @toggleDone="checkItem(item.id)"
  @delete="deleteItem(item.id)"
/>

Now when we're clicking on the checkbox, we will send a mutation that changes our local state. We can see immediately that our todoItems array is changed with this mutation so checkbox becomes checked/unchecked.

Deleting an item

Now we need the way to delete an item. Let's start again with creating a deleteItem mutation:

// queries.js

export const deleteItemMutation = gql`
  mutation($id: ID!) {
    deleteItem(id: $id) @client
  }
`;

As you can see, it's very similar to the previous one: again, we're passing an ID as a parameter. Now let's add a resolver for it:

// resolvers.js

deleteItem: (_, { id }, { cache }) => {
  const data = cache.readQuery({ query: todoItemsQuery });
  const currentItem = data.todoItems.find(item => item.id === id);
  data.todoItems.splice(data.todoItems.indexOf(currentItem), 1);
  cache.writeQuery({ query: todoItemsQuery, data });
  return true;
},

Again, we're reading the todoItemsQuery from the cache as a first step and writing it back later (and we're simply returning true to show the request was successful). But instead of changing currentItem we're just removing it from the todoItems array.

Now let's add this mutation to the App.vue.

<script>
  import {
    todoItemsQuery,
    checkItemMutation,
    deleteItemMutation
  } from "./graphql/queries.js";

  export default {
    ...
    methods: {
      deleteItem(id) {
        this.$apollo.mutate({
          mutation: deleteItemMutation,
          variables: { id }
        });
      }
    }
  };
</script>

Very similar to checkItem, isn't it?

Adding new item

While the two previous mutations were really similar to each other, addItem will be different. First of all, we will pass a text, not an ID, and we want to be able to see what is actually added:

// queries.js

export const addItemMutation = gql`
  mutation($text: String!) {
    addItem(text: $text) @client {
      id
      text
      done
    }
  }
`;

You can assume the resolver will be more complex as well: we need to generate a unique ID somehow. For this project we're going to use shortid library:

npm install shortid

yarn add shortid

Now let's start building our resolver:

// resolvers.js
import shortid from 'shortid';

export const resolvers = {
  Mutation: {
    ...
    addItem: (_, { text }, { cache }) => {
      const data = cache.readQuery({ query: todoItemsQuery });
      const newItem = {
        __typename: 'Item',
        id: shortid.generate(),
        text,
        done: false,
      };
    },
  }
}

As you can see, now we're taking a text from our mutation arguments and set a newItem text property equal to it. For id we're generating a new unique ID with shortid.generate method. As for done property, we always set it to false when creating a new todo-item (because obviously it's not done yet!).

Now we need only to push this newly created item to the todoItems array, write the data back to the cache and return a newItem as a mutation result.

// resolvers.js

addItem: (_, { text }, { cache }) => {
  const data = cache.readQuery({ query: todoItemsQuery });
  const newItem = {
    __typename: 'Item',
    id: shortid.generate(),
    text,
    done: false,
  };
  data.todoItems.push(newItem);
  cache.writeQuery({ query: todoItemsQuery, data });
  return newItem;
},

We're ready to call our addItem mutation from the component! Let's import it to App.vue...

<script>
  import {
    todoItemsQuery,
    checkItemMutation,
    addItemMutation,
    deleteItemMutation
  } from "./graphql/queries.js";
  ...
</script>

...and add it to the addItem method:

  addItem() {
    if (this.newItem) {
      this.$apollo.mutate({
        mutation: addItemMutation,
        variables: { text: this.newItem }
      });
      this.newItem = "";
    }
  },

newItem here represents a string from the input field and we're going to call a mutation only when we have some actual text to send. Also, after we've added a new item, we want to clear an input.

Yay, our application is ready! 🎉

You can find the full application source code here.

Useful links

Building a Desktop App with Vue: NW.js

Natalia Tepluhina — Mon, 14 Jan 2019 12:47:30 +0000

Previously I've written two articles about building desktop applications with Vue framework: one for Vuido library and one for Electron. I've had some comments requesting an article about NW.js and I promised to write one... and here we go! Better late than never 😅

NW.js (previosly known as node-webkit) is a framework for building desktop applications with HTML, CSS, and JavaScript. It's based on Chromium and Node.js. NW.js lets you call Node.js code and modules directly from browser and also use Web technologies in your app. Further, you can easily package a web application to a native application.

⚛️ Differences from Electron

Electron and NW.js share many features: they are both built on top of Chromium and Node.js and use HTML, CSS and JS for building a desktop app. But they also have some notable differences:

In NW.js the main entry point of an application is a web page or a JS script. You specify this entry via package.json main property. In Electron, the entry point is a JavaScript script. Instead of providing a URL directly, you manually create a browser window and load an HTML file using the API.
On build process NW.js builds all Chromium; Electron uses libchromiumcontent to access Chromium's Content API
NW.js has built-in support for compiling your source code to protected binaries. Electron is packaging its applications with asar, which contains the applications' unprotected source code.

💻 What are we going to build

Now when we understand differences with Electron, we're going to build the same application as in the previous article: an app to check the weather in the city of user's choice built on top of OpenWeatherMap API. This project will be built with Vue CLI and I recommend this way to scaffold any Vue application.

If you want just to check the final NW.js app code, it's here.

🛠️ Installation

Creating an app with Vue CLI

First, let's scaffold an app with Vue CLI. Please make sure you have installed it with typing the following command in your console:



vue --version

If you don't have a version or it's less than 3.x, please run



npm install -g @vue/cli

Now you can create a Vue project from the console! To do so, please run



vue create <<YOUR-PROJECT-NAME>>

and select options you need. I will use the default setup for this project.

Great, now we're ready to add some desktop magic 🧙

Adding NW.js

NW.js official documentation recommends to use one of two builders to package your application:

I chose nwjs-builder-phoenix and I will describe further steps assuming you will use it as well 😅

So, first you need to add it as a dependency to your project:



npm install --save-dev nwjs-builder-phoenix
## OR
yarn add --dev nwjs-builder-phoenix

Now you need to modify your package.json file to provide a correct entry for the packager.

Tip: you can find package.json in the root folder of your application.

Packager entry should be specified under the main property. We're going to run a development environment on the desktop so let's extend our package.json with the following:



"main": "http://localhost:8080"

It's the port where our scaffolded web application is running locally. Usually main is index.html but now we want to have a hot reload on every application change. That's why we're pointing main to a Vue application with hot reload module.

Running an application

Now let's run our web application:



npm run serve
## OR
yarn serve

You can check http://localhost:8080 in your browser to make sure an app is actually running. There should be something like this:

And finally we're ready to start a desktop app:



./node_modules/.bin/run .

This will fetch a specified version of NW.js (by default it's sdk) and run a development environment.

run is a command added by nwjs-builder-phoenix and dot means we're usind the package.json from the root directory.

Now you should have an application running on desktop

Let's automate running dev environment a bit. Close your desktop app and install the NW.js SDK flavor:



npm install --save-dev nw@sdk
## OR
yarn add --dev nw@sdk

Now, add a new task to package.json scripts section:



"scripts": {
  "serve": "vue-cli-service serve",
  "build": "vue-cli-service build",
  "nw-serve": "nw ." /* <--- here is your new npm task */
},

Let's try to run it:



npm run nw-serve
## OR
yarn nw-serve

You should have your app running on desktop again but no downloading step now 🎉

Good news: you can simply open devtools like you do in the browser and use them to debug your application! Just click Window -> Devtools

🕹️ Scaffolding an app

Similarly to Electron, NW.js-powered application is built like a usual web application, so we're going to create a web app, style it with some CSS and let nwjs-builder-phoenix to care about packaging it to desktop application.

NOTE: Same as for Electron app, I didn't install any CSS framework or component library on purpose: I wanted to compare package size without adding any different dependencies. The only library used for all desktop projects is axios.

Open App.vue file and replace its content with the following code:



<template>
  <div id="app">
    <p>Enter the city name to check current weather in it</p>
    <section class="weather-input">
      <input type="text" v-model="query">
      <button :disabled="!query.length">Check</button>
    </section>
  </div>
</template>

<script>
export default {
  data() {
    return {
      query: "",
    };
  }
};
</script>

<style>
#app {
  font-family: "Avenir", Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}

.button {
  color: #000;
}
</style>

Now our application looks this way:

🔗 Making an API call

I used the OpenWeatherMap current weather API. It gives you a lot of different information, you can check an example of JSON response here.

We're going to use axios to make API calls. Obviously, we need to install it:



npm install axios
## OR
yarn add axios

To be able to use axios inside any Vue component we will import it to main.js, set the base URL and then create a property in Vue prototype for it:



//main.js

import axios from 'axios'

axios.defaults.baseURL = 'http://api.openweathermap.org/data/2.5';
Vue.http = Vue.prototype.$http = axios;

Now in the App.vue we will create a bunch of data properties to display different weather data:



// App.vue

data() {
    return {
      query: '',
      error: false,
      city: '',
      country: '',
      weatherDescription: '',
      temp: null,
      tempMin: null,
      tempMax: null,
      humidity: null,
      icon: '',
    };
},

Similarly to Electron, I've added one additional property comparing to Vuido version and it's an icon. API provides a weather icon but we couldn't use it in Vuido app because currently there is no support for displaying images.

Let's also create a method to fetch our data:



methods: {
  showWeather() {
    this.$http
      .get(`/weather?q=${this.query}&units=metric&&appid=${API_KEY}`)
      .then(response => {
        this.city = response.data.name;
        this.country = response.data.sys.country;
        this.weatherDescription = response.data.weather[0].description;
        this.temp = response.data.main.temp;
        this.tempMin = response.data.main.temp_min;
        this.tempMax = response.data.main.temp_max;
        this.humidity = response.data.main.humidity;
        this.icon = `http://openweathermap.org/img/w/${
          response.data.weather[0].icon
        }.png`;
        this.error = false;
      })
      .catch(() => {
        this.error = true;
        this.city = '';
      });
  },
},

Don't forget to create a const API_KEY with your OpenWeather API key!

and add it to the click callback of our button:



<button :disabled="!query.length" @click="showWeather">Check</button>

Now if you enter the text into an input field and click the button, you can observe the API call in the Network tab:

💅 Displaying weather data

Let's add this data to the template:



<template>
  <main id="app">
    <p>Enter the city name to check current weather in it</p>
    <section class="weather-input">
      <input type="text" v-model="query">
      <button :disabled="!query.length" @click="showWeather">Check</button>
    </section>
    <section v-if="error" class="weather-error">
      There is no such city in the database
    </section>
    <section v-if="city.length" class="weather-result">
      <h1>{{city}}, {{country}}</h1>
      <p><em>{{weatherDescription}}</em></p>
      <div class="weather-result__main">
        <img :src="icon" alt="Weather icon">
        <div class="weather-result__temp">
          {{temp}}&deg;C
        </div>
      </div>
      <div class="weather-result__details">
        <p>Min: {{tempMin}}&deg;C</p>
        <p>Max: {{tempMax}}&deg;C</p>
        <p>Humidity: {{humidity}}%</p>
      </div>
    </section>
  </main>
</template>

Our application view:

It still looks too basic, so it's time to add some CSS. Let's replace the whole style section of App.vue with the following code:



<style>
* {
  margin: 0;
  padding: 0;
}
html,
body,
#app {
  height: 100%;
}

#app {
  font-family: Arial, Helvetica, sans-serif;
  font-size: 16px;
  padding: 10px;
  background: rgb(212, 228, 239);
  background: radial-gradient(
    ellipse at center,
    rgba(212, 228, 239, 1) 0%,
    rgba(134, 174, 204, 1) 100%
  );
  filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#d4e4ef', endColorstr='#86aecc',GradientType=1 ); /* IE6-9 fallback on horizontal gradient */
}

.weather-input {
  display: flex;
  align-items: center;
  padding: 20px 0;
}

.weather-result {
  text-align: center;
}

.weather-result__main {
  display: flex;
  align-items: center;
  justify-content: center;
  padding-top: 5px;
  font-size: 1.3rem;
  font-weight: bold;
}

.weather-result__details {
  display: flex;
  align-items: center;
  justify-content: space-around;
  color: dimgray;
}

.weather-error {
  color: red;
  font-weight: bold;
}

input {
  width: 75%;
  outline: none;
  height: 20px;
  font-size: 0.8rem;
}

button {
  display: block;
  width: 25%;
  height: 25px;
  outline: none;
  border-radius: 5px;
  white-space: nowrap;
  margin: 0 10px;
  font-size: 0.8rem;
}
</style>

And finally we have a beautiful fully-functional app:

The last thing to do before packaging it is to reduce a window size. To do so, we need to add a window property to package.json:



"window": {
  "width": 600,
  "height": 400
},

📦 Packaging

To package a NW.js app with nwjs-builder-phoenix you need to run a build command with a proper set of parameters. I am going to build it on for Mac to compare its size with Electron and Vuido apps.

First, we need to specify a NW.js version to be used on build process. We can do it via build property of package.json



"build": {
  "nwVersion": "0.35.3"
},

And then let's run a build command in the terminal:



./node_modules/.bin/build --tasks mac-x64 .

Again, dot in the command means we're using a package.json file located in the root project folder

Let's check a package size... 233 MB 😱!

Wow, that's a lot. It's even bigger than Electron application!

🌟 Conclusions

Pros:

really easy to start
can be customized via CSS styling
good docs
has a support for protected binaries

Cons

very big package size
not-so-good naming (maybe it's just me but Electron/Vuido is way more memorable than NW.js)
small ecosystem.

💖 Special thanks

I want to thank Jared Wilcurt who helped me with answers on my NW.js questions. Jared is an author for NW.js Vue devtools to debug a Vue application right on the desktop.

UPDATE: If you wonder how to reduce the size of the package significantly, here is an article by Jared Wilcurt.

How to build a Vue CLI plugin

Natalia Tepluhina — Mon, 15 Oct 2018 12:09:38 +0000

This article is cross-posted from ITNEXT

If you're using Vue framework, you probably already know what Vue CLI is. It's a full system for rapid Vue.js development, providing project scaffolding and prototyping.

An important part of the CLI are cli-plugins. They can modify the internal webpack configuration and inject commands to the vue-cli-service. A great example is a @vue/cli-plugin-typescript: when you invoke it, it adds a tsconfig.json to your project and changes App.vue to have types, so you don't need to do it manually.

Plugins are very useful and there are a lot of them today for different cases - GraphQL + Apollo support, Electron builder, adding UI libraries such as Vuetify or ElementUI... But what if you want to have a plugin for some specific library and it doesn't exist? Well, it was my case 😅... and I decided to build it myself.

In this article we will be building a vue-cli-plugin-rx. It allows us to add a vue-rx library to our project and get RxJS support in our Vue application.

🎛️ Vue-cli plugin structure

First of all, what is a CLI plugin? It's just an npm package with a certain structure. Regarding docs, it must have a service plugin as its main export and can have additional features such as a generator and a prompts file.

For now it's absolutely unclear what is a service plugin or generator, but no worries - it will be explained later!

Of course, like any npm package, CLI plugin must have a package.json in its root folder and it would be nice to have a README.md with some description.

So, let's start with the following structure:

.
├── README.md
├── index.js      # service plugin
└── package.json

Now let's have a look at optional part. A generator can inject additional dependencies or fields into package.json and add files to the project. Do we need it? Definitely, we want to add rxjs and vue-rx as our dependencies! More to say, we want to create some example component if user wants to add it during plugin installation. So, we need to add either generator.js or generator/index.js. I prefer the second way. Now the structure looks like this:

.
├── README.md
├── index.js      # service plugin
├── generator
│   └── index.js  # generator
└── package.json

One more thing to add is a prompts file: I wanted my plugin to ask if user wants to have an example component or not. We will need a prompts.js file in root folder to have this behavior. So, a structure for now looks the following way:

├── README.md
├── index.js      # service plugin
├── generator
│   └── index.js  # generator
├── prompts.js    # prompts file
└── package.json

⚙️ Service plugin

A service plugin should export a function which receives two arguments: a PluginAPI instance and an object containing project local options. It can extend/modify the internal webpack config for different environments and inject additional commands to vue-cli-service. Let's think about it for a minute: do we want to change webpack config somehow or create an additional npm task? The answer is NO, we want just to add some dependencies and example component if necessary. So all we need to change in index.js is:

module.exports = (api, opts) => {}

If your plugin requires changing webpack config, please read this section in official Vue CLI docs.

🛠️ Adding dependencies via generator

As mentioned above, CLI plugin generator helps us to add dependencies and to change project files. So, first step we need is to make our plugin adding two dependencies: rxjs and vue-rx:

module.exports = (api, options, rootOptions) => {
  api.extendPackage({
    dependencies: {
      'rxjs': '^6.3.3',
      'vue-rx': '^6.0.1',
    },
  });
}

A generator should export a function which receives three arguments: a GeneratorAPI instance, generator options and - if user creates a project using certain preset - the entire preset will be passed as a third argument.

api.extendPackage method extends the package.json of the project. Nested fields are deep-merged unless you pass { merge: false } as a parameter. In our case we're adding two dependencies to dependencies section.

Now we need to change a main.js file. In order to make RxJS work inside Vue components, we need to import a VueRx and call Vue.use(VueRx)

First, let's create a string we want to add to the main file:

let rxLines = `\nimport VueRx from 'vue-rx';\n\nVue.use(VueRx);`;

Now we're going to use api.onCreateComplete hook. It is called when the files have been written to disk.

  api.onCreateComplete(() => {
    // inject to main.js
    const fs = require('fs');
    const ext = api.hasPlugin('typescript') ? 'ts' : 'js';
    const mainPath = api.resolve(`./src/main.${ext}`);
};

Here we're looking for the main file: if it's a TypeScript project, it will be a main.ts, otherwise it will be a main.js file. fs here is a File System.

Now let's change file content

  api.onCreateComplete(() => {
    // inject to main.js
    const fs = require('fs');
    const ext = api.hasPlugin('typescript') ? 'ts' : 'js';
    const mainPath = api.resolve(`./src/main.${ext}`);

    // get content
    let contentMain = fs.readFileSync(mainPath, { encoding: 'utf-8' });
    const lines = contentMain.split(/\r?\n/g).reverse();

    // inject import
    const lastImportIndex = lines.findIndex(line => line.match(/^import/));
    lines[lastImportIndex] += rxLines;

    // modify app
    contentMain = lines.reverse().join('\n');
    fs.writeFileSync(mainPath, contentMain, { encoding: 'utf-8' });
  });
};

What is happening here? We're reading the content of the main file, breaking it into lines and reverting their order. Then, we search the first line with an import statement (it will be the last one after the second reverting) and add our rxLines there. After this, we reverse the array of lines and save the file.

💻 Testing cli-plugin locally

Let's add some information about our plugin in package.json and try to install it locally to test. The most important information usually is a plugin name and a version (these fields will be required when publishing the plugin to npm), but feel free to add more info! The full list of package.json fields could be found here. Below is my file:

{
  "name": "vue-cli-plugin-rx",
  "version": "0.1.5",
  "description": "Vue-cli 3 plugin for adding RxJS support to project using vue-rx",
  "main": "index.js",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/NataliaTepluhina/vue-cli-plugin-rx.git"
  },
  "keywords": [
    "vue",
    "vue-cli",
    "rxjs",
    "vue-rx"
  ],
  "author": "Natalia Tepluhina <my@mail.com>",
  "license": "MIT",
  "homepage": "https://github.com/NataliaTepluhina/vue-cli-plugin-rx#readme"
}

Now it's time to check how our plugin works! To do so, let's create a simple vue-cli-powered project:

vue create test-app

Go to the project folder and install our newly created plugin:

cd test-app
npm install --save-dev file:/full/path/to/your/plugin

After plugin is installed, you need to invoke it:

vue invoke vue-cli-plugin-rx

Now, if you try to check the main.js file, you can see it's changed:

import Vue from 'vue'
import App from './App.vue'
import VueRx from 'vue-rx';

Vue.use(VueRx);

Also, you can find your plugin in devDependencies section of your test app package.json.

📂 Creating a new component with generator

Great, a plugin works! It's time to extend its functionality a bit and make it able to create an example component. Generator API uses a render method for this purpose.

First, let's create this example component. It should be a .vue file located in project src/components folder. Create a template folder inside the generator one and then mimic this whole structure inside of it:

Your example component should be...well, just a Vue single-file component! I won't dive into RxJS explanations in this article, but I created a simple RxJS-powered click counter with 2 buttons:

Its source code could be found here.

Now we need to instruct our plugin to render this component on invoke. To do so, let's add this code to generator/index.js:

api.render('./template', {
  ...options,
});

This will render the whole template folder. Now, when plugin is invoked, a new RxExample.vue will be added to src/components folder.

I decided not to overwrite an App.vue and let users add an example component on their own. However, you can replace parts of existing files, see examples in docs

⌨️ Handling user choices with prompts

What if user doesn't want to have an example component? Wouldn't it be wise to let users decide on this during plugin installation process? That's why prompts exist!

Previously we've created prompts.js file in the plugin root folder. This file should contain an array of questions: every question is an object with certain set of fields such as name, message, choices, type etc.

Name is important: we will use it later in generator to create a condition for rendering an example component!

Prompt can have different types but the most widely used in CLI are checkbox and confirm. We will use the latter to create a question with yes/no answer.

So, let's add our prompt code to prompts.js!

module.exports = [
  {
    name: `addExample`,
    type: 'confirm',
    message: 'Add example component to components folder?',
    default: false,
  },
];

We have an addExample prompt which will ask user if he/she would like to add a component to components folder. Default answer is No.

Let's go back to the generator file and do some fixes. Replace out api.render call with

if (options.addExample) {
    api.render('./template', {
      ...options,
    });
}

We're checking if addExample has a positive answer and, if so, the component will be rendered.

Don't forget to reinstall and test you plugin after each change!

📦 Make it public!

Important note: before publishing your plugin please check if its name matches the pattern vue-cli-plugin-<YOUR-PLUGIN-NAME>. This allows your plugin to be discoverable by @vue/cli-service and installable via vue add.

I also wanted my plugin to have a nice appearance in Vue CLI UI, so I added a description, tags and repository name to package.json and created a logo. Logo picture should be named logo.png and placed in the plugin root folder. As a result, my plugin looks this way in UI plugins list:

Now we're ready to publish. You need to be registered an npmjs.com and obviously you should have npm installed.

To publish a plugin, go to the plugin root folder and type npm publish in the terminal. Voilà, you've just published an npm package!

At this moment you should be able to install a plugin with vue add command. Try it!

Of course, the plugin described in this article is very basic, but I hope my instructions will help someone to start with cli-plugins development.

What kind of CLI plugin you're missing? Please share you ideas in comments 🤗

Building a Desktop App with Vue: Electron

Natalia Tepluhina — Tue, 11 Sep 2018 12:07:34 +0000

In my previous article I described building a desktop application with Vue framework using Vuido. It's a great library to create a fast and small-sized desktop app with native platform components but it has its own downsides like no CSS styling or images support. Now it's time to try Electron to build a desktop app.

Electron is an open source library developed by GitHub for building cross-platform desktop applications with HTML, CSS, and JavaScript. Electron accomplishes this by combining Chromium and Node.js into a single runtime and apps can be packaged for Mac, Windows, and Linux

To have a quick start I've used an electron-vue boilerplate by Greg Holguin. It provides a developer with vue-cli scaffolding, common Vue plugins, packager, testing, devtools, and other features.

💻 What are we going to build

We will build the same application as in the previous article: an app to check the weather in the city of user's choice built on top of OpenWeatherMap API.

If you want just to check the final Electron-powered app code, it's here.

🛠️ Installation

An electron-vue boilerplate is built as a template for VueCLI 2.x and includes options to customize an application. So you need to install it globally:

npm install -g vue-cli

If you prefer to use the latest version of VueCLI, you need to install a global bridge too:

npm install -g @vue/cli @vue/cli-init

and then initialize your project:

vue init simulatedgreg/electron-vue weather-app

This will start an installation project with a couple of choices you need to make during it.

The cool thing is if you need some commonly used plugins and libraries such as axios, you can pick them up during the installation process.

Almost all choices were clear but there was one concern 🤔:

I decided to google it and found this useful thread on StackOverflow. According to it, electron-builder seemed to be a better choice for me, so I went with it.

After the project is set up, you need to go to the application folder and run npm install or yarn install and we are ready to go.

🔦 Understanding an application structure

Right after installation is finished you can see two folders inside the src one: main and renderer. First one is required for Electon main process

According to electron-vue docs, in Electron the process that runs package.json’s main script is called the main process. The script that runs in the main process can display a GUI by creating web pages.

There are two files in the main folder: index.js and index.dev.js. First one is your application's main file, the file in which electron boots with. It is also used as webpack's entry file for production. All main process work should start here.

index.dev.jsis used specifically and only for development as it installs electron-debug & vue-devtools. You don't need to touch it while developing an application.

renderer folder is required for renderer process.

Since Electron uses Chromium for displaying web pages, Chromium’s multi-process architecture is also used. Each web page in Electron runs in its own process, which is called the renderer process.

As you may notice, it's a 'normal' Vue application structure with assets and components folders, main.js and App.vue files. Here is the structure of the latter:

<template>
  <div id="app">
    <landing-page></landing-page>
  </div>
</template>

<script>
  import LandingPage from '@/components/LandingPage'

  export default {
    name: 'weather-app',
    components: {
      LandingPage
    }
  }
</script>

<style>
  /* CSS */
</style>

And if you try to run dev task you will have this result:

So there is a landing-page component and also devtools opened. Now we can start to change it!

🕹️ Scaffolding an app

Unlike Vuido, an Electron-powered app is built with HTML-tags, not native components. So we will make a structure similar to the usual web app and style it with CSS.

NOTE: I didn't install any CSS framework or component library on purpose: I wanted to compare package size without adding any different dependencies. The only library used in both projects is axios.

The first step was to get rid of landing-page component. Then I added a simple input field and a button:

<div id="app">
    <p>Enter the city name to check current weather in it</p>
    <section class="weather-input">
      <input type="text" v-model="query">
      <button :disabled="!query.length">Check</button>
    </section>
</div>

Now our application looks this way:

We have a query property in data to handle the user input and we will make an API call with this query as a parameter.

🔗 Making an API call

I used the OpenWeatherMap current weather API. It gives you a lot of different information, you can check an example of JSON response here.

We already included axios to our application during the installation process. Let's have a look at src/renderer/main.js:

import Vue from 'vue';
import axios from 'axios';
import App from './App';

if (!process.env.IS_WEB) Vue.use(require('vue-electron'));
Vue.http = Vue.prototype.$http = axios;
Vue.config.productionTip = false;

So we can use axios methods as this.$http in the component instance! The only thing we will add here is a base URL for our API calls:

axios.defaults.baseURL = 'http://api.openweathermap.org/data/2.5';

Now in the App.vue we will create a bunch of data properties to display different weather data:

data() {
    return {
      query: '',
      error: false,
      city: '',
      country: '',
      weatherDescription: '',
      temp: null,
      tempMin: null,
      tempMax: null,
      humidity: null,
      icon: '',
    };
},

I've added one additional property comparing to Vuido version and it's an icon. API provides a weather icon but we couldn't use it in Vuido app because currently there is no support for displaying images.

Let's also create a method to fetch our data:

methods: {
  showWeather() {
    this.$http
      .get(`/weather?q=${this.query}&units=metric&&appid=${API_KEY}`)
      .then(response => {
        this.city = response.data.name;
        this.country = response.data.sys.country;
        this.weatherDescription = response.data.weather[0].description;
        this.temp = response.data.main.temp;
        this.tempMin = response.data.main.temp_min;
        this.tempMax = response.data.main.temp_max;
        this.humidity = response.data.main.humidity;
        this.icon = `http://openweathermap.org/img/w/${
          response.data.weather[0].icon
        }.png`;
        this.error = false;
      })
      .catch(() => {
        this.error = true;
        this.city = '';
      });
  },
},

and add it to the click callback of our button:

<button :disabled="!query.length" @click="showWeather">Check</button>

Now if you enter the text into an input field and click the button, you can observe the API call in the Network tab:

💅 Displaying weather data

Let's add this data to the template:

<template>
  <main id="app">
    <p>Enter the city name to check current weather in it</p>
    <section class="weather-input">
      <input type="text" v-model="query">
      <button :disabled="!query.length" @click="showWeather">Check</button>
    </section>
    <section v-if="error" class="weather-error">
      There is no such city in the database
    </section>
    <section v-if="city.length" class="weather-result">
      <h1>{{city}}, {{country}}</h1>
      <p><em>{{weatherDescription}}</em></p>
      <div class="weather-result__main">
        <img :src="icon" alt="Weather icon">
        <div class="weather-result__temp">
          {{temp}}&deg;C
        </div>
      </div>
      <div class="weather-result__details">
        <p>Min: {{tempMin}}&deg;C</p>
        <p>Max: {{tempMax}}&deg;C</p>
        <p>Humidity: {{humidity}}%</p>
      </div>
    </section>
  </main>
</template>

Our application view:

Awesome, we can see an actual weather! But it looks like it's 1999... Let's add some CSS magic to it (actually, a lot of CSS magic)!

<style lang="scss">
* {
  margin: 0;
  padding: 0;
}
html,
body,
#app {
  height: 100%;
}

#app {
  font-family: Arial, Helvetica, sans-serif;
  font-size: 16px;
  padding: 10px;
  background: rgb(212, 228, 239);
  background: -moz-radial-gradient(
    center,
    ellipse cover,
    rgba(212, 228, 239, 1) 0%,
    rgba(134, 174, 204, 1) 100%
  );
  background: -webkit-radial-gradient(
    center,
    ellipse cover,
    rgba(212, 228, 239, 1) 0%,
    rgba(134, 174, 204, 1) 100%
  );
  background: radial-gradient(
    ellipse at center,
    rgba(212, 228, 239, 1) 0%,
    rgba(134, 174, 204, 1) 100%
  );
  filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#d4e4ef', endColorstr='#86aecc',GradientType=1 ); /* IE6-9 fallback on horizontal gradient */
}

.weather-input {
  display: flex;
  align-items: center;
  padding: 20px 0;
}

.weather-result {
  text-align: center;
  &__main {
    display: flex;
    align-items: center;
    justify-content: center;
    padding-top: 5px;
    font-size: 1.3rem;
    font-weight: bold;
  }
  &__details {
    display: flex;
    align-items: center;
    justify-content: space-around;
    color: dimgray;
  }
}

.weather-error {
  color: red;
  font-weight: bold;
}

input {
  width: 75%;
  outline: none;
  height: 20px;
  font-size: 0.8rem;
}

button {
  display: block;
  width: 25%;
  height: 25px;
  outline: none;
  border-radius: 5px;
  white-space: nowrap;
  margin: 0 10px;
  font-size: 0.8rem;
}
</style>

And finally we have nice fully-functional app:

The last thing to do before packaging it is to reduce a window size. If we check a src/main/index.js file, we can find settings for it:

mainWindow = new BrowserWindow({
    height: 563,
    useContentSize: true,
    width: 1000
})

Let's change width to be 450 and height to be 250

📦 Packaging

Great news: you can build your app as a web application! If you run a build:web task, you will find a build web app in a dist folder.

But let's go back to our desktop app and run build task. As a result, you will have a folder named after your platform inside the build folder (for me it's mac) and an application file inside of it. And its size it... wow, 133 Mb!

It's a lot for such a little application! Also, if you try to run it, you can notice it's starting a bit slower than a Vuido-powered app.

Final look:

🌟 Conclusions

Pros:

easy to start
good docs
provides web app build
can be customized via CSS styling

Cons

really big package size
slower than an application built with native GUI components

Electron-vue is a good option if your application needs a unique appearance and you care less about package size and performance.

Update

If your web application is built with Vue CLI 3, you can simply make it a desktop app with Vue CLI Plugin Electron Builder. You just need to run the following command in your project root folder:

vue add electron-builder

After it's done you will have two additional npm tasks: serve:electron and build:electron to work with a desktop app.

Building a Desktop App with Vue: Vuido

Natalia Tepluhina — Mon, 03 Sep 2018 11:51:02 +0000

Update: Building Vue desktop app with Electron

I love Vue. It's a great framework allowing you to build awesome web applications. But the real magic is you're not limited to web only. You can simply make native mobile applications using Weex or NativeScript-Vue; but also there is a way to build desktop apps. You can choose Electron or Vuido library for this purpose. In this article I will describe Vuido approach an in the next one I will try to build the same app with Electron.

Vuido is a framework for creating native desktop applications based on Vue.js created by Michał Męciński. Applications using Vuido can run on Windows, OS X and Linux, using native GUI components, and don't require Electron.

Under the hood, Vuido uses the libui library which provides native GUI components for each desktop platform, and the libui-node bindings for Node.js.

💻 What are we going to build

As an example, we will make a simple application checking current weather in the city of your choice. We will use OpenWeatherMap API to fetch actual data.

If you want just to check the final code, it's here.

🛠️ Installation

As stated in Vuido docs, there are some prerequisites to start developing a desktop app. They are different for different platforms:

💡Windows

windows-build-tools
Visual C++ Redistributable Package for Visual Studio 2013

💡Linux

build-essential
GTK+ 3

💡OSX

Xcode

I was using OSX for development and I've had Xcode installed at this moment.

Also, you will need vue-cli installed (if you're using Vue CLI 3, you will also need @vue/cli-init).

To create a new project, run the following command:

vue init mimecorg/vuido-webpack-template my-project

Right after an installation is finished, you can find the MainWindow.vue component inside your src folder with the following code:

<template>
  <Window title="some-app" width="400" height="100" margined v-on:close="exit">
    <Box>
      <Text>Welcome to your Vuido application!</Text>
    </Box>
  </Window>
</template>

<script>
export default {
  methods: {
    exit() {
      this.$exit();
    },
  },
};
</script>

If you run build and then start tasks, you will see a window with the very basic desktop app:

Now we are ready to build something more entertaining 😅

💅 Scaffolding an app

The first thing you need to know about Vuido is it's using native components. So there are neither our familiar HTML tags nor CSS styling - only a set of native GUI components compatible with different desktop platforms. An ppplication built with Vuido will have the native look and feel on each platform.

This may be considered as both advantage and disadvantage - you can't build an application with a very custom appearance but it will be more lightweight and will work faster than the one built with Electron.

The full list of built-in components could be found in this section of Vuido docs.

My initial idea was to build an application to show the weather in the city of the user's choice, so I could test simple user interaction and API calls. First thing I needed was actually an input field with a button. Also, I changed a window size to 400x150px:

<Window title="Weather" width="400" height="150" margined v-on:close="exit">
    <Box padded>
        <Box horizontal padded>
        <TextInput stretchy></TextInput>
        <Button>Search</Button>
    </Box>
    </Box>
</Window>

To align an input field with a button horizontally and add a padding between them, we need a <Box> container with horizontal and padded attributes. Box is similar to HTML div, it works as a wrapper to contain and align components.

TextInput is an input field, it's stretchy attribute means it will stretch to fill available space.

Now our app looks this way:

Let's add a query property to component data and set it as v-model for the input field. Also, we need to disable a button when there is no query string and it was tricky for me because I've tried a familiar disabled attribute - but in Vuido you should use enabled one! So now our input box looks like this:

<Box horizontal padded>
    <TextInput v-model="query" stretchy></TextInput>
    <Button :enabled="!!query">Search</Button>
</Box>

🔗 Making an API call

Now the idea is to fetch current weather conditions with a given query string as a city.

To get weather data I used the OpenWeatherMap API. It provides a lot of different stuff but we need only Current weather data chapter. You can check an example of JSON response here.

So, in order to start fetching data, we need to add an axios library:

npm install --save axios

Then import it and set a base URL and OpenWeatherMap API key variable:

import axios from 'axios';
axios.defaults.baseURL = 'http://api.openweathermap.org/data/2.5'
const apiKey = process.env.API_KEY;

After this, let's add a bunch of new properties for weather data and a method to fetch it from API:

export default {
  data() {
    return {
      query: '',
      error: false,
      city: '',
      country: '',
      weatherDescription: '',
      temp: null,
      tempMin: null,
      tempMax: null,
      humidity: null,
    };
  },
  methods: {
    exit() {
      this.$exit();
    },
    showWeather() {
      axios
        .get(
          `/weather?q=${this.query}&units=metric&&appid=${apiKey}`,
        )
        .then(response => {
          this.city = response.data.name;
          this.country = response.data.sys.country;
          this.weatherDescription = response.data.weather[0].description;
          this.temp = response.data.main.temp;
          this.tempMin = response.data.main.temp_min;
          this.tempMax = response.data.main.temp_max;
          this.humidity = response.data.main.humidity;
          this.error = false;
        })
        .catch(() => {
          this.error = true;
          this.city = '';
        });
    },
  },
};

Now it's time to attach a new method to the button and change the template to show all given data or an error if query doesn't match any of existing cities

<Window title="Weather in your city" width="400" height="150" margined v-on:close="exit">
    <Box padded>
    <Box horizontal padded>
        <TextInput stretchy v-model="query"/>
        <Button :enabled="!!query" @click="showWeather">Search</Button>
    </Box>
    <Separator horizontal/>
    <Group margined>
        <Box padded>
          <Text v-if="error">There is no such city in the database</Text>
          <Box v-if="!!city">
            <Box padded horizontal>
              <Text stretchy>{{city}}, {{country}}</Text>
              <Text>{{temp}}&deg;C</Text>
            </Box>
            <Text>{{weatherDescription}}</Text>
            <Separator horizontal/>
            <Box padded horizontal>
              <Text stretchy>Min: {{tempMin}}&deg;C</Text>
              <Text stretchy>Max: {{tempMax}}&deg;C</Text>
              <Text stretchy>Humidity: {{humidity}}%</Text>
            </Box>
          </Box>
        </Box>
    </Group>
    </Box>
</Window>

As you can see, the first box is the input container we've created in the previous chapter. Below there is a Separator - a horizontal line to visually separate widgets. Next is Group - it's a container which provides a border with a caption around its content.

Inside the Group you can see a combination of components you've already seen: Text for simple text content, Box as a container and Separator. Now applicaton looks the following way:

📦 Packaging

In my opinion, the best and the easiest way to package Vuido-powered application is the one recommended by the library author. He recommends using his own libraries LaunchUI and LaunchUI Packager to package and distribute applications to end users.

I've installed LaunchUI Packager globally:

npm install --global launchui-packager

Then I ran a following command in the app root folder:

launchui-packager weather-app 1.0 dist/main.min.js

In the command above weather-app is the application name, 1.0 is a version and dist/main.min.js is a path to bundle file.

After this a folder with my application! Package size is 39Mb which is a bit more than promised by author (~20Mb mentioned in docs) but not so much anyway.

If you try to run it you might notice it's starting really fast (0.1s or so).

🌟 Conclusions

Pros:

easy to build
provides small package size compared to Electron-powered apps
well-documented

Cons

no cool styles 😕
still not released (current version is 0.2.0)

Vuido looks like a good option if you need a fast small application with a basic appearance. It has a clear documentation and probably the list of built-it components will grow in the future.

Testing vue-apollo Components with Jest

Natalia Tepluhina — Fri, 17 Aug 2018 12:01:00 +0000

Recently I've been working on some tests for Vue single-file components with vue-apollo queries and mutations. Unfortunately, there are not so many guides on the topic so I decided to share my experience. This article doesn't pretend to be a best-practice but I hope it will help people to start testing GraphQL + Apollo in Vue with Jest.

vue-apollo is a library that integrates Apollo in Vue components with declarative queries

Project overview

I added vue-apollo tests to my simple demo application. It contains an App.vue component with one query for fetching the list of Vue core team members and two mutations: one to create a new member entry and another to delete it. Full GraphQL schema could be found in apollo-server/schema.graphql file.

For component unit testing I used Jest and vue-test-utils.

If you have a look at tests folder, you might notice project already had a basic test for App.vue:

import { createLocalVue, shallowMount } from '@vue/test-utils';
import Vuetify from 'vuetify';
import App from '../../src/App';

describe('App', () => {
  let localVue;
  beforeEach(() => {
    localVue = createLocalVue();
    localVue.use(Vuetify, {});
  });

  test('is a Vue instance', () => {
    const wrapper = shallowMount(App, { localVue });
    expect(wrapper.isVueInstance()).toBeTruthy();
  });
});

This project uses Vuetify, so I added it to localVue to prevent warnings about its custom components. Also, there is a simple check if component is a Vue instance. Now it's time to write some vue-apollo-related tests!

Simple tests

At first, when I was searching for any pointers about how to test vue-apollo queries and mutations, I found this comment by vue-apollo author, Guillaume Chau

Comment for #244

Akryum commented on Mar 23, 2018

I recommend to use vue test-utils if you don't already. Then you have to mock everything related to apollo. If you have queries, just use wrapper.setData. If you have mutations, mock them like this:

const mutate = jest.fn()
const wrapper = mount(MyComponent, {
  mocks: {
    $apollo: {
      mutate,
    },
  },
})
// ...
expect(mutate).toBeCalled()

View on GitHub

So I decided to start testing my component using this advice. Let's create a new test case:

  test('displayed heroes correctly with query data', () => {
    const wrapper = shallowMount(App, { localVue });
  });

After this we need to save a correct response to the wrapper data and check if component renders correctly. To get the response structure we can check a query in project schema:

type VueHero {
    id: ID!
    name: String!
    image: String
    github: String
    twitter: String
}

type Query {
  allHeroes: [VueHero]
}

So allHeroes query shoud return an array of VueHero entries and every single field type is specified. Now it's easy to mock the data inside our wrapper:

wrapper.setData({
  allHeroes: [
    {
      id: 'some-id',
      name: 'Evan You',
      image:
        'https://pbs.twimg.com/profile_images/888432310504370176/mhoGA4uj_400x400.jpg',
      twitter: 'youyuxi',
      github: 'yyx990803',
    },
  ],
});

Awesome, our data is mocked! Now it's time to check if it's rendered correctly. For this purpose I used a Jest snapshot feature: a test expects that component will match the given snapshot. Final test case looks like this:

test('displayed heroes correctly with query data', () => {
    const wrapper = shallowMount(App, { localVue });
    wrapper.setData({
      allHeroes: [
        {
          id: 'some-id',
          name: 'Evan You',
          image:
            'https://pbs.twimg.com/profile_images/888432310504370176/mhoGA4uj_400x400.jpg',
          twitter: 'youyuxi',
          github: 'yyx990803',
        },
      ],
    });
    expect(wrapper.element).toMatchSnapshot();
});

If you run it a couple of times, you will see test passes (nothing surprising here, with a given set of data component renders in the same way every time). This is how the heroes grid in the snapshot looks like at this moment:

<v-layout-stub
        class="hero-cards-layout"
        tag="div"
        wrap=""
      >
        <v-flex-stub
          class="hero-cards"
          md3=""
          tag="div"
          xs12=""
        >
          <v-card-stub
            height="100%"
            tag="div"
          >
            <v-card-media-stub
              height="250px"
              src="https://pbs.twimg.com/profile_images/888432310504370176/mhoGA4uj_400x400.jpg"
            />

            <v-card-title-stub
              class="hero-title"
              primarytitle="true"
            >
              <div>
                <h3
                  class="title"
                >
                  Evan You
                </h3>

                <div
                  class="hero-icons"
                >
                  <a
                    href="https://github.com/yyx990803"
                    target="_blank"
                  >
                    <i
                      class="fab fa-github"
                    />
                  </a>

                  <a
                    href="https://twitter.com/youyuxi"
                    target="_blank"
                  >
                    <i
                      class="fab fa-twitter"
                    />
                  </a>
                </div>
              </div>
            </v-card-title-stub>

            <v-card-actions-stub>
              <v-spacer-stub />

              <v-btn-stub
                activeclass="v-btn--active"
                icon="true"
                ripple="true"
                tag="button"
                type="button"
              >
                <v-icon-stub>
                  delete
                </v-icon-stub>
              </v-btn-stub>
            </v-card-actions-stub>
          </v-card-stub>
        </v-flex-stub>
      </v-layout-stub>

Let's move to mutation tests now. We're going to check if $apollo method mutate is called in our Vue component method addHero(). There is no data needed to perform this check, because we don't expect any kind of a result here: we just want to be sure a mutation was called. In a new test case we mock $apollo as shown in the comment above, call addHero() method and then expect mutate to be called:

  test('called Apollo mutation in addHero() method', () => {
    const mutate = jest.fn();
    const wrapper = mount(App, {
      localVue,
      mocks: {
        $apollo: {
          mutate,
        },
      },
    });
    wrapper.vm.addHero();
    expect(mutate).toBeCalled();
  });

Now we have simple tests coverage for GraphQL query and mutation.

Mocking GraphQL schema

I really wanted to see how my queries are called in a more 'real-life' environment and I've found the solution in this chapter of Apollo docs. The idea is to mock the actual GraphQL schema and call queries and mutations against it.

This part is a bit more complicated and requires more work but from my point of view this way of testing GraphQL calls give you more precise results. Let's start with creating a new mockSchema.js file in tests folder and importing required method from graphql-tools:

import { makeExecutableSchema } from 'graphql-tools';

To create a schema I simply copied a part with all types from apollo-server/schema.graphql:

const schema = `
  type VueHero {
    id: ID!
    name: String!
    image: String
    github: String
    twitter: String
  }

  input HeroInput {
    name: String!
    image: String
    github: String
    twitter: String
  }


  type Query {
    allHeroes: [VueHero]
  }

  type Mutation {
    addHero(hero: HeroInput!): VueHero!
    deleteHero(name: String!): Boolean
  } 
`;

Now we can create executable schema with imported makeExecutableSchema method. We should pass our schema as typeDefs parameter:

export default makeExecutableSchema({
  typeDefs: schema,
});

One more thing we need for testing is adding mock functions to schema. Let's do it in our App.spec.js file:

import { addMockFunctionsToSchema } from 'graphql-tools';
import schema from '../mockSchema';
...
describe('App', () => {
  let localVue;
  beforeEach(() => {
    localVue = createLocalVue();
    localVue.use(Vuetify, {});
    addMockFunctionsToSchema({
      schema,
    });
  });
  ...
}):

Now we're ready to test the query.

Testing query with a mocked schema

Let's create a new test case and add a query string to it (you can always check your schema if you're not sure what format should query have):

const query = `
  query {
    allHeroes {
      id
      name
      twitter
      github
      image
    }
  }
`;

Please notice we don't use gql template literal tag from Apollo here because we will do GraphQL call without including Apollo. We also will set component data after resolving a promise:

graphql(schema, query).then(result => {
  wrapper.setData(result.data);
  expect(wrapper.element).toMatchSnapshot();
});

At this moment you can delete a previous snapshot and comment/delete a previous query test case

The whole test case should look like this:

test('called allHeroes query with mocked schema', () => {
    const query = `
      query {
        allHeroes {
          id
          name
          twitter
          github
          image
        }
      }
    `;
    const wrapper = shallowMount(App, { localVue });
    graphql(schema, query).then(result => {
      wrapper.setData(result.data);
      expect(wrapper.element).toMatchSnapshot();
    });
});

After running it if you check the snapshot file, you might realise all response fields are equal to 'Hello World'. Why does it happen?

The issue is without mocking GraphQL resolvers we will always have a generic response (number of entries will always be 2, all integers will be negative and all strings are Hello World). But this generic test is good enough to check response structure.

GraphQL resolvers are a set of application specific functions that interact with your underlying datastores according to the query and mutation operations described in your schema.

If you check apollo-server/resolvers file, you can see that real resolvers are working with data in our database. But test environment doesn't know anything about database, so we need to mock resolvers as well.

Realistic mocking

Let's create mockResolvers.js file in our test folder. First thing to add there is a resolver for allHeroes query:

export default {
  Query: {
    allHeroes: () => [
      {
        id: '-pBE1JAyz',
        name: 'Evan You',
        image:
          'https://pbs.twimg.com/profile_images/888432310504370176/mhoGA4uj_400x400.jpg',
        twitter: 'youyuxi',
        github: 'yyx990803',
      },
    ],
  },
};

Now this query will always return the same array with a single entry. Let's add resolvers to the schema in mockSchema.js:

import resolvers from './mockResolvers';
...
export default makeExecutableSchema({
  typeDefs: schema,
  resolvers,
});

We also need to change addMockFunctionsToSchema call in out test suite: in order to keep resolvers not overwritten with mock data, we need to set preserveResolvers property to true

addMockFunctionsToSchema({
  schema,
  preserveResolvers: true,
});

Delete previous snapshot and try to run a test. Now we can see a realistic data provided with our resolver in a new snapshot.

We can also add other expectation, because right now we know an exact response structure. Say, we can check if allHeroes array length is equal 1.

Final version of this test case:

test('called allHeroes query with mocked schema', () => {
    const query = `
      query {
        allHeroes {
          id
          name
          twitter
          github
          image
        }
      }
    `;
    const wrapper = shallowMount(App, { localVue });
    graphql(schema, query).then(result => {
      wrapper.setData(result.data);
      expect(result.data.allHeroes.length).toEqual(1);
      expect(wrapper.element).toMatchSnapshot();
    });
});

Testing mutation with mocked schema

Now let's test a mutation with our mocked schema too. In the new test case create a mutation string constant:

test('called Apollo mutation in addHero() method', () => {
    const mutation = `
        mutation {
          addHero(hero: {
            name: "TestName",
            twitter: "TestTwitter",
            github: "TestGithub",
            image: "TestImage",
          }) {
            id
            name
            twitter
            github
            image
          }
        }
    `;
});

We will pass custom strings as parameters and await for the response. To define this response, let's add a mutation resolver to our mockResolvers file:

Mutation: {
    addHero: (_, { hero }) => ({
      id: 1,
      name: hero.name,
      image: hero.image || '',
      twitter: hero.twitter || '',
      github: hero.github || '',
    }),
},

So our addHero mutation will return exactly the same hero we passed as its parameter with an id equal to 1.

Now we can add a GraphQL query to the test case:

graphql(schema, mutation).then(result => {
  expect(result.data.addHero).toBeDefined();
  expect(result.data.addHero.name).toEqual('TestName');
});

We didn't check changes to the Vue component instance here but feel free to modify component data with a response.

Full mutation test case:

test('called addHero mutation with mocked schema', () => {
    const mutation = `
        mutation {
          addHero(hero: {
            name: "TestName",
            twitter: "TestTwitter",
            github: "TestGithub",
            image: "TestImage",
          }) {
            id
            name
            twitter
            github
            image
          }
        }
    `;
    graphql(schema, mutation).then(result => {
      expect(result.data.addHero).toBeDefined();
      expect(result.data.addHero.name).toEqual('TestName');
    });
});

Now our test suit has a basic test for mutate call and two 'advanced' tests with a mocked GraphQL schema.

If you want to check the project version with all tests, there is a testing branch here.

DEV Community: Natalia Tepluhina

Six tips to improve your code review skills

Test the changes locally

Ask questions, don't make statements

Don't hesitate to praise

Label your comments

Separate blocking from non-blocking

Make an extra step

Testing Vue+Apollo: 2020 edition

What we're going to test

Setting up a unit test with createComponent factory

Mocking Apollo client with handlers

Testing successful query response

Changing a handler to test an empty list

Testing query error

Testing a mutation to add a new hero

Three awesome tools for GraphQL developer experience

GraphQL explorer/playground

Linting and autocomplete with IDE plugin

VS Code

WebStorm

Apollo DevTools

Wrapping REST API calls with Apollo Client: 'do-it-yourself' approach

What we're going to build?

Step 1: extend GraphQL schema

Step 2: Writing a query and a resolver

Conclusion

Vue Apollo v4: the first look

An example we're going to use

Installation

Adding a query

Working with mutations

Conclusions

Data visualizations with Vue and D3: counting stars (part 2)

What are we going to build?

Scaling star radius

Styling the app

Creating a custom scale for star color

What's next?

Apollo state management in Vue application

🤔 Why do we need Apollo local state management?

🏗️ What are we going to build

🔧 Add Apollo to Vue application

🗃️ Initializing an Apollo cache

📃 Creating a local schema

🔦 Query local data

✏️ Change local data

Checking/unchecking a todo-item

Deleting an item

Adding new item

Useful links

Building a Desktop App with Vue: NW.js

⚛️ Differences from Electron

💻 What are we going to build

🛠️ Installation

Creating an app with Vue CLI

Adding NW.js

Running an application

🕹️ Scaffolding an app

🔗 Making an API call

💅 Displaying weather data

📦 Packaging

🌟 Conclusions

💖 Special thanks

How to build a Vue CLI plugin

🎛️ Vue-cli plugin structure

⚙️ Service plugin

🛠️ Adding dependencies via generator

💻 Testing cli-plugin locally

📂 Creating a new component with generator

⌨️ Handling user choices with prompts

📦 Make it public!

Building a Desktop App with Vue: Electron

💻 What are we going to build

🛠️ Installation

🔦 Understanding an application structure

🕹️ Scaffolding an app

🔗 Making an API call

💅 Displaying weather data

📦 Packaging

Setting up a unit test with `createComponent` factory