Getting Started with IMA.js
IMA.js development stack consists of many different components. Here's a summary of few of the main ones:
- 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.
- Rollup and Gulp with various other tools which are used for building the application.
- 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.
You can find the core and server library along with many other IMA.js related packages in our monorepo at https://github.com/seznam/ima.
To install and run your new IMA.js application, you can use our
create-ima-app npm package.
Start by running following command:
npx create-ima-app my-app
npx create-ima-app my-app
npx create-ima-app my-app
(npx comes with npm 5.2+ and higher, see instructions for older npm versions)
This will bootstrap your new application and install all dependencies. The provided wizard will also let you choose the template you wish to start with.
empty- Hello World [Source code]
feed- TODO List [Source code]
todos- Twitter-Like Feed [Source code]
After the installation succeeds, run following commands to start your application:
npm run dev
pnpm run dev
Before going ahead, now that your application is running, you can either continue reading this documentation, which describes many different parts of IMA.js in detail, take a direct look at the API or start with our tutorial.
Once you've initialized your new IMA.js project, following commands become available to you through npm.
npm run dev- Starts development server in ES6 mode on
http://localhost:3001/. This will also start gulp tasks in watch mode, so any changes you make to the source code are automatically re-builded.
npm run dev --legacy-compat-mode- Starts development server in legacy mode for older browsers, where the code is transpiled to ES5 (IE11).
npm run test- Starts jest test runners.
npm run lint- Runs eslint on your application source files. We've prepared pre-configured .eslintrc.js file which follows our IMA.js coding styles, but feel free to adjust this to your needs.
npm run build- Builds your application. For more information (see Production use).
npm run build:spa- Builds SPA version of your application.
npm run start- Starts IMA.js server.
Why should I use
Developing IMA.js application is fairly easy, but the initial setup process can be quite tiresome. This tool aims to streamline this process, save your time and provide you with buildable application with opinionated defaults that can be easily customized to your needs.
npx create-ima-app my-app command will create following directory structure:
│ ├── assets
│ │ ├── less
│ │ └── static
│ ├── build.js
│ ├── component
│ │ └── document
│ ├── config
│ │ ├── bind.js
│ │ ├── routes.js
│ │ ├── services.js
│ │ └── settings.js
│ ├── environment.js
│ ├── main.js
│ └── page
│ ├── AbstractPageController.js
│ ├── error
│ ├── home
│ └── notFound
So let's take a closer look at the contents of the application:
app- main application folder where all the source code is located.
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, ...).
html- this folder contains two main files:
spa.html- this is a template for SPA applications.
error.html- an error page showed in production.
component- our React components for use in the view. Components are covered in part 3 of our tutorial.
environment.js- configuration files. For more information see Configuration page.
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.
config 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).
If you want to deploy your IMA.js application to production, the installation is similar to the dev environment. To install the IMA.js application, start by cloning your application git repository on your production server:
git clone [your-application-git-repository]
Switch to the cloned directory and run the following commands to set-up your application - same as in the development mode - and build it:
npm run build
pnpm run build
Now after building your IMA.js application your server is ready to run it. You can start your application using the following command:
npm run start
yarn run start
pnpm run start
Your application is now running at
(unless configured otherwise).
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
pnpm run build:spa
Your built application will be in the
build directory, ready to deploy
to a HTTP server.