Migration from Framework7 v5

In this article we will walk through most of the breaking changes to check what needs to be done to migrate your app from Framework7 v5 to Framework7 v6.

Framework7 Core

First of all, let's check what has been changed in core version.

Package

Core version has new package structure, and you may need to tweak your imports for lite and bundle versions:

  • framework7/framework7.esm.js is now framework7
  • framework7/framework7.esm.bundle.js is now framework7/bundle
  • framework7/framework7-lite.esm.js is now framework7/lite
  • framework7/framework7-lite.esm.bundle.js is now framework7/lite-bundle

So if you have something like this in v5:

import Framework7 from 'framework7/framework7-lite.esm.bundle.js'

it should be changed to:

import Framework7 from 'framework7/lite-bundle'

Dom7

Framework7 v6 uses new Dom7 v3. It has breaking changes for all "iteration" methods like .each() and .map(). Specifically, order of arguments has been swapped to match native JavaScript array iterators:

// in v5 (Dom7 v2)
$('p').each((index, el) => {
  // ...
})

// in v6 (Dom7 v3) - arguments are swapped, element is now always the first argument
$('p').each((el, index) => {
  // ...
})

Template7

Template7 template library has been completely removed from Framework7. If your app still needs it, just install it manually:

npm i template7
import Template7 from 'template7';

Template7.compile('...');

Request

Request library's import has been renamed from Request to request. Also now it uses Promises for all methods. Check updated Request documentation.

// import renamed
import { request } from 'framework7/lite';

// not it always uses Promises
request.get('some-url').then((res) => {
  console.log(res.data);
});

Device & Support

Device & Support imports are also changed. Now only getters functions are available for imports.

In v5 we had:

import { Device, Support } from 'framework7';

if (Device.android) {
  console.log('it is Android');
}

if (Support.touch) {
  console.log('touch is supported');
}

In v6 we should use different approach:

import { getDevice, getSupport } from 'framework7';

const device = getDevice();
const support = getSupport();

if (device.android) {
  console.log('it is Android');
}

if (support.touch) {
  console.log('touch is supported');
}

Utils

Utils import has been renamed from Utils to utils:

// in v5
import { Utils } from 'framework7';

// in v6
import { utils } from 'framework7';

View/Router

Route's beforeEnter, beforeLeave, redirect and async methods now receive a single object with following props:

  • to
  • from
  • resolve
  • reject
  • direction (new in v6 - can be forward or backward)
  • router (new in v6 - current router instance)
  • app (new in v6 - f7 app instance)

Check updated Routes documentation for more details and examples.

Framework7 Vue

Vue.js 3

Framework7 Vue v6 compatible only with new Vue.js v3. So first of all you will also need to migrate your app to Vue 3. You can check official Vue.js migration guide.

App Component

Main <f7-app> component now receives all Framework7 parameters as separate props.

<!-- in v5 -->
<f7-app :params="{ id: 'app-id', name: 'app-name' }"> ... </f7-app>

<!-- in v6 -->
<f7-app id="app-id" name="app-name"> ... </f7-app>

App data & methods

App data and methods parameters for storing "global" app state are completely removed.

Now Framework7 comes with new Store library for managing app state. Check new Store documentation and how to use in Framework7 Vue.

View/Router

push-state parameters renamed to browser-history:

<!-- in v5 -->
<View push-state push-state-separator=""> ... </View>

<!-- in v6 -->
<View browser-history browser-history-separator=""> ... </View>

Vue Component Extensions

Framework7 Vue v6 rewritten with Vue functional components, and all Vue component prototype extensions have been removed:

  • this.$$
  • this.$f7
  • this.$f7ready
  • this.$f7route
  • this.$f7router
  • this.$utils
  • this.$device
  • this.$theme
  • this.$request

Now, Framework7 instance, f7ready and theme can be directly imported from framework7-vue package:

import { f7, f7ready, theme } from 'framework7-vue';

f7ready(() => {
  if (theme.ios) {
    f7.dialog.alert('It is iOS theme');
  }
});

f7route and f7router are available in router component props:

<template>
  <f7-page>
    ...
  </f7-page>
</template>

<script>
  export default {
    props: {
      f7route: Object,
      f7router: Object,
    },
    setup(props) {
      const { f7route, f7router } = props;

      console.log(f7route.url);

      const goBack = () => {
        f7router.back();
      }

      //...
    }
  }
</script>

utils, device and request can be imported directly from framework7:

import { utils, getDevice, request } from 'framework7';

// ...

Modals & Panel

All modals components (Popup, Popover, LoginScreen, Actions, Sheet) and Panel now don't have .open() and .close() methods. Their state should be controlled via boolean opened prop.

Swiper

Framework7 v6 uses all new Swiper v6 with its official Vue components which has a bit different API, usage and some new features. For the full new API documentation and more examples check out the official Swiper for Vue documentation.

Skeleton Elements

Skeleton Elements now also integrated as a standalone library. For the full API documentation and more examples check out the official Skeleton Elements for Vue documentation.