Vicatia-cli NPM

Vicatia-CLI

A command-line tool for Vicatia projects.

This project is intended to make it easier building cordova project with polymer.

This project is still in alpha so don't expect too much, but most of basic commands is working because it's based on polymer-cli.

Overview

Vicatia-CLI includes a number of tools for working with Polymer,Web Components and Cordova:

init - Initializes a Vicatia project from one of several templates
build - Builds an application-style project
lint - Lints the project
serve - Runs a development server
test - Runs tests with web-component-tester
platforms - Add or remove specific platform
plugin - Add or remove cordova plugin

Installation

Install via npm:

$ npm install -g vicatia-cli

Then run via vicatia <command>:

$ vicatia help

Project Structure

Vicatia-CLI is somewhat opinionated about project structure.

There are two type of projects:

Plugin projects TODO: write this when plugin environment is implemented.
Application projects
Application projects are self-contained and intended to be deployed as a standalone application. Application projects contain elements in a src/ folder and import their dependencies with absolute paths, or relative paths that reference folders inside the project folder.

Application Styles

Vicatia-CLI currently supports two styles of applications:

Monolithic applications, which have a single entrypoint (usually index.html) and eagerly import all dependencies.
"App shell" applications, which have a very lightweight entrypoint, an app-shell with startup and routing logic, and possibly lazy loaded fragments.

App-shell Structure

App-shell apps are currently the preferred style for Polymer CLI, and most commands are being optimized to support them. App-shell apps usually have client-side routing (see the app-route element), and lazy load parts of the UI on demand.

Vicatia-CLI supports this style by understand these different types of files:

entrypoint - The first file served by the web server for every valid route (usually index.html). This file should be very small, since it may not cache well and must reference resources with absolute URLs, due to being served from many URLs.
shell - The actual app shell, which includes the top-level logic, routing, and so on.
fragments - lazy loaded parts of the application, typically views and other elements loaded on-demand.

Configuration

The project files are specified either as global flags: --entrypoint, --shell and zero or more --fragment flags, or in a vicatia.json configuration file.

vicatia.json

You can specify the project files in vicatia.json so that commands like vicatia build work without flags:

{
  "rootDir": "src",
  "outDir": "www",
  "entrypoint": "index.html",
  "shell": "my-app/my-app.html",
  "fragments": [
    "app-home/app-home.html",
    "app-view-1/app-view-1.html",
  ],
  "sources": [
    "src/**/*",
    "images/**/*",
    "bower.json"
  ],
  "includeDependencies": [
    "bower_components/additional-files-to-include-in-build/**/*",
    "bower_components/webcomponentsjs/webcomponents-lite.js"
  ],
  "plugins": {
    "cordova-plugin-facebook4":{
      "version":"",
      "variable":{
        "APP_ID":"123456789",
        "APP_NAME":"myApplication"
      }
    },
    "cordova-plugin-console":{
      "version":"1.0.0"
    }
  },
  "platforms": {
    "android":{
      "version":"6.0"
    }
  }
}

Commands

help

Displays help on commands and options:

$ vicatia help

init

Initializes a Vicatia project from one of several templates.

Choose a template from a menu:

$ vicatia init

Create a new project from the 'application' template:

$ vicatia init application

install

Installs Bower dependencies, optionally installing multiple variants.

$ vicatia install

This performs a Bower install of dependencies listed in bower.json, and is equivalent to bower install.

$ vicatia install --variants

This performs a Bower install, and also installs any dependency variants specified in the "variants" property of bower.json.

lint

With a vicatia.json file:

$ vicatia lint

Specifying a file to lint:

$ vicatia lint index.html

test

Run test with web-component-tester:

$ vicatia test

build

Specify project files as flags:

$ vicatia build --entrypoint index.html --shell src/my-app/my-app.html

Use index.html as the entrypoint, or read from vicatia.json:

$ vicatia build

build is opinionated and defaults to a good build for app-shell apps. It writes the built output to build/bundled and build/unbundled folders. Both outputs have been run though HTML, JS and CSS optimizers, and have a Service Worker generated for them. The bundled folder contains the application files process by Vulcanize, Polymer's HTML bundler, for optimal loading via HTTP/1. The unbundled folder is optimized for HTTP/2 + Push.

While the build command should support most projects, some users will need greater control over their build pipeline. If that's you, check out the vicatia-build library. Vicatia-build can be called and customized programmatically, giving you much greater control than the CLI can provide.

serve

Start the development server:

$ vicatia serve

Start the development server, and open the default browser:

$ vicatia serve -o

By default the server listens to localhost. To listen to a different address use the --hostname flag. For example:

$ vicatia serve -o --hostname 0.0.0.0

platforms

Add platform into project:

$ vicatia platforms add android

Remove platforms from project:

$ vicatia platforms remove android

plugin

Install cordova plugin:

$ vicatia plugin add cordova-plugin-name

Install cordova plugin with variable:

$ vicatia plugin add cordova-plugin-name --variable VARIABLE_NAME=value

Install multiple plugins:

$ vicatia plugin add cordova-plugin-name-1 cordova-plugin-name-2

Remove cordova plugin:

$ vicatia plugin remove cordova-plugin-name

Templates and Generators

Vicatia-CLI initializes new projects with the init command, and includes a few built-in templates.

New templates can be distributed and installed via npm. Yeoman generators prefixed with generator-vicatia-init will show up in the vicatia init menu.

Compiling from Source

$ npm run build

You can compile and run the CLI from source by cloning the repo from Github and then running npm run build. But make sure you have already run npm install before building.

Supported node.js versions

Vicatia CLI targets the current LTS version (4.x) of Node.js and later.