IMA.js skeleton application
To install the IMA.js application development stack, start by cloning this git repository:
git clone https://github.com/seznam/IMA.js-skeleton.git
Switch to the cloned
IMA.js-skeleton directory and run the following commands
to set-up your application:
npm install npm run app:hello npm run dev
These commands install the dependencies locally, prepare the basic demo
application and start the development server. Go ahead and open
http://localhost:3001/ in your browser!
You also may want to install the
gulp tool globally in
order to access all the available tools, examples and commands (you may need to
sudo on a UNIX-like system):
npm install -g gulp
Check installation and hello world video tutorials on
You may also try other local demos by running either of the following commands:
npm run app:feed npm run app:todos
If you want deploy your IMA.js application to production, the installation is similar to the dev enviroment.
To install the IMA.js application, start by cloning your application git repository on your production server:
git clone https://github.com/seznam/IMA.js-skeleton.git // use your application's repository
Switch to the cloned directory and run the following commands to set-up your application - same as in the development mode:
npm install npm run build
Now your server is ready for running the built IMA.js application.
You can run your application using the following command:
npm run start
Your application is running at
(unless configured otherwise) now!
Building for SPA deployment
It is also possible to deploy your IMA.js application as an SPA (single-page application). To do that, run the following command to build your application:
npm run build:spa
Your built application will be in the
build directory, ready for deployment
to an HTTP server.
We have prepared a complex tutorial for you: Your first IMA.js application. This tutorial covers the basics of creating isomorphic web applications using IMA.js, but you will encounter some more advanced concepts in there as well.
IMA.js consists of several components:
- React for UI, which you should learn before you dive head-first into IMA.js
- Express.js as the web server, but you don't need to know express to use IMA.js
- ...and various little utilities you don't need to concern yourself with :)
The IMA.js is divided into the core library, which you'll use to build your application, and the application server build on top of Express.js, that brings your application to life.
Structure of your IMA.js application
You application resides in the
app directory, so let's take a closer look at
the contents of the demo "hello world" application:
assets- files that are preprocessed and copied to our built application, usually as static resources
less- Less CSS files defining common rules, overrides, macros, mixins and the basic UI layout.
static- any files that do not need preprocessing (3rd party JS files, images, ...)
base- base classes providing default implementation of some of the abstract APIs. We can use these to make our lives a little easier in some cases.
component- our React components for use in the view. We'll cover those in the tutorial.
config- configuration files. You don't need to worry about those right now, but feel free to study them.
locale- localization files, providing localized phrases used in our application. This directory contains sub-directories for specific languages, each named after the ISO 639-1 two-character language code for the given language.
page- controllers, main views and page-specific Less CSS files for pages in our application. Usage of these is configured via routing.
error- the page shown when the application encounters an error that prevents it from working properly.
home- the index (home) page.
notFound- the page shown when the user navigates to a page that is not defined in our application.
locale directories are expected by the IMA.js
application stack, the remaining directories can be renamed or moved and you
are free to organize your files in any way you like (but you will have to
update the configuration accordingly).
There are several configuration files in your IMA.js application:
gulpConfig.jscontains configuration for the gulp tasks we use to build and run your application.
karma.conf.jsis used to configure the karma test runner.
app/environment.jsconfigures the server-side environment. Notice that the
testenvironment configuration automatically inherits values from the
prodenvironment (except for the
$Languagewhich has to be configured individually).
app/main.jsis the bootstrap of your application. You don't need to concern yourself with this file usually.
app/config/services.jsspecifies how the fatal application errors should be handled at the client side.
app/config/routes.jsconfigures your router, mapping routes to the controllers and views in your application.
app/config/settings.jsconfigures your application and IMA.js services. Notice how, again, the
testenvironment configuration automatically inherits values from the
- and finally, the
app/config/bind.jsconfigures the object container (think of it as a more powerful dependency injector) with support for constants, managing dependencies of your classes and setting the default implementors of interfaces. You can also create aliases for your classes and interfaces using the object container.
All of these files are necessary and must remain in their locations.
There are several directories we have not mentioned so far:
doccontains the generated documentation of IMA.js and your application. The IMA.js relies on YUI doc for documentation building, and augments the YUI doc with support for several jsdoc-specific annotations.
buildcontains your built application. All files are generated, so any changes you make will be automatically discarded once the application is rebuilt.
node_modules/ima-examplescontains the example IMA.js applications for you to study. You can install any of the examples into your project skeleton by running the
gulp app:(name of the example)command. (It is recommended to run
gulp app:cleanfirst to remove any extra files that might be left by the previously installed application).
servercontains the application server. You will most likely won't have to concern yourself with these files, but feel free to study them or modify them if the need arises.
There are several plugins authored by us that can use (and there may be more of them provided by the community):
- Abstract REST API client - the base plugin providing an abstract implementation of a high-level REST API client.
- Abstract web analytics - the base plugin used & extended by other web analytics plugins.
- Google analytic - web analytics plugin that provides integration with the Google Analytics service.
- HAL+JSON REST API client - a high-level REST API client for HAL+JSON REST APIs.
- Managed Abstract Component -
an extension of the
ima/page/AbstractComponentclass that automatically handled binding of event listeners in the elements returned from the
render()method, manually bound event, interval and timeout listeners, to the component's instance (
this). The component also handles automatic unbinding the listeners and canceling pending timeouts and interval when the component is about to be unmounted (see the React component's
componentWillUnmount()method). This plugin is currently experimental and may not work.
- UI Atoms - elementary web page building elements (hence the name "atoms") for building AMP HTML-ready websites with AMP-style lazy-loading of external resources (images, videos, iframes) for regular HTML version of the site.