Menu

Upgrade to Adaptive.js v2.0

Upgrade your project to Adaptive.js v2.0 to increase performance and to get new features.

When you migrate your Adaptive.js version, you gain access to:

A major version upgrade (for example, from 1.4.0 to 2.0.0) introduces changes that break your code. This major upgrade requires you to also change your project code.

Follow the steps after the Overview to upgrade your project to Adaptive.js 2.0.


Overview of New and Renamed Files in Adaptive.js 2.0

Adaptive.js v1.X Adaptive.js v2.0
loader.js
adaptation/main.js adaptation.js
assets/js/ui/main.js ui.js

Loader.js

The loader.js file is the Adaptive.js bootloader. It allows you to pre-load assets before your transformation runs or render out a splash loading screen quicker than was previously possible. This file should be kept as small as possible to keep page loads snappy.

Adaptation.js

The adaptation.js file is the same as the adaptation/main.js file in Adaptive.js 1.x. This is where where you store all the configuration for your adaptation.

Ui.js

The ui.js file is the same as the assets/js/ui/main.js file in Adaptive.js 1.x. All setup and configuration of UI components and plugins go here.


1. Generate a new Adaptive.js 2.0 Project

Adaptive.js 2.0 comes with a new file structure.

1.To make it easier to port your project to the new structure, generate a new project.

2. Move the files from your current project to the new project structure with the following instructions.


2. Update your Generator

1. Open a new Terminal (Mac) or Command Prompt (Windows).

2. To change to your project new directory, enter the following command on the command line:

cd path/to/new/project/directory

3. To update your Adaptive.js generator, enter the following command on the command line:

npm install -g generator-adaptivejs

3. Set up your Project Directory


4. Generate your Adaptive.js 2.0 Project

1. Ensure that you are in the parent directory that is one level up from your root project folder on the command line.

2. To generate a new project scaffold in the Adaptive.js 2.0 structure, enter the following command on the command line:

yo adaptivejs --slug your-project-directory-name

Ensure that you replace the your-project-directory-name argument with the name of your project directory.

jQuery or Zepto? The Yeoman generator prompts you to use either Zepto or jQuery. Pick the same library that you used before migrating. To ensure 100% compatibility in the upgrade, simply copy the files from your old project vendor directory into the app/vendor folder in your new project.


5. Ensure Project Name and File Locations

Directory Name Different from Project Name Have you changed the name of the directory so that it is different from the name key in your project's package.json file? Fix this name field in your newly generated project's package.json file so that the directory and the project name are the same.

The biggest difference in the Adaptive.js 2.0 directory structure is that every asset which is run through a build step lives inside the app directory. This includes your UI JavaScript, Views, Templates, SCSS stylesheets, etc. Place all the static files in the static folder.

The project structure that you generated in the previous step is a suggestion for your the arrangement of your project files. At Mobify, we generally build our projects around a component-based model. The changes to the file structure reflect that.

Keep these items exactly as they are:

1. Place all of the files that you want to build into the app folder. 2. Place all static assets in the static folder. 3. Ensure that your adaptation.js, ui.js, and loader.js files are inside the app directory.

Keep the File Names Do not rename the adaptation.js, ui.js, and loader.js files. The tasks that compile your project look for each of these files by name.


6. Move your Project into the New Folder Structure

old_project/adaptation

1. In your new project directory, overwrite the newly-generated app/adaptation.js file with your original project old_project/adaptation/main.js file. 2. In an editor app, from the new project app folder, open the adaptation.js file. 3. In the adaptation.js file, change path of the router require to global/router. Your completed file looks like the following code snippet of the adaptation.js file listing:

require([
    'global/router',
    'adaptivejs/adaptive',
    'adaptivejs/view',
    'adaptivejs/utils',
    'adaptivejs/defaults',
    'utils/selector-extensions'
],

4. In your new project directory, overwrite the app/global/router.js Router file with the old_project/adaptation/router.js Router file from your original project. 5. In an editor app, from the new project app/config directory, open the adaptation.js file. 6. In the editor, from the old_project/adaptation director, open the config.js file. 7. Copy the paths from the from the config.js file to the config/adaptation.js file.

Notice that in Adaptive.js 2.0 that the bower_components path is now contained inside the app folder. This gives the paths a tighter structure.

8. Move all of the files from the adaptation folder from your original project into the new project app directory.

old_project/assets

1. Move static assets like fonts and images from your old_project/assets original project folder into the static folder in the new project structure.

Follow these instructions if your styles are written in SCSS.

2. Move the style files from your old project into the app folder in the new project. 3. In the new project, from the app folder, delete the stylesheet.scss file. 4. In the new project, delete the app/global/styles folder. 5. In an editor app, from the tasks/config in your new project directory, open the sass.js file. 6. Change both the cwd keys in the files blocks so that they look like this sass.js code snippet:

module.exports = function(grunt) {
    return {
        prod: {
            options: {
                bundleExec: true,
                style: 'compressed',
                sourcemap: 'none',
                loadPath: [
                    'app/',
                    'app/bower_components/'
                ],
                require: [
                    'compass/import-once/activate'
                ]
            },
            files: [{
                expand: true,
                cwd: 'app/styles/',
                src: [
                    '**/*.scss',
                    '!bower_components/**/*.scss'
                ],
                dest: 'build/css',
                ext: '.css',
            }],
        },
        dev: {
            options: {
                bundleExec: true,
                style: 'expanded',
                sourcemap: 'auto',
                loadPath: [
                    'app/',
                    'app/bower_components/'
                ],
                require: [
                    'compass/import-once/activate'
                ]
            },
            files: [{
                expand: true,
                cwd: 'app/styles/',
                src: [
                    '**/*.scss',
                    '!bower_components/**/*.scss'
                ],
                dest: 'build/css',
                ext: '.css',
            }],
        }
    };
};

7. If you have any files or folders other than the ui folder in your old_project/assets/js original project directory, move them into the static/js folder in the new project structure. 8. In the new project directory, in the app folder, overwrite the ui.js file with the old_project/assets/js/ui/main.js file from your original project. 9. In an editor app, from the old_project/assets/js/ui folder in the original project, open the config.js file. 10. In an editor app, from the app/config folder in the new project structure, open the ui.js file. 11. Cope the necessary paths from the config.js file into the ui.js file.

Update all Paths to bower_components Directory Paths to the bower_components folder in the older directory structure had many ../ strings to navigate up to the root directory. Now, since the bower_components components are installed with the app directory structure, the old path references are now incorrect.

12. In the ui.js file, update all references to bower_components to the new structure. Follow this sample path for the Pikabu plugin:

bower_components/pikabu/src/pikabu.js

13. Copy all other files from the old_project/assets/js/ui/ folder in the original project into the app directory in the new project structure.

External Package Managers (Bower and Bundler)

1. In the new project root directory, replace the Gemfile and Gemfile.lock files with the ones from your old_project original project folder (if you have them). 2. In an editor app, from your new project root directory, open the bower.json file. 3. In the editor, from the original project root directory, open the bower.json file. 4. Update the paths in the new bower.json file with the paths from the bower.json file from your old project. 5. Open a new Terminal (Mac) or Command Prompt (Windows). 6. To change to your project new directory, enter the following command on the command line:

cd path/to/new/project/directory

7. To update your Bower dependencies, enter the following command on the command line:

bower install

Custom Tasks and Gruntfile

Follow these instructions if you have any custom tasks in your original project.

1. In an editor app, from your new project root directory, open the Gruntfile.js file. 2. In an editor app, from your original project root directory, open the Gruntfile.js task runner filer. 3. Move the custom tasks from the original Gruntfile.js file into the new Gruntfile.js file.

If any of these tasks required modules from NPM, add the packages back to your package.json file.

4. To update the NPM dependencies, in your new project root directory, enter the following command on the command line:

npm install

Test your Upgraded Project

Once you complete the previous steps, test your project.

grunt preview

ESLint Errors If the ESLint eslint:dev task reports any errors, append the "--force" flag to the end of the grunt preview command to continue past them. These errors do not prevent your site preview.

Ensure that there are no build errors.

Edit in GitHub