@applicaster/zapplicaster-cli

Zapplicaster-cli

This packages contains the code for the Zapplicaster-cli tool

Usage

You can run the cli in multiple ways :

• with npx npx @applicaster/zapplicaster-cli <command> <...args> [...options]
• by installing it globally

$ npm i -g @applicaster/zapplicaster-cli
$ zapplicaster <command> <...args> [...options]

• by installing it locally in an npm package

$ npm i @applicaster/zapplicaster-cli
$ node_modules/.bin/zapplicaster <command> <...args> [...options]

commands

init

Sets up the applicaster environment. It will check installation of brew, zappifest, zapptool, yarn, nvm and node. If any of these tools aren't installed, the script will install them. This command will also prompt the user for some data required to run the App (Zapp Token, path to native folders, name of android emulators). It will also offer to clone the repositories if needed. Once all the data is configured, it is saved at ~/.applicaster.json

prepare

Prepares a workspace for a specific zapp app npx @applicaster/zapplicaster-cli prepare (<app_version_id>) [...options]

Options

• -a | --app-version-id [id]: id if the app. Required if not provided as argument to the command
• -d | --destination-path [path]: destination path to prepare the workspace. if ommitted, will render in $* {PWD}/quick-brick
• -v | --verbose: more logging output
• -y | --yarn: use yarn instead of npm to install dependencies
• -t | --template [path]: overrides the default template for the app's platform with the one located at the provided path
• -b | --build-mobile: will run zapptool / rake to prepare & build the native layer of the app

Templates

The prepare command uses templates to customise the way the workspace is bootstrapped. For a normal usage, this doesn't need to be changed, but an arbitrary template can be provided.

A CLI template is simply made of a js object with the following properties:

const template = {
  files: {
    templatePath: "", // path to where the template files are located
    filesToCopy: [], // array of files to copy, with a path relative to the templatePath above
    filesToRender: [ // array of files to render
      {
        templatePath: "", // absolute path to the ejs template file
        filePath: "", // full path of the output file, relative to the workspace root
      }, { // the filePath property can be a function which uses the configuration for the app
      // this allows to inject specific values in the file path
        templatePath: "",
        filePath: config => `customPath/${config.platform}/index.js`,
      }
    ],
  },
  dependencies: [
    // array of dependencies to add to the workspace's package.json
    {
      name: "",  // name of the dependency
      version: "", // version of the dependency
      type: "", // type of dependency - either `dependencies` or `devDependencies`
    },
    { name: "babel-core", version: "^6.26.3", type: "devDependencies" },
    { name: "react", version: "16.0.0", type: "dependencies" },
  ],
  scripts: [
    // custom scripts to inject to the workspace package.json
    {
      name: "", // script name,
      command: "", // command to run
    },
    {
      name: "start",
      command: "yarn start",
    },
  ],
  configFiles: [
    // array of custom config files to generate and put in the workspace config folder
    {
      name: "", // name of file
      getJsonContent: config => ({  ...  }) // function to get the config file's content from the CLI's configuration object. optional
    }
  ],
  remoteFiles: config => [] // function which returns an array of remote urls to save as config files. optional
}

Files are rendered with ejs. The render function is injected with an object with two properties :

• configuration: the app's CLI configuration, including Zapp's build_params
• plugins: array of plugins - data is gathered from the app's plugin_configuration and provides access to the plugin name, the npm package name & version, and the identifier

publish_plugin

npx zapplicaster-cli publish_plugin path/to/plugin [...options]

This command can be used to publish a QuickBrick plugin to Zapp. It will push the plugin to npm, generate the manifests for the supported platforms, push the zappifests to Zapp, and commit the changes to your current branches.

In order to work, you need to make sure you are logged in to npm to an account which is allowed to publish the npm package of your plugin. You also need to make sure you can run zappifest commands, which means you have the right ruby version, the latest version of zappifest, and the ZAPP_TOKEN environment variable set.

You will also need to define an applicaster property in your package.json file to declare the list of platforms which are supported by the plugin. By default, the command will try to publish all plugins at once, but you can use the -s, --single-platform flag to target only one platform. However, if you ask the script to publish the plugin for a single platform, the script will not let you publish to a platform that is not listed in the supported platforms.

// package.json

{
  "name": "my-awesome-plugin",
  "version": "1.5.0",
  "applicaster": {
    "supportedPlatforms": ["ios", "android", "tvos", "samsung"],
    "zappOwnerAccountId": "<plugin owner account from zapp>"
  }
}

NOTE: android tv, amazon fire and android share the same android platform value

The main benefit of this command is that it allows you to consolidate all your manifest information in a single file. Your plugin should have a manifests folder at its root, which contains a manifest.config.js file. this file should export a function which can render the zappifest for a given platform and version, like this:

// <plugin_root>/manifests/manifest.config.js

module.exports = function({ platform, version }) {
  const manifest = {
    api: {},
    manifest_version,
    platform,
    identifier: "my_plugin_identifier",
    dependency_name: "my-awesome-plugin",
    dependency_version: version,
    /* you can put here all the fields which are common to all platforms */
  };

  if (platform === "ios") {
    manifest.npm_dependencies = [`my-awesome-plugin@${version}`];
    manifest.extra_dependency = {
      MyNativeModule: ":path => ./path/to/podspec/MyNativeModule.podspec",
    };
  }

  return manifest;
};

options

• -v, --version [version] mandatory the version you want to set for your plugin. it is required to input this in order to avoid interactive shell commands when running on CI containers or such
• -y, --yarn: will publish with yarn instead of npm. only npm supports dry-runs
• -d, --dry-run: will run the task but skip all the shell commands and file generation. will output to the log instead to see if the expected result is achieved
• -p, --plugin-path plugin path can be set with this flag as well as the first command argument
• -n, --next will publish to the npm registry in the next channel, using the --tag next option. useful for prerelease versions
• g, --skip-git will run all the steps, but won't commit the changes. In order to avoid issues with git, if this flag is not set, the command won't run unless the git tree is clean
• -s, --single-platform By default, the command will publish all the supported platforms defined in the plugin's package.json file. This flag lets you publish for a single platform

run

This command runs a Quick Brick app in the emulator. Can be used in conjunction with the react-native start script @applicaster/zapplicaster-cli run <android> & yarn start

Accepts a single argument, the name of the platform to run the app on available values are ios, tvos, android, androidTv, amazon.

Requires having ran the init command before.

reload_config

This command will do like prepare but without bootstrapping the app. This is very useful when working on a project where you need to reload the configuration from zapp but without generating the project's entry point again.

Keep in mind though that if you add / remove plugins, you will have to manually update the imports statements in your project.

options :

• -a | --app-version-id [id]: id if the app. Required if not provided as argument to the command
• -d | --destination-path [path]: destination path to prepare the workspace. if ommitted, will render in $* {PWD}/quick-brick
• -v | --verbose: more logging output