Overview

Introduction

Monaca Localkit is a tool to support local development environment for Monaca apps. You can use it with various development tools including editors, source code management system, task runner and so on. Monaca Localkit allows you to develop offline with a faster synchronization with Monaca debugger.

Monaca Localkit can accelerate your app development process because it provides the following functions:

• Create and import Cordova project: You can create a new project based on templates provided by Monaca. Moreover, you can import either a Monaca project from Monaca Cloud IDE or an existing Cordova project.

• Live reload of the project: By pairing with Monaca Debugger, you can run your project instantly on your device. All changes made to the source code of the project will be updated immediately after those changes are saved.

• Integrate with Chrome DevTools: By connecting your device (running Monaca Debugger) to the host PC (running Monaca Localkit) via USB cable, you can debug your app using Chrome DevTools. With Chrome DevTools, you can set breakpoints and implement JavaScript debugging and app inspection.

• Remote build: Monaca Localkit allows you to build your app for various platforms with support from Monaca server.

You are required to have a valid plan in order to use Monaca Localkit. Otherwise, Monaca Localkit will run in an evaluation mode for 30 days after the first login. Please refer to Monaca Subscription Plans for more details of each Monaca plan.

Please note that Monaca Backend as well as Push Notification are currently not available in the Monaca Localkit.

Installation and setup

Before getting started, you need to install the Monaca Localkit on your computer and Monaca Debugger on your device.

1. Download the latest version of Monaca Localkit here. Please refer to GitHub release page for change logs.

2. Install Monaca Debugger as described in Debugger Installation.

Installing the Localkit under Windows environment requires Git.

Usage

Starting Monaca Localkit

1. Open Monaca Localkit and sign in using your Monaca account.

2. After a successful login, the Monaca Localkit dashboard will open.

Creating a new project

You can create a new project based on templates provided by Monaca.

1. From the Monaca Localkit dashboard, click the➕button. Then, click Create.

2. Fill in the necessary information:

• Project Name: create a name to represent your new project which will be shown in the project list.

• Working Directory: specify a directory where you want to keep your project files.

• Select Category: choose a template category for your new project.

• Select Template: choose a template for your new project. Use the Preview button to see how each template looks like.

3. If the project is created successfully, it will be shown in the project list.

Importing a project

There are 3 types of projects you can import to the Monaca Localkit:

1. From Cloud IDE: projects you have in your Monaca Cloud IDE.

2. From Local Cordova Project: Cordova projects you have on your PC. There are some limitations when importing Cordova projects such as:

   • App icons and splash images may not be imported. They can be configured on theBuild Config screen.

   • The scripts in the hooks directory are ignored.

   • Platform specific codes including Cordova are not imported. Monaca will use its own Cordova and surrounded libraries.

3. From Zip File: the zip file of a valid project.

To import a project to the Monaca Localkit, please do as follows:

1. From the Monaca Localkit dashboard, click the➕button on the top right corner of the left panel. Then, click Import and choose how you want to import the Monaca project.

• If you choose the From Cloud IDE option, fill in the necessary information:

  • Select Project: select a project from the list of all projects you have in Monaca Cloud IDE.

  • Working Directory: specify a directory where you want to keep your project files.

• If you choose the From Local Cordova Project option, fill in the necessary information:

  • Working Directory: specify a directory where you want to keep your project files.

  • Project Name: create a name to represent your new project which will be shown in the project list.

• If you choose the From Zip File option, fill in the necessary information:

  • Zip File: browse the zip file of your project.

  • Project Name: create a name to represent your new project which will be shown in the project list.

  • Working Directory: specify a directory where you want to keep your project files.

2. After that, the new project will be shown in the project list.

Adding an editor program for local projects

Monaca Localkit provides an Open in feature which is used to open your local project files in different ways such as:

• Finder/File Explorer: This will reveal the selected project's folder

  in Finder (for Mac), File Browser (for Linux), or File Explorer (for Windows).

• Terminal/Command Prompt: This will open the selected project's

  folder in Terminal (for Mac/Linux) or Command Prompt for (Windows).

• Other editor programs: You can also add any preferred editors to

  open your local project files from Monaca Localkit.

To add an editor program to Monaca Localkit, please do as follows:

1. In Monaca Localkit, select a project.

2. Click the Open in... button and select Open with....

3. Then, Add Application dialog will open. Fill in the necessary information related to the editor program:

• Application Path: browse the editor execution file (.app file for Mac or .exe file for Windows).

• Application Name: name the selected editor program. It will be shown in the list of programs when you click Open in....

• Command-line Arguments: applicable arguments for the selected editor program. Currently, one command line parameter is available: %d (Project File Path).

4. Click OK. Now, the new editor program should appear in the Open in list as shown below:

Transpile process management

Some of the modern frameworks have created their own languages in order to interact with their products (like JSX), or have just integrated some extensions that are not natively available in JavaScript (for example TypeScript). The transpiling process transforms the code written with those languages to a native JavaScript code ready to be executed on modern browsers/WebViews. We currently use WebPack to perform the transpiling operations.

One of the biggest issues in the Localkit transpiling environment has been the inability to control the transpiling process management. For example, when a user selected a transpilable project, the transpiler was automatically triggered every time a change was made on that project.

We realized this may bring issues on outdated hardware. That’s why we decided to allow you to choose when to enable the automatic transpiling or pause it. You can freely manage it with the switch Enable automatic transpiling. The settings are persistent and related to each project. The status of the automatic transpiling can also be checked in the Transpiler tabbar element.

Transpiler console

It is important that you can constantly check the transpiling process log as it can help you to spot issues related to your project in real time. Before, the transpiling process log was not user-friendly because of the need to manually configure the log settings. That’s why we decided to integrate the console directly on Localkit, where you will be able to follow the progression of the whole transpiling process.

The displayed information includes:

• Transpiling status

• Creation of a new transpiling process with relative PID

• Information related to the transpiling process Kill operation

• Transpiling settings management

Moreover, the console can be easily resized and hidden, in case the developer is not interested in displaying the generated log.

Preferences dialog

1. From the Monaca Localkit menu, go to Preferences (for Mac) or File → Preferences (for Windows/Linux).

2. In the Preferences dialog, you can change the following settings:

• Working Directory: Specify a default location to store your local projects.

• Listening Port: Specify the port number to be used when pairing Monaca Localkit with Monaca Debugger.

• Project Preview Port：Specify the port number used in the preview screen.

• Proxy Server: Specify the proxy server.

• Log Output: Specify where you want to store the log file.

• Language: Specify the display language.

• Synchronize Changes: Specify the download operation after closing remote windows (Remote Build and Settings) on the Preferences menu.

• Upload Option: Specify whether a project is transpiled before uploading.

• Beacon Broadcast: Specify the beacon broadcast used when synchronizing Monaca Localkit and Monaca Debugger.

• Environment Path：Specify the node.js path if the monaca Localkit does not recognize node.js.

3. Save the settings.

Upload/download control

You might sometimes want to exclude specific files and folders from the Monaca Cloud. When using Monaca, the .monacaignore file will be automatically created and placed under the root directory of the React Native projects. You can edit the file to add or remove specific files and folders.

.monacaignore is using the same pattern as .gitignore.

The default .monacaignore file looks like this:

/.monaca/*
!/.monaca/project_info.json
/platforms
.DS_Store
*.swp
.vscode/
typings/
node_modules
.git