DEV Community: Carlos Rodrigues

How to test your library for vue 2 and vue-next

Carlos Rodrigues — Wed, 22 Jul 2020 14:26:18 +0000

With vue-next now a release candidate, many library authors have begun porting their vue 2.x library to vue-next.

There are solutions to enable library compatibility with both Vue 2 and Vue 3. For example, vue-demi allows your library to access the appropriate Vue APIs for the version of vue you have installed installed.

However, there are no current solutions for testing your library against both Vue 2 and Vue 3. This is particularly relevant to me as I maintain vue-composable, a library that has both vue 2.x and vue-next support -- and of course, a suite of automated tests.

Preface

First, an important note: this may not be the most correct or the cleanest approach, but it works and has been tested for quite a few months now.

Probably the best place for this to be used is with the composition-api libraries, because the render has breaking changes, that make this method to be a bit messy.

Introduction

I will cover how to setup a project to work with both vue-next and vue 2 + composition-api. It will target vue-next primarily.

I've tried to keep the example as simple as possible, but some prior knowledge is required:

Vue 3
Vue 2.x + @vue/composition-api
Jest

Project

For the project we will create a composable called useApi

import { ref } from "vue";

export function useApi(factory, handleResponse) {
  const isLoading = ref(false);
  const result = ref(null);
  const error = ref(null);
  const execute = async (...args) => {
    const request = factory(...args);

    isLoading.value = true;
    error.value = null;
    try {
      const response = await fetch(request);
      const valueResponse = await handleResponse(response);

      result.value = valueResponse;
      return valueResponse;
    } catch (e) {
      error.value = e;
      result.value = null;
    } finally {
      isLoading.value = false;
    }
  };

  return {
    isLoading,
    result,
    error,
    execute,
  };
}

As written, this would work with vue-next, but not with vue 2.x.

api.js

So we will need to replace the import { ref } from 'vue' with our own import { ref } from './api'.

// api.js [Vue3]
export { ref } from "vue";

In api.js we will expose all the required Vue APIs needed in the project. All vue dependencies should come from this file. (Otherwise we might end up importing different vue versions and breaking reactivity.)

vue 2 + composition-api

Now we will create a new file called api.2.js

export { ref } from "@vue/composition-api";

We can hot-swap in this file when testing.

Test

Now we just need to create a test __tests__/index.spec.js

import { useApi } from "../index";
import { mockFetch } from "./utils";

describe("useApi", () => {
  it("should work", async () => {
    mockFetch({ name: "Luke Skywalker" });
    const userList = useApi(
      (page) => ({ url: `https://swapi.dev/api/people/${page}` }),
      (r) => r.json()
    );
    await userList.execute(1);

    expect(userList.result.value.name).toBe("Luke Skywalker");
  });
});

Now we could just change the import { ref } from './api' to import { ref } from './api.2'. Only one problem remains: @vue/composition-api needs to be initialised by running Vue.use(VueCompositionApi).

Jest config

So we will add a jest.config.js and create a file (__tests__/setupTest.js) where we can initialise the Vue 2 composition-api plugin.

Because we currently only need the setupTest.js when using vue 2.x we will pass an environment variable named VUE with the version number. If is 2 we will include

// jest.config.js
const isVue2 = process.env.VUE === "2";

module.exports = {
  setupFiles: isVue2 ? ["<rootDir>/__tests__/setupTest.2.js"] : undefined,
  testMatch: ["<rootDir>/__tests__/**/*spec.[jt]s?(x)"],
};

For the setupTest.2.js we will need to import vue, but we can't just import it normally because we already have vue@next in our package dependencies. So we will need to add vue 2.x with a different name (vue2).

// package.json
  "dependencies": {
    "@vue/composition-api": "^1.0.0-beta.6",
    "vue": "^3.0.0-rc.4",
    "vue2": "npm:vue@^2.6.1"
  }

Now we can import it in setupTest.2.js

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

Vue.use(VueCompositionApi);

Great. However, we're not done yet. If you pass env.VUE === '2', it may initialize the composition api, but the tests would still run using vue-next 🤔

To make sure we run with the correct API we will mock the api.js module with jest.

// setupTest.2.js

// mock for the correct api
jest.mock("./../api", () => jest.requireActual("./../api.2"));

//... importing vue and use CompositionApi

Now if you pass the VUE=2 environemnt variable it will use @vue/composition-api instead of vue-next.

Scripts

You can have yarn test test both versions by doing

// package.json
  "scripts": {
    "test": "yarn test:vue2 && yarn test:vue3",
    "test:vue2": "VUE=2 yarn jest",
    "test:vue3": "yarn jest"
  },

Multi-platform

You can install cross-env and run both

yarn add cross-env -D

//package.json
  "scripts": {
    "test": "yarn test:vue2 && yarn test:vue3",
    "test:vue2": "cross-env VUE=2 yarn jest",
    "test:vue3": "yarn jest"
  },

Pitfalls

If there's file that imports vue or @vue/composition-api, most likely it will compile but it will not work properly, reactivity will not work, etc. Please make sure you only import from api.js.

Typescript types might be different and have some nuances, if using with typescript please export the types from api.ts, if the types don't exist in v2 or v3, export custom types using api.ts or api.2.ts.

Conclusion

Hopefully this will give you a good start to begin experimenting with both libraries within the same code base. There are a few missing apis in @vue/composition-api, and this approach will allow you to implement some of them (example)

Please check up-to-date repo for the all the code and working project.

Big thanks to @danielroe for reviewing this article, so many awesome changes 🎉

Thoughts on building composition-api functions

Carlos Rodrigues — Tue, 25 Feb 2020 12:43:35 +0000

After vue-next became publicly available, inspired by LinusBorg composition-api-demos, I started building a utility composition-api library vue-composable with a goal of learning and understanding the composition-api.

Typescript

Because of my background on C#, I'm really keen to have intellisense, I always went the extra mile to get types on my vue apps, even when it required heavily modify and adapt vuex typings or other caveats of using typescript with vue.

I must admit using typescript within setup() has been really pleasant, it feels like plain typescript (similar to react in a way), without sleight of hands.

composition-api

IMHO composition-api shines when composing multiple functions to get the desire result.

Let's try implementing SWAPI composable:

import { usePagination, useFetch, wrap } from "vue-composable";
import { ref, watch, isRef } from "@vue/composition-api";

type SWAPI_RESOURCE =
  | "planets"
  | "spaceships"
  | "vehicles"
  | "people"
  | "films"
  | "Species";

interface SWAPIList<T = any> {
  count: number;
  next: string;
  previous: string;
  results: Array<T>;
}

function useSWAPI<T = any>(r: SWAPI_RESOURCE) {
  const resource = wrap(r);
  const ENDPOINT = `https://swapi.co/api/`;

  const items = ref<T[]>([]);
  const { json, loading, exec, status } = useFetch<SWAPIList>();

  const pagination = usePagination({
    currentPage: 1,
    pageSize: 10, // default size
    total: 0
  });

  watch(
    json,
    json => {
      if (json) {
        pagination.total.value = json.count;
        items.value = json.results;
      } else {
        pagination.total.value = 0;
        items.value = [];
      }
    },
    {
      lazy: true
    }
  );

  watch([pagination.currentPage, resource], () => {
    exec(`${ENDPOINT}${resource.value}/?page=` + pagination.currentPage.value);
  });

  return {
    ...pagination,
    exec,
    items,
    loading,
    status
  };
}

// usage
setup(){
  return useSWAPI('people');
}

We can improve the return types from the request based on SWAPI_RESOURCE.

In this example we use two composables usePagination and useFetch

usePagination allows manipulating pages based on items, it's generic enough to allow to adapt any pagination implementation.
useFetch just a fetch wrapper

Re-usability

You might be thinking "Isn't that what mixins are used for?" and you be correct, but using mixins you need to be careful with naming collisions, handling variable names, methods, etc.

Using composition-api becomes trivial to expose multiple api calls on the setup:

setup(){
  const people = useSWAPI('people');
  const planets = useSWAPI('planets');

  return {
    people,
    planets
  }
}

`Ref` vs `Reactive`

I recommend having a look on this Thought on Vue 3 Composition API - reactive() considered harmful

When building vue-composable 98% of the cases I will return a object with ref, the reason being it allows you to deconstruct your object and vue will unwrap it on the render.

One common practice I use on my composables is accept both Ref<T>|T, this allows the flow in the setup() to be much cleaner (without .value everywhere) and also allowing the composable to watch changes on the argument.

Template unwrapping

One of the arguments of using ref is the auto-unwrapping on the template(no need to use .value in the render), ~~but the commit refactor: remove implicit reactive() call on renderContext, disables the auto unwrapping of the object (more info), making the usage of ref a bit more verbose~~

export default {
  // before 
  template: `<div> {{ awesomeObject.items }} {{ awesomeObject.selected }} </div>`,
  // after
  template:  `<div> {{ awesomeObject.items.value }} {{ awesomeObject.selected.value }} </div>`,
  // after with auto unwrap
  template:  `<div> {{ autoUnwrap.items }} {{ autoUnwrap.selected }} </div>`,
  setup() {
    const awesomeObject = {
      items: ref([]),
      selected: ref({}),
    };

    return {
      awesomeObject,
      // auto unwrapping, it need to be a ref, cannot return plain object with nested ref
      autoUnwrap: ref(awesomeObject) // or reactive(awesomeObject)
    };
  }
};

This is a breaking change and as far as I know, the @vue/composition-api it not updated yet.

This change makes the usage of ref less appealing, but not sure how in the real world environment what changes it will make.

Not everything needs to be `ref` or `reactive`

This might be a bit controversial, I don't believe your use* should always return ref, when you are returning something you know it will not change, you might be better off not wrapping it on a ref/reactive, eg:

export function useOnline() {
  const supported = "onLine" in navigator;

  // not sure how to test this :/
  if (!supported) {
    online = ref(false);
  }

  if (!online) {
    online = ref(navigator.onLine);
    // ... listen for changes
  }

  return {
    supported,
    online
  };
}

supported won't change, so the usage of a ref is not necessary, I don't think consistency is a good argument in this particular case.

using `reactive(state)` and then return `toRefs()`

I've seen code that uses an reactive state and then return toRefs(state).

I like how clean this is, you just need to understand why you need to return toRefs(state) and that's basically the complexity of this approach.

const state = reactive({
  supported: "onLine" in navigator,
  online: navigator.onLine
})
window.addEventListener("online", () => state.online = true));

return toRefs(state);

Although as a library creator, having to call toRefs will have a theoretically more objects created (just an opinion, I might be wrong, you can prove me wrong), thus more GC work. Asides from that, I think is a pretty neat way to overcome .value 👍

Moving to composition-api

IMO you don't need to port your object-api code to composition-api, I would go as far as don't recommend doing it without a good reason.

object-api only has a few issues when dealing with huge components, you can even make an argument that you should refactor your component better, I would only use composition-api if maintaining your component if getting out-of-hand and composition-api would allow to make the component easier to maintain.

You can use `composition-api` return values on your `object-api`

When using @vue/composition-api plugin, it is built on top of the object-api and when using vue-next the options-api is built using composition-api, making it trivial to share functionality between them.

For example, our useSWAPI example, if you want to use it on your vue component without using setup(), you can use:

export default {
  data(){ 
   return reactive(useSWAPI('people')), 
   // you need to use `reactive` or `ref` to unwrap the object,
   // otherwise you need to use `.value` on the template
  }
}

Final thoughts

I really like the extensibility of the composition-api, I'm looking forward for what the community will build once vue3 is out!

I recommend being open-minded and use the right tool for the job, some components don't required extra complexity or you don't want to migrate your huge project to composition-api, my answer to that is: You don't need it.

You can take advantage of the community libraries for composition-api within your object-api component, to be fair that's one thing I like VueJS it provides an standard way to do things but also giving you the tool to allow modifying and tweak it for your needs.

I know the composition-api was quite controversial in the beginning, let me know if you still think is unnecessary or if you are interested in learning or if you're using it already or what's your thoughts on this matter?

You can check some of my choices and implementations: https://github.com/pikax/vue-composable

EDIT

2020-03-01

Striking the text that mentions the commit to prevent auto-unwrapping on template, because the auto-unwrapping was re-added
refactor(runtime-core): revert setup() result reactive conversion

Dynamic components using VueJS

Carlos Rodrigues — Fri, 26 Jul 2019 08:08:37 +0000

First things first, if you're just starting with VueJS this might be a bit too advanced for you, I would strongly recommend read documentation on VueJS, especially components.

This is my first guide, criticism is welcome :)

Preface

Swapping components based on user inputs or even just have a form being set by a json file, is really usefull method to maintain your sanity level low throughout a big project, since usually there's hundreds components/forms/pages/etc, so making a change in code it might cause a ripple effect and break something elsewhere.

Since VueJS will handle all the dirty details of handling DOM, we can focus on solve business problems.

I will cover loading components by name, creating on-the-fly and async components.

Component "magic"

Doing dynamic wouldn't be as easy without <component v-bind:is="dynComponent"></component> check Dynamic & Async Components for more detailed information.
Basically the components will render a component, async function or by component name.

Loading components by name

Using <component/> will allow you to access global and also local components by name.

codepen

// add some different components globaly
Vue.component("test-comp0", {
  template: `<p>comp0</p>`
});

Vue.component("test-comp1", {
  template: `<p>comp1</p>`
});

Vue.component("test-comp2", {
  template: `<p>comp2</p>`
});

// sample app
new Vue({
  el: "#app",

  components: {
    // add a local component
    // check https://vuejs.org/v2/guide/components-registration.html#Component-Names
    TestComp3: {
      template: `<p>comp3 locally registered component</p>`
    }
    // you can also add some components from other files, using ES6 import or required.
  },

  data() {
    return {
      componentIndex: 0
    };
  },

  computed: {
    componentName() {
      return "test-comp" + this.componentIndex;
    }
  },

  template: `
      <div>
        Component: {{componentIndex}} <button @click="componentIndex=(++componentIndex)%4">change</button>
        <component :is="componentName"></component>
      </div>`
});

Cycle between components is useful, but in the real world you would pass some props to it.
To add props, lets change the component test-comp0 and to the app template.

Vue.component("test-comp0", {
  props: ["name"], // please use the object props for production
  template: `<p>Hello {{name}}</p>`
});

...

// add name prop
<component :is="componentName" name="pikax"></component>

This will pass the prop name to every component. To solve this we can have a computed property and bind it to the component.

// app becomes

new Vue({
  el: "#app",

  components: {
    // add a local component
    // check https://vuejs.org/v2/guide/components-registration.html#Component-Names
    TestComp3: {
      template: `<p>comp3 locally registered component</p>`
    }
    // you can also add some components from other files, using ES6 import or required.
  },

  data() {
    return {
      componentIndex: 0,
      name: "pikax"
    };
  },

  computed: {
    componentName() {
      return "test-comp" + this.componentIndex;
    },
    componentProps() {
      if (this.componentIndex == 0) {
        return {
          name: this.name
        };
      }
      return {}; // return empty object
    }
  },

  template: `
      <div>
        Component: {{componentIndex}} <button @click="componentIndex=(++componentIndex)%4">change</button>
        <component :is="componentName" v-bind="componentProps"></component>
      </div>`
});

On-the-fly components

On-the-fly components are components we just generate as we need using javascript, this shows how powerful the <component></component> is, some use case scenarios would be building widgets.

We can generate and test components based on the user input.

NOTE: be really careful with this, this can allow attackers to attack your application, please ensure the source is trusted!

codepen

new Vue({
  el: "#app",

  data() {
    return {
      componentDefinition: `{ template: "<div>Hello</div>" }`
    };
  },

  computed: {
    myComponent() {
      return eval(`(${this.componentDefinition})`);
    }
  },

  template: `<div>
    <p>Change me</p>
    <textarea v-model="componentDefinition" rows="4" cols="50"></textarea>
    <component v-if="myComponent" :is="myComponent"></component>
</div>
`
});

You can see as you change the textarea, the component should render straight away.
I don't recommend using this, but I think is a good example on how powerful <component></component> is.

Importing async Components

This is for me the most usefull use case of the component. I greatly recommend reading the (official guide)[https://vuejs.org/v2/guide/components-dynamic-async.html#Async-Components]

Vue.component(
  "async-webpack-example",
  // The `import` function returns a Promise.
  () => import("./my-async-component")
);

Real world problem

In my last project we had a problem of we wanted to collect user information, but the fields would change depending on the journey, some journey would required email, others email and phone.

The solution was to get the journey definition in a JSON file, each time the user would start an journey we would load that file and load the fields.
The strategy was to use names to load the component dynamically loading the components by name, but we ended up loading all the possible editors in Vue.Component, this worked... but loading them at the start up means the startup time and app size were much bigger than needed.

Solution

Using a mix of Async, (Dynamic)[https://vuejs.org/v2/guide/components-dynamic-async.html] components and Webpack.

// returning equivalent of webpack : import(name)
const getComponent = async path => {
  /* I recomend having an switch with the possible components you will load, this
   *   will allow you only load specific components.
   */
  if (path == 1) {
    return async () => {
      template: `<p>component 0</p>`;
    };
  } else {
    return async () => {
      template: `<p>${path}</p>`;
    };
  }
};

Vue.component("component-fallback", {
  template: `<div>This is not the component you're looking for</div>`
});

new Vue({
  el: "#app",
  data() {
    return {
      componentIndex: 0,
      component: "component-fallback"
    };
  },

  methods: {
    changeComponent() {
      const newIndex = ++this.componentIndex;
      this.loadComponent(newIndex);
    },

    // returns the component
    loadComponent(name) {
      const componentFunc = getComponent(name)
        .then(x => {
          this.component = x;
        })
        .catch(e => {
          this.component = "component-fallback";
        });
    }
  },

  template: `
        <div>
            Component: {{componentIndex}} <button @click="changeComponent">change</button>
            <component :is="component"></component>
        </div>
        `
});

End

Hope my first article is useful for you, I find fascinating how powerful and flexible <component></component> is.

If you have any more use cases for <component></component> let me know on the comments.

This story was first publish at medium.com

DEV Community: Carlos Rodrigues

How to test your library for vue 2 and vue-next

Preface

Introduction

Project

api.js

vue 2 + composition-api

Test

Jest config

Scripts

Multi-platform

Pitfalls

Conclusion

Thoughts on building composition-api functions

Typescript

composition-api

Re-usability

Ref vs Reactive

Template unwrapping

Not everything needs to be ref or reactive

using reactive(state) and then return toRefs()

Moving to composition-api

You can use composition-api return values on your object-api

Final thoughts

EDIT

Dynamic components using VueJS

Preface

Component "magic"

Loading components by name

On-the-fly components

Importing async Components

Real world problem

Solution

End

`Ref` vs `Reactive`

Not everything needs to be `ref` or `reactive`

using `reactive(state)` and then return `toRefs()`

You can use `composition-api` return values on your `object-api`